---
name: wiki-doc
description: >
3-level documentation protocol for LLM-assisted codebases. Builds and maintains a
structured knowledge base (module index → function index → function docs) that any
LLM agent can navigate with minimal context loading. Supports two pass types:
doc-only passes (no source edits) and edit-enabled passes (small fixes surfaced
during documentation, gated by an explicit suggest-approve-apply-verify-log protocol).
Use this skill whenever the user wants to: create documentation for a codebase or
module, build a knowledge base from code review sessions, set up structured docs
that stay synchronized with source code, run a "salvage" documentation pass on
existing reviewed code, maintain or refresh existing wiki-doc documentation after
code edits, trace variable/argument relationships across modules, generate AST-based
function indexes, or audit a module for duplicates and dead code before documenting it.
Trigger phrases: "wiki-doc", "3-level docs", "function index", "salvage documentation",
"Level 2 index", "Level 3 docs", "document this module", "create the variable map",
"refresh line numbers", "audit this module before documenting", "edit-enabled doc pass".
---
# Wiki Documentation Protocol — v1
A 3-level documentation system in which an LLM agent builds and maintains a persistent
knowledge base for a codebase, structured around functions and their relationships.
Updates propagate bottom-up from source code; the maintenance cost is near zero so the
docs stay current. The human curates, verifies, and directs. The agent handles bookkeeping.
This protocol covers two distinct working modes:
- **Doc-only pass:** the agent reads source and writes documentation. Source files are not
modified.
- **Edit-enabled pass:** the agent may apply small, clearly-safe source fixes (dead-code
deletion, comment cleanup, unambiguous renames) that surface during the doc pass — gated
by an explicit suggest → approve → apply → verify → log protocol. Larger fixes are out of
scope and routed to a dedicated debug session.
Conceptual lineage: Karpathy's llm-wiki (persistent agent-maintained wiki), MemPalace
(hierarchical retrieval for bounded-context agents), Obsidian (interlinked markdown).
---
## Section 1 — Triggers and scope
### When to use this skill
- A codebase needs documentation created after the fact (post-hoc or "salvage").
- An existing wiki-doc'd codebase needs maintenance after source edits.
- A code review surfaced knowledge worth preserving in structured form.
- A function/variable trace needs to span multiple modules with bounded context.
- Line numbers in the index drift from source and need an authoritative refresh.
- A module needs an upfront duplicate / dead-code audit before documentation begins.
### When NOT to use this skill
- One-off code explanations or single-file overviews — write a comment or short doc.
- API reference generation from docstrings — use a dedicated tool (Sphinx, etc.).
- Code review itself — this skill consumes the output of code review, it doesn't perform it.
- Generating tests, lint configs, or build artifacts.
### Two pass types
The skill supports both **doc-only** passes and **edit-enabled** passes. Doc-only is the
default: source is read but never modified. Edit-enabled fires only when the human
explicitly opts in for a session and only for fixes within the in-scope category defined in
Section 8. Anything ambiguous defaults to doc-only.
---
## Section 2 — Three-level architecture
```
Level 1 — Module Index (index.md)
Entry point. Catalogs modules with version, date, status. Staleness detector.
Read FIRST on every session.
│
├──▶ Level 2a — Function Index (per module)
│ Every function: name, AST-generated line number, scope, brief description,
│ call relationships, status. Working layer for most agent tasks.
│ Append-only changelog at bottom.
│
└──▶ Level 2b — Variable & Definition Map (per module)
Module-level variables, closure-scoped state, shared dicts, hidden
dependencies. Human-triggered creation. Class-section L2b template
supports class-instance state (Section 5.5).
│
▼
Level 3 — Function & Variable Documentation (per module)
Full per-function entries (scope, args, returns, description, upstream, downstream,
dev notes, last-edit footer). Variable entries use `### VAR:` heading prefix.
Appendices for high-density workflow tables (Section 6.6). Future Considerations
appendix for forward-looking content (Section 6.7).
Ground truth. Edits originate here and propagate upward.
```
### Update propagation (bottom-up)
```
Source code edit
→ Level 3 updated (description, args, returns, dev notes, last-edit footer)
→ AST script runs → Level 2a/2b line numbers auto-refresh
→ Level 2a changelog gets one-line entry
→ Level 2b updated if shared variables affected
→ Level 1 last-updated date bumped, version incremented if applicable
```
### Read paths
- **Session start:** Read Level 1 first; identify modules relevant to the current task;
spot-check version/date consistency.
- **Most tasks:** Resolve at Level 2a (function lookup, call-chain tracing, cross-module
workflow assembly).
- **Deep dives:** Sub-agent dispatched with specific function name(s) → reads matching
Level 3 entry by heading → cross-references source. Never reads full Level 3 file.
- **Variable trace:** Read Level 2b for the relevant module; descend to Level 3 for full
variable docs only when needed.
---
## Section 3 — File structure & naming
### Default layout
```
project_root/
├── index.md # Level 1
├── indexes/
│ ├── <module_name>.md # Level 2a — function index
│ ├── <module_name>_vars.md # Level 2b — variable map
│ └── ...
├── docs/
│ ├── <module_name>_docs.md # Level 3 (appendices at bottom)
│ └── ...
├── tools/
│ └── ast_index.py # AST extraction script (Section 21)
├── handoff/
│ ├── s1_dump_<module>_<date>.md # Salvage Phase S-1 output
│ ├── session_report.md # Active session report (Section 13)
│ ├── fixes_log.md # Edit-enabled fix history (Section 8)
│ ├── <module>_line_deltas.md # Cascade tracking (Section 9)
│ ├── <module>_deadcode.md # Dead-code findings (Section 8)
│ ├── <project>_skill_gaps.md # Protocol deferrals (Section 19)
│ └── ...
└── .claude/
└── wiki-doc.config.yaml # Project config (Section 4)
```
### Naming conventions
- Level 2a function index: `<module_name>.md` (no suffix).
- Level 2b variable map: `<module_name>_vars.md`.
- Level 3 docs: `<module_name>_docs.md` (singular `_docs`, distinguishes from L2a `<module>.md`).
- Bug findings filed during doc pass: `<name>bug.md` (e.g., `excepthookbug.md`) — short
identifier + `bug.md` suffix. Status banner at top: `**Status:** OPEN | RESOLVED <date>`.
- Dead-code clusters: `<module>_deadcode.md`, append-only, organized by cluster number.
### Project-config overrides
All paths above are overridable via the project config (Section 4). The defaults are
recommendations — a project may relocate `handoff/` to `docs/internal/`, rename
`indexes/` to `index/`, etc. The skill reads the config at session start; nothing in this
file is hard-coded as a path.
---
## Section 4 — Configuration surface
### Why a config file
Project-stable decisions live in a versioned file in the project, not in the agent's
session memory. This way: (a) any agent reading the project sees the same config, (b)
decisions survive across sessions and machines, (c) humans can audit and edit the file
directly, (d) the file travels with the project (Git, sync).
### File location
Default path: `.claude/wiki-doc.config.yaml` at project root. Overridable via the
`config_path` environment variable or skill argument; if neither, the default is used.
YAML chosen for human-readable comments alongside structured keys — projects benefit from
"we picked frozen because…" annotations next to the values.
### Required vs optional fields
The shipped template (`wiki-doc.config.template.yaml`) marks each field as `# REQUIRED`
or `# OPTIONAL` with the default value or `(no default — must be supplied)` inline.
- **Required fields** must be present in the project config. If absent, the agent asks
the user during session startup (batched in a single message), then writes the answers
back to the config file with the user's approval.
- **Optional fields** fall back to skill defaults if absent.
### Session-start behavior
1. Agent reads the project config from the configured path.
2. If the file is absent: assume defaults for all optional fields; ask the user for all
required fields; write a starter config with the answers.
3. If the file is present: load it; for each missing required field, ask in a single
batched message; write answers back with approval.
4. For enum fields (e.g., `last_edit_range: frozen | auto_shift`), use the multi-choice
prompt mechanism if the host environment supports it; otherwise free-form ask.
5. Agent reports loaded config in one line at session start: e.g., "Loaded
`.claude/wiki-doc.config.yaml` — frozen Last-edit anchors, fixes_log at
`handoff/fixes_log.md`, 2 required fields supplied this session and written back."
### What the config controls
- Path conventions (handoff dir, fixes_log path, indexes dir, deadcode pattern, archive
dir).
- Verification commands (pre-edit rule list, post-edit command list).
- Cascade policy (`last_edit_range`, optional `frozen_anchor_prefix`).
- Source-internal metadata (field names, format, bump rules).
- Style (appendix line threshold, depth-calibration knobs).
- Session report (suffix convention, archive path).
- Doc field labels for localization (e.g., `description` → `說明`).
See the shipped template for the full key list with descriptions and defaults.
---
## Section 5 — Required fields per level
### 5.1 Level 1 — Module Index fields
| Field | Description |
|-------|-------------|
| Module name | File name (e.g. `mymodule.py`) |
| Path | Relative path from project root |
| Brief description | One line — what this module does |
| Version | Version string from source (if present in file header) |
| Last-updated date (index) | When this index entry was last reviewed |
| Last-modified date (file) | From filesystem (`stat` or `ls -l`) |
| Level 2a path | Path to function index, or `—` if not yet created |
| Level 2b path | Path to variable map, or `—` if not yet created |
| Level 3 path | Path to function docs, or `—` if not yet created |
| Status | `active` / `in-progress` / `archived` / `not-reviewed` |
### 5.2 Level 2a — Function Index fields
| Field | Description |
|-------|-------------|
| Function name | As defined in source |
| Line number | Auto-generated via AST — never manually maintained |
| Scope | Auto-detected by AST (`top`, `cls:Class`, `cls:Class (in <method>)`, `cl:<closure>`, `cl:<closure> (in <inner>)`) |
| Brief description | One line |
| Status | `documented` / `pending` / `stub` / `deleted` |
| Last updated | Date of last Level 3 edit for this function |
The `deleted` status preserves a breadcrumb when a def is removed via Section 8 edits —
keeps the row in L2a so future readers don't ask "where did X go?" Treat `deleted` rows
as deprecated breadcrumbs: retain them across several version cycles (e.g., v1.0 →
v1.6) so users updating from older versions don't lose a needed reference. A periodic
cleanup pass purges them only after enough versions have shipped that downstream
readers won't be affected.
### 5.3 Level 2b — Variable Map fields
| Field | Description |
|-------|-------------|
| Variable name | As used in source |
| Line number | Auto-generated via AST `--vars` (Section 15) |
| Defined at | Module-level / closure / class / unpacked from file |
| Type | Data type (if inferrable or documented) |
| Scope rule | `global` / `nonlocal` / `local` / `closure` |
| Owner | Function or scope that creates/initializes it |
| Readers | Functions that read this variable |
| Writers | Functions that modify this variable |
| Inter-module flow | If passed to/from other modules, which and how |
| Notes | Hidden dependencies, implicit contracts, gotchas |
### 5.4 Level 3 — Function entry minimum-fields template
Every L3 function entry has these fields. Fields with no content show the field name with
`—` rather than being omitted (skip-resistance: even an empty field is salient).
```markdown
### function_name
**Scope:** [auto-detected scope tag]
**Arguments:**
- `arg_name` (type): description
- (or `none` for no-args)
**Returns:** type — description (or `None — side effect: [description]`)
**Description:**
[Concise prose: what it does, why it exists, non-obvious behavior. For high-density
functions, refer to the appendix instead of expanding here.]
**Upstream:**
- Line N — caller_function (intra-module) or caller_module.caller (inter-module)
- (or `—` if unused / entry-point)
**Downstream:**
- intra-module: helper_a, helper_b
- inter-module: other_module.fn_x
- (or `—` if leaf function)
**Dev notes:**
[Categorized — see Section 6.3. If no dev notes warranted: omit the field, do not pad.]
**Last edit:** YYYY-MM-DD — [one-line description; date frozen unless cascade policy
configured to auto_shift, in which case the line range below also shifts]
```
### 5.5 Class-section L2b template (External resource refs)
For classes (or class-bodied closures), L2b extends with a class-section using a 4-subsection
structure. Subsections are optional — if a class has no resource refs, omit that subsection
rather than padding it.
```markdown
## Section <Letter> — `<ClassName>` instance state
### Construction params
[Fields populated from constructor arguments. Example: `flag_vars` (dict, set in __init__).]
### Lifecycle flags
[Boolean / state flags governing the instance's lifecycle. Example: `is_open` (bool, set
True in __init__, flipped False in close()).]
### Mutable state
[Containers and values mutated post-construction. Example: `samples` (list, appended by
add_sample, cleared by reset_samples).]
### External resource refs
[References to objects owned outside the class — Tk widgets, file handles, DB connections,
network sockets, threads. Note: in GUI projects this subsection often holds widget refs.
In services it may hold DB sessions or message queues.]
```
The "External resource refs" name generalizes the proven 4-subsection pattern beyond
GUI-specific framings. GUI projects should still document widget refs here.
---
## Section 6 — Writing calibrated entries
This section encodes the structural defenses against three common failure modes when an
LLM writes documentation: **hallucination** (inventing behavior or contracts not in
source), **skip** (omitting load-bearing detail), and **drift / over-explanation**
(padding with restatement of code or training-data leakage).
### 6.1 Source-anchor every behavioral claim
Every dev note and every behavioral statement in a Description must source-anchor. Convention:
- Inline: `the gate diagnostics run after PPM computation (lines 8073-8133)`.
- Or footer-style at end of dev note: `(line N)` or `(lines N-M)`.
If the agent cannot point at lines in the current source, it does not write the claim.
This is the primary anti-hallucination defense.
### 6.2 Minimum-fields template (skip-resistance)
The minimum-fields template (Section 5.4) is non-optional. Every entry has scope,
arguments, returns, description, upstream, downstream, last-edit footer. Empty fields
show the field name with `—`, they are not omitted. A skip-prone model has to actively
delete a field-name to shortcut, which is more salient than just omitting content.
### 6.3 Dev-note eligibility — four categories that earn space
A dev note must fit one of these four categories. If it doesn't fit any, it does not
belong in the entry.
1. **Regression anchor** — date-stamped record of a prior bug and its fix.
Format: "(fixed YYYY-MM-DD) Previously … . Now … . If a related case is reintroduced,
check …" The date and prior-state description are both required.
2. **Footgun pin** — "Don't refactor away because …" or "This looks redundant but …"
Calls out behavior whose subtlety would otherwise be lost in a refactor.
3. **Load-bearing contract callout** — interface assumption, type-dispatch shape,
tuple-order convention, multi-site coordination requirement. Example: "The
`isinstance(w, tuple)` chain in this function is mirrored in 3 other sites; changing
the discriminator shape requires updating all 4."
4. **Cross-module interface note** — implicit contract with another module not visible
from the call signature.
### 6.4 What does NOT belong in dev notes
- **Forward-looking speculation** ("In the future, schema versioning would help …",
"If we later support …"). Goes to a per-module **Future Considerations appendix**
(Section 6.7), not to per-function dev notes.
- **Restatement of code as English** — "First it iterates the dict, then for each key it
…". The Description carries the prose-level summary; reiterating in dev notes is padding.
- **Repeated cross-cutting concerns across siblings.** If three sibling methods share a
bug or convention, document it once in the most discoverable entry and use `See also:
<function>` pointers in the others. Don't restate.
- **Training-data leakage** — content the model "knows" about Python or libraries
generally but isn't specific to this codebase.
### 6.5 Proportionality floor
Every L3 entry has a floor of approximately 15 lines (scope, arguments, returns,
description, upstream, downstream optional, last-edit). Even trivial helpers get this
much. The floor protects against skip; the eligibility rules above protect against bloat.
### 6.6 Appendix-split rule
When stage-by-stage detail would dominate an entry, split it: keep the L3 entry thin
(orientation + dev notes + last-edit) and put the workflow table in an appendix at the
bottom of the L3 file.
Trigger threshold: function body > ~100 lines OR > 5 distinct stages OR > 30 dev-notes
lines. The exact threshold is configurable (`style.appendix_threshold_lines`).
The L3 entry's Description references the appendix: `See Appendix A-<function_name> for
the stage-by-stage workflow.`
Appendix table format:
```markdown
## Appendix A-<function_name>
| Stage | Lines | Operation | Key Variables | Notes |
|-------|-------|-----------|---------------|-------|
| 1 | N-M | High-level operation | vars touched | Optional context |
| 1.1 | N-M | Sub-row detail | — | Per-line specifics |
```
Sub-rows (dotted numbering) optional, used when stage-level detail isn't enough.
### 6.7 Future Considerations appendix
A per-module appendix at the bottom of the L3 file, after function entries and workflow
appendices. Format:
```markdown
## Future Considerations
### Schema versioning
Currently `load_flags` doesn't check a schema version field. If config schema evolves
(field renames, type changes), a versioning mechanism would help. Filed in
`<project>_skill_gaps.md` if relevant.
### Encoding asymmetry on Windows
…
```
This is the home for forward-looking content evicted from per-function dev notes by
rule 6.4. Keeps dev notes tight while preserving the speculation.
---
## Section 7 — Salvage protocol
For codebases that need documentation created after the fact. Five phases (S-1 through
S-5) plus checkpoint/resume.
### Prerequisites
- The target module has been examined during code review (interactive exploration with
the human).
- The agent has session memory of explanations discussed.
### Phase S-1: Harvest review knowledge
**Trigger:** "Please save the explanations of functions we've explored during this code
review session" (or equivalent).
The agent:
1. Collects all function explanations discussed during the review.
2. Outputs in structured format per function (one record):
```
**function_name**
Summary: [one-line]
Key points: [bullets of what was discussed]
Args noted: [types/purposes mentioned]
Relationships noted: [call chains traced]
```
3. Saves to `<handoff>/s1_dump_<module>_<date>.md`.
4. Does NOT explore undiscussed functions — the human chose what to review.
### Phase S-2: Scaffold structure
1. Run `ast_index.py` on the module to get all function names + line numbers + auto-detected
scope.
2. Create Level 2a with every function listed (name, line, scope).
- Functions from S-1 get descriptions pre-filled.
- Others get `description: —` and `status: pending`.
- Extract any existing docstrings or inline comments where present.
3. Update Level 1: list this module with `status: in-progress`.
### Phase S-3: Pre-documentation audit
NEW phase. Runs after the L2a scaffold exists, before L3 drafting begins.
**Trigger:** explicit human request, or automatically scheduled by S-2 in projects that
opt in via `audit.run_after_s2: true`.
1. Run `ast_index.py --audit` on the module.
2. Outputs surfaced (each as a section in the audit report):
- **Duplicate-name candidates:** same function name in multiple scopes (outer/inner
pairs, sibling shadows). Each pair flagged with both line numbers and a note about
which scope captures which.
- **Zero-caller candidates:** defs with no observed call sites within the file. Note:
this is intra-file only; cross-file zero-caller detection requires a separate pass.
- **Shape anomalies:** defs nested inside string literals or unreachable branches
(heuristic; flagged for human review).
3. Audit report saved to `<handoff>/<module>_audit_<date>.md`.
4. Human reviews; for confirmed duplicates, plans paired-entry coverage in S-4 (document
both, side-by-side compare, decide loser).
5. Confirmed dead-code candidates filed to `<handoff>/<module>_deadcode.md` for later
resolution (Section 8 protocol if edit-enabled, otherwise tracking only).
The audit phase prevents the disruptive mid-S-4 discovery of duplicates that would
otherwise force the agent to switch into compare-and-decide mode mid-pass.
### Phase S-4: Systematic documentation (clean session)
Was Phase S-3 in v0.2 of the protocol.
Start a fresh session for L3 creation. Load the S-1 dump, L2a index, audit report (if
S-3 ran), and source.
**Ordering:** Follow workflow order (natural data flow) for human readability. When a
function calls an undocumented downstream function, document the leaf as a brief stub
first, then return to the caller.
**Per function:**
1. Agent drafts the L3 entry following Section 5.4 and Section 6 rules.
2. Agent presents draft to user for review.
3. User approves, edits externally (then notifies agent), or requests changes.
4. If user edits related functions, they notify agent to update those entries.
5. Agent marks function as `documented` in L2a.
**Cross-module boundaries:** Record cross-module calls as typed references (e.g., "calls
`other_module.some_function`"). Flag in L1 as dependency. Do NOT drill into the external
module — that's a separate salvage pass.
**Edit-enabled mode (optional):** If the human enabled edit-enabled mode for this
session, fixes surfaced during S-4 follow Section 8's protocol. Otherwise stay doc-only:
file findings to `<name>bug.md` for later resolution.
### Phase S-5: Variable mapping (before finalization)
Was Phase S-4 in v0.2.
**Trigger:** "Please create the list and mapping of variables and arguments in this
module."
1. Read L2a to collect all referenced arguments/variables.
2. Run `ast_index.py --vars` for module-level assignments.
3. Build L2b initial map.
4. **Hidden behavior sweep:** Search for variable operations NOT captured by the function
index — assignments in conditionals, values unpacked from files/configs, variables
passed through closures without explicit parameters.
5. Present unknowns to the user as a numbered list for resolution.
6. Check session logs — hidden operations often surfaced during prior debugging.
7. After user resolves all items: write L3 entries for key variables, finalize L2b.
8. For class-bodied closures or class definitions, extend L2b with a class-section using
the Section 5.5 template.
### Checkpoint/Resume
Salvage sessions for large modules will exceed context limits.
1. L2a tracks each function: `documented` / `pending` / `stub` / `deleted`.
2. On mid-session end, write checkpoint at top of L2a:
```
**Salvage checkpoint:** Documented through `some_function`. Next: `next_function`. [date]
```
3. Next session reads checkpoint, resumes without re-reading completed entries.
4. S-1 dump and variable summaries remain available across sessions.
---
## Section 8 — Source edits during a doc pass (edit-enabled protocol)
This protocol fires only when the human has explicitly enabled source edits for a
session. It governs the moment when a doc pass surfaces a fixable issue and the agent
needs a defined sequence to apply the fix safely.
### Scope
**In scope (edit-enabled allowed during salvage):**
- Dead-code deletion when a def has zero callers OR is shadowed by a clearly active def.
- Comment cleanup (rotted/stale comments).
- Single-line typo or rename, unambiguously broken.
- Insertion of a clearly-missing return statement when control-flow analysis confirms
the absence is a bug, not intentional.
**Out of scope (deferred to dedicated debug session):**
- Bug fixes requiring behavior tracing or runtime monitoring.
- Bugs where consumer impact is unclear without a regression test.
- Refactors that change behavior, even subtly.
- Anything where the agent would benefit from more context than the doc pass provides.
When in doubt: file as `<name>bug.md` and continue the doc pass without applying. Filing
is always allowed; applying requires confidence.
### Per-fix protocol (steps 1–5)
For each in-scope fix:
1. **Pre-edit verification (agent, internal).** Apply project-defined verification rules
(config key: `verification.pre_edit_rules`). Confirm line numbers, trace call chain,
apply scope/interface checks. Surface in chat only if something surprises.
2. **Suggestion to human.** Structured preview block:
```
**Fix:** <ticket-or-finding-name>
**File:** <path>
**Reasoning:** <one line + ticket reference>
**Delete (lines N-M):**
```
<verbatim deleted code>
```
**Context preserved (1-3 lines each side):**
<surrounding code unchanged>
**Comment to add:** <none | proposed comment>
```
Comments are proposed only when the WHY is non-obvious from context. Default `none`.
3. **Approval gate.** Human approves, questions, requests edits, or rejects. Sequential
per fix (not batch) until the protocol is proven stable in the project; then projects
may relax to batched approval.
4. **Apply.** Agent uses Edit tool on the source file with the approved change.
5. **Defer file-wide post-edit scan.** Do NOT run `verification.post_edit_commands`
yet — that fires once per cluster (Section 12), not per edit.
### End-of-cluster protocol (steps 6–9)
After all fixes in the cluster have been applied:
6. **File-wide post-edit verification.** Run all commands in
`verification.post_edit_commands`. For Python projects this typically includes
`python -m py_compile <module>`, grep for orphaned method references, callback-def
existence checks. Project-defined.
7. **Index cascade.** Run AST script. Refresh L2a function-row line numbers, L2b
variable line numbers (Section 9). Update L2a status fields for deleted defs (`deleted`
status, retain row). Delete corresponding L3 entries (L3 = current-state ground
truth). Append L2a changelog entries. Update L1 last-updated date.
8. **Append to fixes log.** One entry per fix:
```markdown
## YYYY-MM-DD — <module>:<finding-name>
**Files+lines:** <module>:N-M
**Source delta:** -K lines (or +K, or rename)
**Verification:** <commands run + outcome>
**Ticket:** <name>bug.md → status banner updated
```
Path is `verification.fixes_log_path` (typically `handoff/fixes_log.md`).
9. **Bisect rollback if verification fails.** If post-edit verification (step 6) fails,
bisect by reverting fixes in reverse application order. Re-run verification after each
revert until clean.
### Index handling for deletions
- **L2a row:** retain, flip `status: deleted`, brief one-line note pointing at the
fix-log entry.
- **L3 entry:** delete entirely. L3 represents current-state ground truth; stranded
"DELETED" entries are clutter. The L2a row carries the breadcrumb.
- **Bug file:** add `**Status:** RESOLVED YYYY-MM-DD (see fixes_log.md)` banner at top.
Original discovery content preserved below.
### Duplicate / dead-code handling
For duplicates surfaced by Phase S-3 audit (or discovered mid-pass):
1. Document both copies in L3 first, each flagged with link to deadcode tracking.
2. At the seam (end of cluster batch where the pair was documented), present
side-by-side compare to human.
3. Human picks survivor; loser is queued for deletion via the per-fix protocol above.
4. After deletion: cascade as in step 7.
For zero-caller dead code from S-3 audit: same protocol — document, flag, delete via
per-fix protocol with audit findings as the ticket reference.
### Sequence cadence default
Sequential approve+apply per fix is the default (one fix at a time). Reason: makes the
protocol auditable and surfaces friction explicitly.
After the protocol is proven stable in a project (typically after several clean cluster
seams), projects may opt into batched approval — agent presents all pending fixes
in one block, human approves all at once, agent applies in order. This is a
project-level decision, not a skill default.
---
## Section 9 — Cascade management
Source edits shift line numbers. Some references auto-refresh via AST; others are
prose-level and require manual review. This section defines what cascades and how.
### What auto-refreshes vs. what doesn't
**Auto-refreshes (via AST script):**
- L2a function-row line numbers.
- L2b variable line numbers (via `--vars`).
- Module-level constant line numbers.
**Does NOT auto-refresh — requires manual review or project-config policy:**
- L3 prose line cites — explicit `(line N)` and `(lines N-M)` references inside
Description and Dev notes.
- L3 "Last edit" footers — `source read of lines X-Y` (depends on
`cascade_policy.last_edit_range` config).
- Frozen anchors used as historical breadcrumbs (depends on
`cascade_policy.frozen_anchor_prefix` config).
- Cross-references in dev notes ("see line N", "callsite at line M").
- Line refs inside `<name>bug.md` and `<module>_deadcode.md` files.
### Per-cluster batched cascade
The cascade fires once per cluster of edits, at the cluster seam — not per individual
edit. This is the cadence rule (Section 12). A single AST run, a single index pass, one
changelog batch. If a cluster has only one edit, per-edit and per-cluster collapse.
### Line-delta tracking artifact
For sessions with multiple edit-enabled fixes, a `<module>_line_deltas.md` artifact in
the handoff directory tracks cumulative source-line delta. The artifact is for **human
audit and for agents reasoning about historical state** — the agent does not apply
shifts from this table. The authoritative line numbers always come from a fresh AST run
on current source (Section 10). Format:
```markdown
# <module> Line Delta Tracking
| Date | Cluster | Δ lines | Cumulative | First affected line | Notes |
|------|---------|---------|------------|---------------------|-------|
| 2026-04-28 | cluster 1 | -21 | -21 | 6776 | dead ML params API block |
| 2026-04-28 | cluster 3 | -6 | -27 | 6890 | inner _short_id duplicates |
| 2026-04-29 | cluster 4 | -11 | -38 | 4523 | _update_main_status_for_batch shadow |
```
The `First affected line` column is optional but recommended — it captures the cutoff
above which references are unaffected and below which they shift, useful for human
review of which docs might need re-reading after a series of edits. Recommended for
projects with active edit-enabled work; optional otherwise. Path and column set are
configurable.
### Project-config policies
Two cascade decisions are project-configurable, no skill-mandated default for the more
ambiguous one:
- `cascade_policy.last_edit_range` (default: `frozen`):
- `frozen` — `Last edit: source read of lines X-Y` stays as the historical snapshot.
The date stamps when it was read; line numbers don't shift on subsequent edits.
Lower maintenance; archaeology-friendly.
- `auto_shift` — line range updates on every cascade to point at current source.
Higher navigation utility; high maintenance cost.
- `cascade_policy.frozen_anchor_prefix` (optional, no default):
- If projects use prefix-tagged historical anchors (e.g., `[[anchor:original-2026-04-25]]`),
declare the prefix here so the cascade tooling can distinguish
historical-from-current anchors. If absent, all anchors are treated as current and
shift on cascade.
### L3 prose line-cite policy
Three options, project picks (default: status quo):
- **Status quo (default):** prose line cites are free-form text. Manual grep + human
review on demand for staleness. Low cost per use; cost scales with how often refresh
is invoked.
- **Annotation convention (opt-in):** wrap line cites in a parseable tag the AST tool
can detect and shift (e.g., `[line:7711]` or `<sline n="7711"/>`). Higher upfront cost;
lower per-refresh cost. Recommended for projects with high refresh frequency.
- **Drop line cites entirely (opt-in):** rely on function-name + scope identification
in prose; never cite line numbers. Cleanest but loses navigation utility.
Configure via `cascade_policy.l3_line_cite_handling: status_quo | annotation | dropped`.
---
## Section 10 — Reference Refresh (R-1)
On-demand line-number reconciliation. Callable from any mode (salvage edit-enabled
passes use it per-cluster automatically; active maintenance uses it on-demand).
### Trigger
- Human says "refresh line numbers" / "run reference refresh" / equivalent.
- Drift detected at session start: file mtime newer than L2a `last_updated` field.
Agent surfaces the gap and offers R-1.
### Steps
1. Agent (or sub-agent dispatched for read-only discovery) runs `ast_index.py` and
`ast_index.py --vars` on current source.
2. Agent diffs AST output against L2a function-row line numbers and L2b variable line
numbers.
3. Agent reports drift in one structured message: "23 functions shifted, 4 vars shifted,
2 new defs, 1 def deleted."
4. Per `cascade_policy.last_edit_range`:
- **Frozen mode:** L3 footers stay as-is. Refresh affects L2a + L2b only.
- **Auto-shift mode:** L3 footers updated to new ranges. Agent presents diff for
approval before write.
5. Optional add-on: human asks "also check L3 prose cites?" → agent greps L3 for line
cites, reports candidates, human reviews per-case (no automation here — too risky
for prose semantics).
6. Agent writes updates after approval. L2a `last_updated` field bumped. Cascade-style
changelog entry appended.
### Sub-agent dispatch (for context savings)
The discovery + diff phase (steps 1–3) is purely read-and-compute; offloading to a
sub-agent saves main-agent context. The sub-agent returns the drift report. The main
agent presents to human, gets approval, and writes. This preserves the read-only
sub-agent contract (Section 18): sub-agents never apply updates.
### L3 prose cite limitation
AST cannot see prose line cites. They remain human-review territory unless the project
has opted into annotation convention (Section 9). Be honest about this limit when
running R-1: report which checks are automatic and which are manual.
---
## Section 11 — L2b extension trigger
For incremental L3 salvage where L2b already exists for a partial scope and new L3
entries introduce new variable readers/writers, two signals trigger L2b extension.
Whichever fires first.
### Signal 1: Per-cluster forward-pointer check
At the start of each cluster's L3 work, grep the existing L2b file for the cluster's
function names and explicit forward-pointer markers — strings like `"will document when
X gets L3"` or `<!-- L2B-TODO: -->`. If markers exist for any function in the upcoming
cluster, plan L2b extension as part of the cluster.
### Signal 2: End-of-cluster cross-check
After writing L3 entries for a cluster, scan each entry's scope-captured variables and
arguments (closure constants, mutable state, module-level constants used by the
function). Cross-reference against L2b. Anything cited in L3 that isn't in L2b → extend
L2b in the same session.
### Salvage / extension scope boundary
- **In scope (during salvage):** add rows for newly-referenced closure constants,
closure mutable state, closure tk vars / DB sessions / etc., module-level constants.
Update existing rows' Readers/Writers columns when the cluster introduces new
readers/writers. Resolve TODO markers in L2b's "Hidden behaviors / open questions"
when the L3 work covers them.
- **Out of scope (defer to Phase S-5 finalization):** L3 `### VAR:` entries for
newly-listed variables. Local-state Sections analogous to per-function locals for
large closures.
### Scope-corrections from class-method-nested defs
When a class method contains nested defs, the AST scope tag is
`cls:Class (in <method>)` (Section 5.2). If the AST is older and shows just `cls:Class`,
update both L2a and L2b rows during the cluster's work — this is part of L2b extension.
---
## Section 12 — Verification rules cadence
The skill recommends a cadence split between pre-edit and post-edit checks. Specific
rule contents are project-defined via the config.
### Pre-edit: per individual edit
`verification.pre_edit_rules` is a list of project-defined checks the agent runs before
each edit decision. Examples:
- Confirm line numbers (grep for the exact function name in current source).
- Trace call chain (find all upstream callers).
- Interface check (signature compatibility with callers).
- Ordering check (post-move dependencies still resolve).
- Path derivation check (sidecar paths consistent with new format).
- Scope check (`global` vs `nonlocal` correctness).
These fire per-edit because they prevent wrong edits before they happen — they cannot be
batched.
### Post-edit file-wide scans: per cluster
`verification.post_edit_commands` is a list of shell commands the agent runs once per
cluster, at the cluster seam (not per individual edit). Examples:
- `python -m py_compile <module>` (Python syntax check).
- Grep for orphaned method references.
- Callback-definition existence check.
- Project-specific lint or test commands.
Per-cluster cadence: running these after each individual edit in a 5-edit cluster
multiplies cost without catching anything per-cluster wouldn't.
### Bisect on failure
If post-edit verification fails after a cluster, bisect by reverting fixes in reverse
application order. Re-run verification after each revert. The error message usually
points at the offending edit, so bisection is typically O(1) — cheaper than per-edit
verification across the cluster.
---
## Section 13 — Session report finalization gate
At the end of every session that touched docs or applied edits, a finalization gate runs
before the session report is written.
### Default behavior
Overwrite `<handoff>/session_report.md` (path is `paths.session_report` config key).
Prior session report archived to `<archive>/<suffix>_session_report.md` first.
### Self-check checklist
Agent runs a categorical pass before presenting the report:
- All in-progress L3 entries reached `documented` status (no orphans)?
- Every approved source edit recorded in `fixes_log.md`?
- Every newly-created `<name>bug.md` has a status banner (OPEN / RESOLVED)?
- Index cascade complete — L1 / L2a / L2b match current source state?
- If mid-cluster: checkpoint marker written at L2a top with "next: X"?
- Forward-pointer for next session noted?
- Any TODO markers in L2b/L3 resolved this session but still present in text?
Results presented as a structured pass/fail list; failures listed with brief detail.
### Single-message gate
```
Session self-check: [results]
Draft report preview: [content, ~50 lines]
Anything to add, edit, or flag for next session?
Otherwise: archive prior session_report to <archive_path>, overwrite session_report.md.
```
Human responds with edits or "go." Only if they say "don't overwrite" does the fallback
fire. The gate is a single round-trip in the common case.
### Fallback options if human declines overwrite
- **Concat:** append the new report to the existing `session_report.md`. Single file
grows.
- **New file with suffix:** write to `<handoff>/session_report_<suffix>.md` where suffix
follows project config (`paths.session_report_suffix_format`, default `<YYYYMMDD>`).
Existing report untouched.
### Archive-before-write
The archive step (move prior `session_report.md` to dated archive) runs BEFORE the new
write. If the new write fails, the prior report has already been preserved. No risk of
losing both.
---
## Section 14 — Source-internal metadata
Conditional convention for projects that maintain in-source datestamps and version
constants (`__version__`, `__date__`, `last_update`, `version`, etc.) at the top of
modules.
### Bump matrix
| Field type | Bump on edit-enabled doc-pass edits? | Rationale |
|-----------|--------------------------------------|-----------|
| Date-class (`last_update`, `__date__`, `last_modified`) | **Yes** — set to today's date in project format | The field's semantics are "when was this file last touched"; not bumping makes it a lie. Cost is one one-line edit. |
| Version-class (`version`, `__version__`) | **No** for doc-driven cleanup; **Yes** for feature releases | Salvage cleanups don't change behavior; reserve version bumps for feature deliveries (matches semver intent). |
| L2a header `last_updated` field | **Always**, every session that touches the index | Standard wiki-doc convention, in scope for this skill. |
| Filesystem mtime | n/a — auto-managed by OS | Drives session-start staleness checks. |
### Project-config keys
- `metadata.date_field_name` (no default — required if any date-bumping desired).
- `metadata.date_format` (default `%Y%m%d` if `date_field_name` is set).
- `metadata.version_field_name` (no default).
- `metadata.bump_version_on_salvage` (default `false`).
If `metadata.date_field_name` is absent or null, no bumping happens — the convention is
opt-in.
### Verification
Optional grep at end-of-cluster step 6 for unbumped fields. The agent surfaces:
"Detected `last_update = 20260421` in source; current date is 20260501. Bump per
metadata.bump_rules?" Human approves or skips.
---
## Section 15 — Variable line-number refresh
L2b variable rows include a line-number column (Section 5.3). The AST script's `--vars`
output drives variable line-number refresh in L2b, mirroring the function-row pattern.
Same cadence as function refresh: per-cluster batched, automatic on Reference Refresh
(Section 10), automatic at end-of-cluster step 7.
---
## Section 16 — Active maintenance
For modules with `active` status — post-salvage edits typically happen outside the
wiki-doc protocol (regular development work, collaborator pull requests, etc.). The
skill cannot enforce edit-time discipline outside its protocol. This section defines
the realistic posture.
### Skill posture
- **Within wiki-doc protocol** (edit-enabled doc pass during salvage or maintenance):
cascade applies, Section 8 protocol fires, all rules above hold.
- **Outside protocol** (regular dev edits): unavoidable drift accumulates between L1/L2/L3
and source. The skill's catch-up mechanism is Reference Refresh (Section 10).
### Drift detection at session start
Recommended: agent compares file mtime to L2a `last_updated` at every session start. If
file is newer, alert and offer R-1. Already implemented as a session-start check in
mature projects.
### Optional CI / git hook
For projects with active concurrent development, an optional git pre-commit hook or CI
job can run `ast_index.py --diff` against a stored snapshot, alerting when source
changes affect functions documented in L2a. The skill describes the pattern; project
implements (it's environment-specific).
Sample pre-commit hook outline:
```bash
# .git/hooks/pre-commit (project-supplied)
python tools/ast_index.py <module>.py --diff .wiki-doc/<module>.snapshot.tsv \
| grep -q DRIFT \
&& echo "WARN: wiki-doc drift detected; run R-1 after commit." || true
```
---
## Section 17 — Version control integration
Optional. Activates only when `vcs.enabled: true` in the project config.
(vcs = version control system.) When disabled, the skill makes no commits,
no branches, no worktrees — it operates as if VCS does not exist.
Useful for projects where VCS is managed through a separate workflow (e.g.,
external sync to a Git host from a different machine, or a workspace that is itself a
non-canonical working copy).
### 17.1 Commit granularity
Commits fire at the cluster seam — once per cluster, after post-edit verification
passes. NOT per individual fix. Reasons:
- The cluster seam is the natural verified-work unit. Pre-seam state is mid-protocol
and not necessarily consistent.
- Per-fix commits create noise: 5 fixes in a cluster → 5 commits, none of which
individually carry verification.
- Per-cluster commits align with the rollback model (Section 8 step 9): if verification
fails, the cluster is reverted in a single `git reset` rather than five individual
reverts.
The cluster seam in the protocol's order:
```
Cluster of fixes applied (Section 8 steps 1–5)
→ Post-edit verification (Section 12 + Section 8 step 6)
→ Index cascade (Section 8 step 7)
→ Append fixes log (Section 8 step 8)
→ [VCS commit happens here, if enabled]
→ Session report finalization gate (Section 13)
```
The commit lands AFTER the index cascade and fixes-log append, so the commit captures
both source changes AND documentation updates in one atomic commit.
### 17.2 Commit message format
Configurable via `vcs.commit_message_template`. Default template:
```
{module}: {summary}
{fix_list}
- Net source delta: {delta} lines
Verification: {verification}
Cluster: {cluster_id}
```
Substitution variables:
- `{module}` — affected module's bare name
- `{summary}` — one-line cluster summary, supplied by the agent
- `{fix_list}` — bullet list of fixes with line ranges
- `{delta}` — net source-line delta with sign
- `{verification}` — verification commands and outcome
- `{cluster_id}` — cluster identifier or descriptive name
Example commit (filled-in default):
```
mspfileloaderv14: open_ml_params_window cluster cleanup
- Outer _get_ml_context deleted (lines 6776-6797)
- Inner _read_ml_from_json deleted (lines 6764-6772)
- _on_key dead binding deleted (lines 6890-6905)
- Net source delta: -38 lines
Verification: py_compile OK, self._ audit OK, callback grep OK
Cluster: S7-cluster-1
```
### 17.3 Branch strategy
Project-config'd via `vcs.branch_strategy`:
- `current` (default) — agent commits to whatever branch is currently checked out.
- `cluster_branch` — agent creates a new branch per cluster
(`<module>-<cluster_id>`), commits there, leaves it for human review and merge.
- `worktree` — agent uses git worktrees (Section 17.4) for parallel cluster
experimentation.
For most projects, `current` is correct: clusters are small enough that branch overhead
isn't justified. `cluster_branch` is useful when multiple agents or contributors need
parallel cluster work without stepping on each other.
### 17.4 Worktree pattern (documented, opt-in)
For projects that want to isolate cluster experimentation, the worktree pattern
provides a parallel working directory without affecting the main checkout. Useful
when a cluster's bisect-rollback (Section 8 step 9) might be invoked multiple times
or when experimental refactors need to stay isolated until verified.
Project-config'd via:
```yaml
vcs:
worktree_create_command: "git worktree add ../{module}-{cluster_id}-experiment HEAD"
worktree_remove_command: "git worktree remove ../{module}-{cluster_id}-experiment"
```
Substitution variables: `{module}`, `{cluster_id}`. Both commands are adjustable —
the values shown are the recommended defaults.
Workflow when `vcs.branch_strategy: worktree`:
1. Cluster begins → agent runs `worktree_create_command`.
2. Agent applies fixes in the worktree directory.
3. Verification runs in the worktree.
4. On success: merge worktree branch back to the main branch via `git merge`, then run
`worktree_remove_command`.
5. On failure (verification fails): run `worktree_remove_command` (no merge); fixes are
discarded along with the worktree.
The worktree pattern is **documented but not recommended by default**. For most
clusters the in-place `current` strategy is simpler and faster. Adopt worktree only
when parallel experimentation or risky refactors justify the overhead.
### 17.5 Pre-approved fix categories (opt-in)
For fixes that match pre-defined safe criteria, the agent may apply without per-fix
human approval. Still logged (Section 8 step 8); still surfaced in the cluster summary
at the seam, where the human reviews all pre-approved fixes en masse before approving
the commit.
**Opt-in only — no skill default.** Projects that want this list categories explicitly
in config:
```yaml
edit_protocol:
pre_approved_categories:
- zero_caller_dead_code # Section 8 in-scope item: zero callers, scope clear
- rotted_comment_cleanup # Stale comments referencing removed code
# Additional project-defined categories
```
When the agent identifies a fix candidate, it checks the list:
- **Match found:** apply without per-fix approval. Log normally. Include in cluster
summary marked `[pre-approved]`.
- **No match:** standard Section 8 protocol — per-fix human approval required.
Cluster seam still gates the commit. Human reviews all pre-approved fixes alongside
manually-approved fixes at the seam, before the commit lands. Revert is one
`git reset HEAD~1` if anything is wrong.
**Risk management:**
- Pre-approved categories are project-explicit — the skill ships with no defaults to
prevent accidental enablement.
- Cluster summary includes a `[pre-approved]` tag on each pre-approved fix, so the
human can spot them at a glance.
- Same Section 8 verification rules apply — pre-approval doesn't skip pre-edit checks.
- Same cluster-seam post-edit verification — failure triggers bisect-rollback as
normal.
### 17.6 Project-config keys
Summary of `vcs.*` keys (full template in `wiki-doc.config.template.yaml`):
| Key | Default | Purpose |
|-----|---------|---------|
| `vcs.enabled` | `false` | Master toggle. Skill makes no VCS calls when false. |
| `vcs.commit_message_template` | (built-in default, Section 17.2) | Commit message format string |
| `vcs.branch_strategy` | `current` | One of `current` / `cluster_branch` / `worktree` |
| `vcs.worktree_create_command` | `git worktree add ../{module}-{cluster_id}-experiment HEAD` | Used when `branch_strategy` is `worktree` |
| `vcs.worktree_remove_command` | `git worktree remove ../{module}-{cluster_id}-experiment` | Cleanup after worktree merge or revert |
| `edit_protocol.pre_approved_categories` | `[]` | Opt-in list of safe-to-auto-apply fix categories |
When `vcs.enabled: false`, all other `vcs.*` keys are ignored.
---
## Section 18 — Sub-agent pattern
### Read-only contract
Sub-agents are read-only by skill contract. They perform search, cross-reference, trace,
discovery, and computation. They do NOT update documentation. They do NOT perform edits.
They do NOT execute project commands that mutate state.
This contract is non-negotiable in the current version of the skill. If a future
project demands sub-agent dispatch for narrow post-approval write tasks (e.g.,
line-number-only L2a/L2b updates after R-1 approval), that is a deliberate skill
amendment requiring its own design pass.
### Tasks suitable for sub-agents
- Searching L3 by heading and reading the matched entry.
- Tracing call chains across L2a (multi-module).
- Cross-referencing L2a entries against current source.
- Running `ast_index.py` and reporting results (R-1 discovery phase, Section 10).
- Audit phase output review (Section 7, Phase S-3 candidate review).
- Hidden-behavior sweep within a single module (Phase S-5 step 4).
### Tasks NOT suitable for sub-agents
- Writing or modifying any documentation file.
- Editing source code.
- Running test suites or anything that mutates project state.
- Approving fixes on behalf of the human.
### Dispatch pattern
Main agent passes the sub-agent: function name(s), file paths, the specific question to
answer, and a short context briefing. Sub-agent searches, reads, computes, returns
findings. Main agent integrates, surfaces to human, performs writes if any.
---
## Section 19 — Deferring protocol expansions
When a protocol gap is identified mid-pass but cannot be addressed in the current pass,
file the deferral as a single-line breadcrumb in the most discoverable L3 entry plus an
entry in the project's gap log. Do NOT commit to a resolution; the breadcrumb just
makes the deferral discoverable.
### Breadcrumb format
In the most discoverable L3 entry (e.g., the closure-root entry for a closure-local
state issue, or the class `__init__` for a class-state issue), add a single Dev-notes
row:
```markdown
**Dev notes:**
- *(deferred protocol gap)* Closure-local state for this mega-closure is not formally
mapped in L2b. Tracked in `<handoff>/<project>_skill_gaps.md` Gap N.
```
Brief, pointer-only. The detailed write-up lives in the gap log, not in the L3 entry.
### Gap log entry format
In `<handoff>/<project>_skill_gaps.md`:
```markdown
## YYYY-MM-DD — <module> <cluster>
### Gap N — <one-line summary>
**What's missing in the skill**
[1-3 paragraphs]
**Where this matters**
[1-2 paragraphs with concrete example from this project]
**Working agreement adopted for now**
[1-3 paragraphs describing the project's current handling]
**To investigate later**
[bullets — what the skill should consider when this gap is addressed]
```
This pattern emerged from real GlycoMSP usage and is the source of the v1 protocol's
8-gap evolution. It works because deferrals stay discoverable without committing the
project (or skill) to a particular resolution.
### When deferrals accumulate
Periodic gap-log review (project-driven cadence) consolidates deferrals: some get
resolved by the project, some get upstreamed to a skill amendment, some stay as
documented working agreements indefinitely. The breadcrumbs in L3 entries are updated
when the gap is resolved.
### Upstreaming a gap to the skill
If a deferred gap might be valuable beyond your project — i.e., the working agreement
could be a useful default for other wiki-doc users — consider upstreaming it. See
`CONTRIBUTING.md` for the proposal format and review process. Working agreements that
have been stable across multiple sessions or projects are the strongest candidates.
---
## Section 20 — Completion validation (final gate)
Before flipping a module from `in-progress` to `active` in L1:
1. **AST completeness:** Run AST script, diff against L2a. Every `def` must appear.
Missing functions get stub entries.
2. **L3 coverage:** Every `documented` function in L2a has an L3 entry. `stub`/`pending`
are acceptable but noted.
3. **Variable map:** L2b exists and is human-reviewed. Cross-check: shared-state arguments
in L3 entries appear in L2b.
4. **Cross-references:** All upstream/downstream references in L3 entries resolve to real
functions. All L2b reader/writer entries exist in L2a.
5. **Line number spot-check:** Compare 3-5 functions between L2a and source. Re-run AST
if mismatch.
6. **Pre-S-3 audit findings resolved or deferred.** Each duplicate-pair from S-3 either
resolved (one copy deleted) or explicitly deferred via Section 19.
7. **Bug files have status banners.** Every `<name>bug.md` filed during salvage has a
current `**Status:**` banner (OPEN with rationale or RESOLVED with date).
8. **Fixes log reconciled.** `fixes_log.md` has entries for every approved source edit
during this salvage. Line-delta artifact (`<module>_line_deltas.md`) sums match.
9. **Calibration spot-check.** Sample 3 L3 entries (one trivial, one mid-complexity,
one high-density). Verify each follows Section 6 rules: source-anchored claims,
minimum-fields template, eligible dev notes, no forward-looking speculation in dev
notes.
If all pass: update L1 status to `active`, update date, note coverage percentage.
---
## Section 21 — AST script reference
The bundled script `scripts/ast_index.py` is the single tool that powers Sections 7
(salvage), 9 (cascade), 10 (Reference Refresh), and 15 (var refresh).
### Function index (default mode)
```bash
python ast_index.py <source.py>
```
Output: `DEF\t<name>\t<line>\t<scope>` rows, sorted by line number.
**Auto-detected scope** (NEW in v1):
- `top` — module-level def.
- `cls:ClassName` — class method (direct member).
- `cls:ClassName (in <method>)` — nested def inside a class method.
- `cl:<closure_name>` — closure-local def (named-function closure).
- `cl:<outer> (in <inner>)` — sub-closure-local def.
This eliminates the manual scope-correction work that was required in v0.2.
### Variable index (`--vars`)
```bash
python ast_index.py <source.py> --vars
```
Output: adds `VAR\t<name>\t<line>\t<scope>` rows. Same scope auto-detection as
functions.
### All (`--all`)
```bash
python ast_index.py <source.py> --all
```
Output: adds `CLASS\t<name>\t<line>\t<scope>` rows for class definitions.
### Pre-S-3 audit mode (`--audit`, NEW)
```bash
python ast_index.py <source.py> --audit
```
Output: structured report with three sections:
- **Duplicate-name candidates:** same `def` name in multiple scopes. Each pair listed
with both line numbers.
- **Zero-caller candidates:** defs with no observed call sites within the file (intra-file
only).
- **Shape anomalies:** defs nested inside string literals, defs inside `if False:`
branches, etc. (heuristic).
Powers Phase S-3 (Section 7).
### Diff mode (`--diff <snapshot>`, NEW)
```bash
python ast_index.py <source.py> --diff <previous_snapshot.tsv>
```
Output: drift report comparing current AST against a saved snapshot. Lists shifted,
added, deleted, and renamed defs/vars. Powers Reference Refresh (Section 10).
To produce a snapshot for later diff:
```bash
python ast_index.py <source.py> --vars > <snapshot>.tsv
```
### Output format
Tab-separated values, one entry per line:
```
KIND<TAB>NAME<TAB>LINE<TAB>SCOPE
```
Sortable by `cut -f3 | sort -n` if needed.
### Python-specific note
The shipped script is Python-specific (uses Python's `ast` module). Projects in other
languages need to author their own AST tool conforming to the documented output format.
The structure generalizes — any AST library can produce equivalent output — but the
shipped tool covers Python only.
For other languages, suggested approaches:
- **JavaScript/TypeScript:** `@babel/parser` or `typescript` compiler API.
- **Go:** `go/ast` standard library.
- **Rust:** `syn` crate.
- **C/C++:** Clang's libclang.
The output format must match (`KIND\tNAME\tLINE\tSCOPE`). All other tooling in this
skill consumes that format and is language-agnostic.
---
## Section 22 — Glossary
- **L1, L2a, L2b, L3** — Levels of the documentation hierarchy. See Section 2.
- **S-1 through S-5** — Salvage protocol phases. See Section 7.
- **R-1** — Reference Refresh. See Section 10.
- **Cluster** — A thematically-related batch of work performed in a single sub-session,
bounded above by context budget or human-defined cadence and below by a single
function or fix. Clusters are the unit at which post-edit verification, index cascade,
and fix-log entries fire ("the cluster seam"). A typical L3-drafting cluster covers
5–15 related functions; a typical fix cluster covers 1–5 related edits. Clusters can
be thematic (a class's methods together) or structural (a closure's helpers
together) — the human picks the boundary, the protocol enforces what fires at the seam.
- **Cascade** — The cascading update of L1/L2a/L2b/L3 line numbers and metadata after
one or more source edits. See Section 9.
- **Cluster seam** — The point between clusters where post-edit verification, index
cascade, fixes-log append, and rollback-on-failure all run.
- **Frozen anchor** — An anchor in the docs whose line number is preserved as a
historical snapshot rather than auto-shifted. See Section 9.
- **Doc-only pass** — A wiki-doc session in which source files are not modified. The
default mode.
- **Edit-enabled pass** — A wiki-doc session in which the human has explicitly enabled
source edits per Section 8.
- **Audit mode** — `ast_index.py --audit`. Surfaces duplicates, zero-callers, shape
anomalies before S-4 begins.
- **Diff mode** — `ast_index.py --diff <snapshot>`. Powers Reference Refresh.
---
## Quick rule reference
1. **Read L1 first** every session. Spot-check version/date for relevant modules.
2. **L2a is the working layer.** Most tasks resolve here.
3. **L2b is human-triggered.** Variable map on explicit request.
4. **Line numbers are auto-generated** via AST. Only L2a/L2b store them.
5. **L3 is accessed by name.** Sub-agents grep `### name` headings.
6. **Updates propagate bottom-up.** Source → L3 → L2a/L2b → L1.
7. **Sub-agents are read-only.** No exceptions in v1.
8. **Doc-only is default.** Edit-enabled requires explicit opt-in.
9. **Edit-enabled requires Section 8 protocol.** Suggest → approve → apply → verify → log.
10. **Verification cadence:** pre-edit per-edit, post-edit per-cluster.
11. **Cascade is per-cluster.** AST refresh, index update, log append at the cluster seam.
12. **Frozen Last-edit by default.** Project may opt into auto-shift.
13. **Calibrated entries.** Source-anchor claims; eligible dev notes only; speculation
goes to Future Considerations.
14. **Defer cleanly.** Breadcrumb in the most discoverable L3 entry; full deferral in
the gap log.
15. **Completion gate before active.** Section 20's nine checks before flipping L1
status.