Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agents/rules/docs-governance.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 "<doc-path>(#[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)

Expand Down
6 changes: 3 additions & 3 deletions .agents/skills/docs-governance/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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/<topic>.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.
Expand Down
2 changes: 1 addition & 1 deletion docs/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ A `.agents/rules/<name>.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[<key>]` 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 <prefix>` (auto-resolve `<prefix>-files` / `<prefix>-dependencies` / `<prefix>-deprecated` from `query_baselines`), `--<delta>-baseline <name>` (explicit per-delta — composes with the others), and `--base <ref>` (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[<key>]` 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 <prefix>` (auto-resolve `<prefix>-files` / `<prefix>-dependencies` / `<prefix>-deprecated` from `query_baselines`), `--<delta>-baseline <name>` (explicit per-delta — composes with the others), and `--base <ref>` (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 <ref>` / git-ref baseline

Expand Down
2 changes: 1 addition & 1 deletion docs/why-codemap.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Loading