Skip to content

Commit e3e511d

Browse files
SutuSebastianSutuSebastian
committed
docs: record leftover fact-check findings in audits/
Track R.1–R.12 residuals from the May 2026 markdown audit with cross-links from docs/README and roadmap backlog.
1 parent 0f7e6fc commit e3e511d

3 files changed

Lines changed: 58 additions & 1 deletion

File tree

‎docs/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ Each topic has exactly one canonical file. Other files cross-reference by relati
2222
| [packaging.md](./packaging.md) | **`CHANGELOG.md` / `dist/` / `templates/`** on npm, **engines**, [**Node vs Bun**](./packaging.md#node-vs-bun), [**Releases**](./packaging.md#releases) (Changesets; **`bun run version`** + oxfmt **`CHANGELOG.md`**). |
2323
| [roadmap.md](./roadmap.md) | Forward-looking [**Backlog**](./roadmap.md#backlog) and [**Non-goals**](./roadmap.md#non-goals-v1) (not a `src/` inventory). |
2424
| [plans/](./plans/) | One `<feature-name>.md` per in-flight plan. Created on demand — don't add the `-plan` suffix; the folder provides context. See folder contents for the current in-flight set; avoid maintaining a duplicate inline list. |
25-
| [audits/](./audits/) | Targeted architecture / performance / lifecycle audits. Open findings stay here until resolved; closed audits follow the audit lifecycle in the docs-governance skill. |
25+
| [audits/](./audits/) | Targeted architecture / performance / lifecycle audits. Open: [`audits/2026-05-24-docs-fact-check-residuals.md`](./audits/2026-05-24-docs-fact-check-residuals.md). Closed audits indexed from [`roadmap.md` § Closed audits (pointers)](./roadmap.md#closed-audits-pointers). |
2626
| [research/](./research/) | Dated, snapshot-style notes (e.g. competitive scans, non-goals reassessments). Each note links shipped items back to canonical homes — see [research/non-goals-reassessment-2026-05.md](./research/non-goals-reassessment-2026-05.md). |
2727

2828
---

‎docs/audits/2026-05-24-docs-fact-check-residuals.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Docs fact-check residuals — 2026-05-24
2+
3+
**Status:** Open — low-priority items deferred after the May 2026 full `.md` audit.
4+
5+
**Scope:** ~129 markdown files under `docs/`, `.agents/`, `templates/`, root, and `.github/`. Parent verification on `main` through `0f7e6fc`.
6+
7+
**Method:** Five parallel fact-check passes against `src/`, `package.json`, CI workflows, and `templates/recipes/`; manual diff review for information loss.
8+
9+
**Shipped in audit commits:** `e6ab158`, `3c65a65`, `0f7e6fc` — glob/batchInsert corrections, `--base` git-archive wording, MCP vs HTTP resource split, plan status headers, agent-content path fixes, recipe example SQL, rule frontmatter, synthesis Step 1 closure.
10+
11+
This audit follows [docs/README.md Rule 6](../README.md) and [docs/README.md Rule 7](../README.md).
12+
13+
---
14+
15+
## TL;DR
16+
17+
The audit corrected stale/wrong prose without dropping load-bearing design. **11 residual items** remain — mostly code/doc drift and STYLE nits. None block releases; three want code changes when touched next.
18+
19+
---
20+
21+
## Residual findings
22+
23+
### Code fixes (docs partially or fully updated)
24+
25+
| ID | Finding | Evidence | Suggested fix | Effort |
26+
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ |
27+
| **R.1** | **Project recipes ignore custom `--state-dir`.** Docs now say `<projectRoot>/.codemap/recipes/`; loader hardcodes that path. | `resolveProjectRecipesDir()` in `src/application/query-recipes.ts` — `join(projectRoot, ".codemap", "recipes")` only. | Honor `resolveStateDir()` when resolving project recipe dir, or document permanently that recipes are `.codemap`-scoped only. | S |
28+
| **R.2** | **`function_params.owner_kind` never varies.** Recipe doc updated; extractor always passes `"function"`. | `pushParams()` default in `src/extractors/params.ts`; all call sites omit `ownerKind`. | Populate distinct values (`method`, `arrow`, `constructor`, …) at extraction sites, then restore filter docs on `find-by-param-type`. | M |
29+
| **R.3** | **MCP stdio does not register `codemap://files/{path}` / `codemap://symbols/{name}`.** README and glossary correctly scope these to HTTP `GET /resources/{uri}`; `readResource()` supports them but `registerResources()` does not. | `src/application/mcp-server.ts` vs `src/application/resource-handlers.ts`. | Either register as MCP resource templates (parity with HTTP) or keep HTTP-only and ensure agent-content skill states the split (done in README). | S (if registering) |
30+
31+
### Doc-only (STYLE / accuracy nits)
32+
33+
| ID | Finding | Location | Suggested fix |
34+
| ------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------- |
35+
| **R.4** | Example timing tables will drift. | `docs/benchmark.md` Results section | Optional callout: regenerate via `bun src/benchmark.ts`; numbers are snapshots, not CI-gated. |
36+
| **R.5** | "Main tables" copy counts five tables; index has more. | `templates/recipes/index-summary.md` description | Say "core tables" or list which five; or point at `index-summary.sql`. |
37+
| **R.6** | Relative `./unimported-exports.md` link may not resolve in MCP/`--recipes-json` body consumers. | `templates/recipes/unused-type-members.md` | Use recipe id prose only, or absolute path in bundled context if a consumer breaks. |
38+
| **R.7** | Root README env block omits `CODEMAP_STATE_DIR`, `CODEMAP_WATCH`. | `README.md` Configuration inline block | One-line mention if users hit custom state-dir or watch opt-out often. |
39+
| **R.8** | Substrate plan ship dates mix 2026-05-14 / 15 / 19. | `docs/plans/substrate-extraction.md` tier headers | Normalize to wave date where one SCHEMA bump covers multiple tiers. |
40+
| **R.9** | Research note jumps §3 → §5 → §7 (§4/§6 lifted). | `docs/research/non-goals-reassessment-2026-05.md` | Optional one-line TOC note: "§4/§6 lifted to roadmap/plans." |
41+
42+
### Already tracked elsewhere (no new work)
43+
44+
| ID | Item | Canonical home |
45+
| -------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
46+
| **R.10** | GitHub Marketplace Slice 5 (tags, `MARKETPLACE.md`) | [`roadmap.md` Backlog](../roadmap.md#backlog) · [`plans/github-marketplace-action.md`](../plans/github-marketplace-action.md) |
47+
| **R.11** | C.9 `files.is_entry`, plugin loader, reachability recipes | [`plans/c9-plugin-layer.md`](../plans/c9-plugin-layer.md) |
48+
| **R.12** | Apply-engine synthesis Steps 2–12 | [`research/codemap-richer-index-synthesis-2026-05.md`](../research/codemap-richer-index-synthesis-2026-05.md) §6 |
49+
50+
---
51+
52+
## Closing criteria
53+
54+
Delete this file when **R.1–R.3** are resolved or explicitly rejected with a one-line decision in `roadmap.md`, and **R.4–R.9** are either fixed or accepted as intentional. Index closure in [`roadmap.md` § Closed audits (pointers)](../roadmap.md#closed-audits-pointers).
55+
56+
Recover the full May 2026 audit agent reports via conversation / commit diffs at `f25f8a6..0f7e6fc` if needed.

‎docs/roadmap.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ Soft constraints — describe shipped reality. Decided-but-unshipped flips live
5252

5353
## Backlog
5454

55+
- [ ] **Docs fact-check residuals (2026-05-24)** — low-priority drift from the full `.md` audit (`e6ab158`–`0f7e6fc`): project-recipes + `--state-dir` loader (R.1), `owner_kind` extraction (R.2), optional MCP `files`/`symbols` resource registration (R.3), plus six STYLE doc nits. Audit: [`audits/2026-05-24-docs-fact-check-residuals.md`](./audits/2026-05-24-docs-fact-check-residuals.md). Effort: S–M per item.
5556
- [ ] **`history` table** (deferred — revisit-triggered) — temporal queries: "when did symbol X get `@deprecated`?", "coverage trend over last 50 commits", "files that became dead this week". `audit --base <ref>` covers the most-common temporal question (PR-scoped diff) without schema growth, so the table earns its place only when bigger questions emerge. Two shapes (per-commit snapshots ~N × DB size; append-only event log heavier CTE walks); both pay an N-reindexes backfill cost (~30s per reindex). **Revisit triggers:** two consumers ship `jq`-based "audit-runs-over-time" workflows, OR `query_baselines` evolution becomes a recurring agent need.
5657
- [ ] **`codemap audit` verdict + thresholds** (v1.x) — `verdict: "pass" | "warn" | "fail"` driven by an `audit.deltas[<key>].{added_max, action}` field on the config object (`.codemap/config.{ts,js,json}`). Triggers: two consumers ship `jq`-based threshold scripts with similar shapes, OR one consumer asks with a concrete config sketch. Until then, raw deltas + consumer-side `jq` is the CI exit-code idiom. **Likely accelerant:** the Marketplace Action (next item) shipping is the most plausible path to firing the trigger — once `- uses: stainless-code/codemap@v1` is the dominant CI path, real `jq` threshold scripts will surface.
5758
- [ ] **GitHub Marketplace Action — publish + listing finish** — core Action implementation is in-tree: root `action.yml`, `query --ci`, `audit --format sarif` / `--ci`, package-manager detection, dogfood smoke, and opt-in `pr-comment` summary renderer have shipped. Remaining work is the release/listing slice: `MARKETPLACE.md`, `v1.0.0` / floating `v1` tags, Marketplace setup, sacrificial-repo smoke, and making `action-smoke` blocking once the Action tag exists. Action version stream is independent of CLI version (`package.json` currently drives CLI/npm version; Action publishes at its own `v1.0.0`). Plan: [`plans/github-marketplace-action.md`](./plans/github-marketplace-action.md). Effort: S.

0 commit comments

Comments
 (0)