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.

1. If the file is present: load it; for each missing required field, ask in a single

batched message; write answers back with approval.

1. 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.

1. 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

5.2 Level 2a — Function Index fields

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

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).

### 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.

## 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.

1. Footgun pin — "Don't refactor away because …" or "This looks redundant but …"

Calls out behavior whose subtlety would otherwise be lost in a refactor.

1. 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."

1. 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:

## 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:

## 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]

1. Saves to <handoff>/s1_dump_<module>_<date>.md.
2. 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.

1. 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.

1. 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).

1. Audit report saved to <handoff>/<module>_audit_<date>.md.
2. Human reviews; for confirmed duplicates, plans paired-entry coverage in S-4 (document

both, side-by-side compare, decide loser).

1. 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.

1. Present unknowns to the user as a numbered list for resolution.
2. Check session logs — hidden operations often surfaced during prior debugging.
3. After user resolves all items: write L3 entries for key variables, finalize L2b.
4. 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]

1. Next session reads checkpoint, resumes without re-reading completed entries.
2. 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.

1. 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.

1. 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.

1. Apply. Agent uses Edit tool on the source file with the approved change.

1. 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:

1. 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.

1. 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.

1. Append to fixes log. One entry per fix:

   ## 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).

1. 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.

1. Human picks survivor; loser is queued for deletion via the per-fix protocol above.
2. 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:

# <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.

1. Agent diffs AST output against L2a function-row line numbers and L2b variable line

numbers.

1. Agent reports drift in one structured message: "23 functions shifted, 4 vars shifted,

2 new defs, 1 def deleted."

1. 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.

1. 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).

1. 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

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:

# .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:

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.

1. 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:

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):

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:

**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:

## 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.

1. L3 coverage: Every documented function in L2a has an L3 entry. stub/pending

are acceptable but noted.

1. Variable map: L2b exists and is human-reviewed. Cross-check: shared-state arguments

in L3 entries appear in L2b.

1. Cross-references: All upstream/downstream references in L3 entries resolve to real

functions. All L2b reader/writer entries exist in L2a.

1. Line number spot-check: Compare 3-5 functions between L2a and source. Re-run AST

if mismatch.

1. 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.

1. Bug files have status banners. Every <name>bug.md filed during salvage has a

current **Status:** banner (OPEN with rationale or RESOLVED with date).

1. 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.

1. 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)

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)

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)

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)

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)

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:

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.

1. Defer cleanly. Breadcrumb in the most discoverable L3 entry; full deferral in

the gap log.

1. Completion gate before active. Section 20's nine checks before flipping L1

status.