From 9e3e89f87a80b716aaf291c34687ac13e871030f Mon Sep 17 00:00:00 2001 From: Sutu Sebastian Date: Mon, 4 May 2026 15:37:17 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20lockstep=20cleanup=20=E2=80=94=20drop?= =?UTF-8?q?=20fallow=20as=20positioning=20yardstick=20across=20remaining?= =?UTF-8?q?=20surfaces?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Audit of remaining `[Ff]allow` references after PRs #58, #61, #62 landed found 4 surfaces still treating fallow as a positioning peer (off-mission under the cohort framing locked in by PR #58): CLEANED UP: - docs/why-codemap.md:23 — non-goal parenthetical "(those are different products — e.g. fallow, knip, jscpd)" still elevated fallow as the primary static-analysis exemplar. Mirrors the PR #62 roadmap.md fix (lockstep per docs/README.md Single source of truth — non-goals canonical home is roadmap.md; consumer-facing framing in why-codemap.md must follow). Now: "(those are different products — e.g. knip, jscpd)". - docs/glossary.md:36 (audit definition) — "Distinct from `fallow audit` (that runs code-quality verdicts...)" singled out fallow as the comparator. Generalized to "Distinct from code-quality audit tools (e.g. knip for unused exports, jscpd for duplication, framework- specific complexity linters)". Same product-class point; no peer yardstick. - .agents/rules/docs-governance.md:36 — "(fallow, future plugins)" as the canonical example of repo-wide tool adoption was stale (fallow.md closed in PR #61). Updated to "(oxlint, future plugins)" + added a closure-precedent note pointing at fallow.md's status header and non-goals-reassessment-2026-05.md for current positioning. - .agents/skills/docs-governance/SKILL.md:86,88,136 — same staleness: "fallow" as ongoing-tracker example was stale; "fallow audit" in the re-derivable test list. Updated to oxlint + generic "static-analysis tooling"; preserved the fallow.md cross-ref as the CLOSED precedent (research notes that close with status header when peer framing goes off-mission). LEFT ALONE (legitimate): - docs/why-codemap.md:110-121 (comparison table) — different-product- classes consumer framing (Codemap vs fallow vs Aider RepoMap vs LSP). Not a peer yardstick under the cohort positioning; "agents can use Codemap AND fallow AND LSP" framing is honest about distinct slots. - docs/research/fallow.md (closed historical) — body preserved per PR #61. - docs/research/competitive-scan-2026-04.md (closed historical scan). - .agents/lessons.md:16 — "Never commit absolute local user paths" lesson with PR #58 historical context referencing the fallow clone path. Historical record; preserve. - .agents/skills/audit-pr-architecture/SKILL.md (5 mentions) — recommends `bunx fallow audit` as a static-analysis TOOL during PR audits. Different-product-class tool recommendation, not positioning. Borderline; left alone for now (could be genericized later as a separate concern). Net effect: every remaining `[Ff]allow` reference in the repo is either historical (closed research, lessons) or a different-product- class acknowledgement (consumer comparison table, static-analysis tool usage). Zero peer-yardstick framing remains in the load-bearing positioning surfaces. --- .agents/rules/docs-governance.md | 2 +- .agents/skills/docs-governance/SKILL.md | 6 +++--- docs/glossary.md | 2 +- docs/why-codemap.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.agents/rules/docs-governance.md b/.agents/rules/docs-governance.md index 884cdfb..e4dee1f 100644 --- a/.agents/rules/docs-governance.md +++ b/.agents/rules/docs-governance.md @@ -33,7 +33,7 @@ The canonical Rules (1–9) live in [`docs/README.md`](../../docs/README.md) — 1. **Anchor preservation** — slim READMEs keep cited rule numbers and section anchors. Grep before any slim: `rg "Rule [0-9]+" docs/` and `rg "(#[a-z-]+)?"`. 2. **Anti-bloat meta-rule** — don't add a rule until there's content that needs it. Same for ownership-table rows. -3. **Repo-level vs in-source** — repo-wide tool evaluations + adoption (fallow, future plugins) live in `.agents/`, not as permanent `docs/research/` files. A `docs/research/` file may motivate the adoption, but the rule + skill earn the permanent home. +3. **Repo-level vs in-source** — repo-wide tool evaluations + adoption (oxlint, future plugins) live in `.agents/`, not as permanent `docs/research/` files. A `docs/research/` file may motivate the adoption, but the rule + skill earn the permanent home. (Precedent: [`research/fallow.md`](../../docs/research/fallow.md) was closed in 2026-05 once peer-tool framing went off-mission — its tracker shape is no longer the ongoing-research pattern; for current positioning see [`research/non-goals-reassessment-2026-05.md`](../../docs/research/non-goals-reassessment-2026-05.md).) ## Existence test (apply on every doc-touching PR) diff --git a/.agents/skills/docs-governance/SKILL.md b/.agents/skills/docs-governance/SKILL.md index 93e7147..21ce1bc 100644 --- a/.agents/skills/docs-governance/SKILL.md +++ b/.agents/skills/docs-governance/SKILL.md @@ -83,9 +83,9 @@ Same applies to ownership-table rows — a row exists when the file or folder it ### 6. Repo-level vs in-source clarification -**Codemap-wide tool evaluations + adoption** (e.g. fallow, oxlint, future plugins) belong directly in `.agents/rules/` + `.agents/skills/` — not in `docs/research/`. The artifact that earns a permanent home isn't the evaluation; it's the rule + skill. +**Codemap-wide tool evaluations + adoption** (e.g. oxlint, future plugins) belong directly in `.agents/rules/` + `.agents/skills/` — not in `docs/research/`. The artifact that earns a permanent home isn't the evaluation; it's the rule + skill. -A `docs/research/` file may **motivate** adoption of a repo-level tool (the precedent is [`research/competitive-scan-2026-04.md`](../../../docs/research/competitive-scan-2026-04.md), which drove PR #23), but the _adoption itself_ is repo-level — the rule lands under `.agents/rules/`, not as a permanent doc under `docs/research/`. The research note then either slims to "what shipped" (per [`docs/README.md` Rule 8](../../../docs/README.md)) or stays open as an ongoing tracker (the [`research/fallow.md`](../../../docs/research/fallow.md) shape). +A `docs/research/` file may **motivate** adoption of a repo-level tool (the precedent is [`research/competitive-scan-2026-04.md`](../../../docs/research/competitive-scan-2026-04.md), which drove PR #23), but the _adoption itself_ is repo-level — the rule lands under `.agents/rules/`, not as a permanent doc under `docs/research/`. The research note then slims to "what shipped" (per [`docs/README.md` Rule 8](../../../docs/README.md)) — or, if peer-tool framing goes off-mission entirely, closes with a status header and a pointer at the new canonical positioning home (the [`research/fallow.md`](../../../docs/research/fallow.md) precedent — closed 2026-05 when codemap's positioning shifted from "adoption-from-fallow" to its own intrinsic differentiation; see [`research/non-goals-reassessment-2026-05.md`](../../../docs/research/non-goals-reassessment-2026-05.md)). ### 7. Cross-reference preservation discipline @@ -133,7 +133,7 @@ Codemap doesn't ship an `audits/` folder today. When the first audit lands, choo | **Single-file `audit.md`** | One rolling audit doc | When all open items resolve: lift deferred items to `roadmap.md`; **slim** closed findings to durable policy + cited-from-source bits; keep "Last verified" header current | | **Multi-file `audits/.md`** | Multiple targeted audit passes worth keeping side-by-side | Per audit: **No source cites AND no unique policy** → digest deferred items into `roadmap.md` (or absorb into a reference doc), then **delete** the audit file (don't leave a tombstone). **Has source cites OR unique policy** → **slim** to the cited findings + the durable policy; add a `Status: Closed` header; file stays in `audits/`. Index closed audits from `roadmap.md § Closed audits (pointers)` | -**The re-derivable test (positive framing of "no source cites AND no unique policy").** Before keeping a closed audit, ask: _would a fresh audit run today re-derive every finding from current code (codemap query, fallow, grep, schema)?_ If yes and nothing in source points back to this file by name, the audit's only remaining job is historical archaeology — `git log --follow` does that better than a stale snapshot. **Delete it.** Three things an audit can carry that the codebase cannot infer, and that earn a slim+keep: +**The re-derivable test (positive framing of "no source cites AND no unique policy").** Before keeping a closed audit, ask: _would a fresh audit run today re-derive every finding from current code (codemap query, static-analysis tooling, grep, schema)?_ If yes and nothing in source points back to this file by name, the audit's only remaining job is historical archaeology — `git log --follow` does that better than a stale snapshot. **Delete it.** Three things an audit can carry that the codebase cannot infer, and that earn a slim+keep: 1. **Decisions of record** with rejected alternatives ("we kept X at root because Y; the Z alternative was considered and rejected because…"). Code shows the result, not the rejection rationale. 2. **Source-back-references** — `NOTE(...)` markers, JSDocs, or test names that cite the audit by file. Deletion would orphan them. diff --git a/docs/glossary.md b/docs/glossary.md index bfd510e..70ee76e 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -33,7 +33,7 @@ A `.agents/rules/.md` file with YAML frontmatter. Distinct from a **skill* ### audit -Two-snapshot structural-drift command: `codemap audit` diffs the live `.codemap/index.db` against a base snapshot and emits `{head, deltas}` where each `deltas[]` carries `{base, added, removed}`. v1 ships three deltas: `files`, `dependencies`, `deprecated`. Each delta pins a canonical SQL projection (in `V1_DELTAS`) and a required-columns list — projects baseline rows down to that subset before diffing so schema bumps that add columns don't break pre-bump baselines. Three mutually-exclusive top-level snapshot sources: `--baseline ` (auto-resolve `-files` / `-dependencies` / `-deprecated` from `query_baselines`), `---baseline ` (explicit per-delta — composes with the others), and `--base ` (worktree + reindex against a git committish — see § A `audit --base`). Distinct from `codemap query --baseline` (that's one query, one diff; audit composes multiple per-delta diffs into one envelope). Distinct from `fallow audit` (that runs code-quality verdicts — dead code, dupes, complexity — which are explicit non-goals per [`roadmap.md` § Non-goals (v1)](./roadmap.md#non-goals-v1); codemap audit stays structural). +Two-snapshot structural-drift command: `codemap audit` diffs the live `.codemap/index.db` against a base snapshot and emits `{head, deltas}` where each `deltas[]` carries `{base, added, removed}`. v1 ships three deltas: `files`, `dependencies`, `deprecated`. Each delta pins a canonical SQL projection (in `V1_DELTAS`) and a required-columns list — projects baseline rows down to that subset before diffing so schema bumps that add columns don't break pre-bump baselines. Three mutually-exclusive top-level snapshot sources: `--baseline ` (auto-resolve `-files` / `-dependencies` / `-deprecated` from `query_baselines`), `---baseline ` (explicit per-delta — composes with the others), and `--base ` (worktree + reindex against a git committish — see § A `audit --base`). Distinct from `codemap query --baseline` (that's one query, one diff; audit composes multiple per-delta diffs into one envelope). Distinct from code-quality audit tools (e.g. `knip` for unused exports, `jscpd` for duplication, framework-specific complexity linters) — those produce verdicts on dead code / dupes / complexity, which are explicit non-goals per [`roadmap.md` § Non-goals (v1)](./roadmap.md#non-goals-v1); codemap audit stays structural. ### `audit --base ` / git-ref baseline diff --git a/docs/why-codemap.md b/docs/why-codemap.md index 2add59c..dbcc9bd 100644 --- a/docs/why-codemap.md +++ b/docs/why-codemap.md @@ -20,7 +20,7 @@ Codemap is intentionally narrow. It is **not**: - **Full-text search** — use `ripgrep` / your IDE for raw string queries on file bodies. - **A language server (LSP)** — no rename, no go-to-definition wired to your editor, no hover types. - **An AI agent** — Codemap does not reason, decide, or generate. Agents call Codemap; Codemap does not call agents. -- **A static analyzer** — no dead-code detection, duplication detection, complexity scoring, or boundary enforcement (those are different products — e.g. [fallow](https://github.com/fallow-rs/fallow), `knip`, `jscpd`). +- **A static analyzer** — no dead-code detection, duplication detection, complexity scoring, or boundary enforcement (those are different products — e.g. `knip`, `jscpd`). - **A semantic / embedding index** — no vector search, no PageRank summarization, no "what's relevant" inference. - **A replacement for reading code** — the index returns paths, line ranges, signatures; the agent still reads the snippets it needs.