incitaciones 0.7.0 → 0.9.0

package/README.md

@@ -39,13 +39,10 @@ cd incitaciones
 **Install options:**
 
 ```bash
-./install.sh --bundle essentials    # Core prompts only
-./install.sh --bundle planning      # Planning workflows
-./install.sh --bundle reviews       # Review prompts
-./install.sh --bundle documentation # Documentation tools
+./install.sh --bundle essentials    # Core prompts only (see all 8 bundles: --list)
+./install.sh --list                 # Show available prompts and bundles
 ./install.sh --format commands      # Legacy flat-file format for other tools
 ./install.sh --disable-model-invocation # Require explicit /skill:name usage
-./install.sh --list                 # Show available prompts
 ./install.sh --help                 # Show all options
 ```
 
@@ -83,12 +80,12 @@ pi install git:github.com/charly-vibes/incitaciones
 pi install .
 ```
 
-The repository includes checked-in pi package resources under `pi-package/`, and the generation step can refresh them when content changes:
+The npm package ships generated pi package resources under `pi-package/`. The directory is **gitignored, not checked in** — CI regenerates it during npm publish (`npm-publish.yml` runs `scripts/generate-pi-resources.mjs` before `npm publish`), so there is nothing to commit. Locally, the pre-push hook runs `just validate-pi-package`, which regenerates and verifies the resources match the manifest:
 
 - `pi-package/skills/` — Agent Skills with pi-compatible frontmatter
 - `pi-package/prompts/` — prompt templates for slash-command shortcuts
 
-After changing distilled content or manifest entries, run `just generate-pi-resources` and commit the updated `pi-package/` files.
+After changing distilled content or manifest entries, you don't need to touch `pi-package/` — it is regenerated and validated automatically (CI on publish, pre-push hook locally). To preview the generated resources manually, run `just generate-pi-resources`.
 
 ### Publishing a new version
 

package/content/distilled/close/SKILL.md

@@ -8,14 +8,22 @@ tools: Read, Write, Edit, Glob, Bash
 
 End the current session: log what was done, update tasks, route durable knowledge to `~/.whisper/`, commit and push, clear context.
 
-Uses `$JOURNAL_PATH` (defaults to `~/dev/status`) for the daily log journal, and `~/.whisper/` for accumulated operational knowledge. The log subdirectory defaults to `log/`; set `$JOURNAL_LOG_SUBDIR` to override (e.g. `areas/log` for the JORNAL layout).
+Uses `$JOURNAL_PATH` for the daily log journal, and `~/.whisper/` for accumulated operational knowledge. Agent shells run non-interactive and never source `.bashrc`, so the environment may be missing these exports — resolve both values per step 1 (env → shell config → convention → legacy fallback).
 
 ## Steps
 
 1. Pull the journal repo:
    ```bash
-   JOURNAL="${JOURNAL_PATH:-$HOME/dev/status}"
-   LOG_SUBDIR="${JOURNAL_LOG_SUBDIR:-log}"
+   # Non-interactive shells never source .bashrc, so $JOURNAL_PATH etc. are
+   # usually unset here. Source the config in a throwaway shell — bash itself
+   # handles comments, quotes, and nested vars ($JORNAL) — then fall back.
+   shellval() { bash -c 'source ~/.bashrc >/dev/null 2>&1; printf "%s\n" "${'"'$1'"'}"' 2>/dev/null; }
+   JOURNAL="${JOURNAL_PATH:-$(shellval JOURNAL_PATH)}"
+   [ -n "$JOURNAL" ] || JOURNAL="$(shellval JORNAL)"
+   [ -n "$JOURNAL" ] || JOURNAL="$HOME/para/areas/jornal"   # JORNAL convention
+   [ -d "$JOURNAL/.git" ] || JOURNAL="$HOME/dev/status"     # legacy clone; flag this fallback in the reply
+   LOG_SUBDIR="${JOURNAL_LOG_SUBDIR:-$(shellval JOURNAL_LOG_SUBDIR)}"
+   [ -n "$LOG_SUBDIR" ] || LOG_SUBDIR="areas/log"
    cd "$JOURNAL" && git pull
    ```
 

package/content/distilled/code-review/SKILL.md

@@ -1,4 +1,4 @@
-<!-- skill: code-review, version: 1.2.0, status: verified -->
+<!-- skill: code-review, version: 1.3.0, status: verified -->
 # Iterative Code Review (Rule of 5)
 
 Perform a multi-pass, iterative code review using Steve Yegge's Rule of 5 to achieve high-quality refinement through breadth-first exploration.

package/content/distilled/code-review/references/criteria.md

@@ -8,7 +8,7 @@ Use these criteria to categorize findings and determine when the review process
 | :--- | :--- | :--- |
 | **CRITICAL** | Blocks merge. Severe security vulnerability, data loss risk, or fundamental logic failure. | SQL Injection, plaintext passwords, unhandled exceptions in core path. |
 | **HIGH** | Should fix before merge. Significant performance issue, major regression risk, or violation of key requirements. | Missing index on hot query, non-singular requirement, missing error states. |
-| **MEDIUM** | Consider addressing. Minor technical debt, sub-optimal pattern, or readability issues. | Magic strings, DRY violations, lack of docstrings, magic numbers. |
+| **MEDIUM** | Consider addressing. Minor technical debt, sub-optimal pattern, or readability issues. | Magic strings, DRY violations, lack of docstrings, missing or stale file-header Purpose (see `file-headers`), magic numbers. |
 | **LOW** | Nice to have. Stylistic improvements, minor metadata gaps, or typos in non-critical comments. | Minor formatting, redundant comments, small consistency improvements. |
 
 ## Convergence Criteria
@@ -47,4 +47,5 @@ Use these criteria to categorize findings and determine when the review process
 ### Stage 5: EXCELLENCE
 - Performance optimization?
 - Documentation polish?
+- File headers: every touched source file's Purpose is present, one-sentence-accurate, and not stale; Rationale reflects the current design (see `file-headers`)?
 - Style consistency?

package/content/distilled/codebase-cartography/SKILL.md

@@ -31,11 +31,12 @@ Pick the entry level from the request:
 - Before gathering evidence for any map (and again before rendering), read `references/zoom-levels.md` — per-level evidence collection commands and text rendering formats.
 - Before any health check or when the user asks about "health", "smells", or refactoring targets, read `references/smell-signatures.md` — anti-pattern proxies, evidence requirements, severity ratings.
 - Before writing the final output, read `references/report-template.md` — output structure per mode.
-- When the user asks for an HTML export or a shareable version of the report, read the "Optional HTML Export" section at the end of `references/report-template.md`.
+- When the user asks for an HTML export or a shareable version of the report, read the "Optional HTML Export" section at the end of `references/report-template.md`; when the request spans multiple reports (batch), also read its "Batch export" section.
 
 ## Zoom Discipline
 
-- Offer adjacent levels as follow-ups; never dump all three maps unrequested.
+- Offer adjacent levels as follow-ups; never dump all three maps unrequested. An explicit batch request ("all reports", "map every module") is a user request — the offer-don't-dump rule applies to unprompted follow-ups only (batch procedure in `references/report-template.md`, "Batch export" section).
+- Re-verify every embedded count and fan-in/fan-out number against a fresh command run immediately before writing each report (one consolidated pass per batch is fine) — counts gathered early in a long session drift.
 - Every claim carries a file reference (`path`, or `path:line` for specific symbols).
 - State dependency direction explicitly (A → B); never "related to".
 - Distinguish observed evidence from inference; label inference explicitly.
@@ -48,4 +49,4 @@ Pick the entry level from the request:
 - Prefer structural facts over narrative: dependency direction, counts, boundaries.
 - Health-check findings follow the evidence format in `references/smell-signatures.md` (pattern, evidence, quantity, severity) — never unanchored opinions.
 - Maps are diff-able artifacts: tables and Mermaid, not prose walls.
-- HTML export is derived output, produced only on request; the markdown report remains the artifact of record.
+- HTML export is derived output, produced only on request; the markdown report remains the artifact of record. Exports live in `docs/cartography/` as a self-contained directory (index + shared assets); see the "Optional HTML Export" section of `references/report-template.md`.

package/content/distilled/codebase-cartography/references/report-template.md

@@ -12,10 +12,11 @@ Structure the final output by mode. All modes share the closing sections. Keep m
 
 ## Mode: macro
 
-1. **Module inventory** — table (module, path, responsibility, deps out, fan-in)
+1. **Module inventory** — table (module, path, responsibility, weight bar, deps out, fan-in)
 2. **Dependency matrix** — text DSM with ↑ marks for layer violations
 3. **Module graph** — Mermaid, edges labeled with counts
-4. Structural observations
+4. **Composition** — disk-reality breakdown by file kind (source / test / generated / vendored / config), excluded code included; distinct from the inventory weight column (analysis code, exclusions applied)
+5. Structural observations
 
 ## Mode: meso
 
@@ -60,16 +61,67 @@ One finding block per pattern (format in `smell-signatures.md`), ordered by seve
 
 **Adjacent levels offered** — one line each, e.g. "meso map of ledger available on request".
 
+## Batch export
+
+An explicit batch request ("generate all the reports", "map every module") is a user request — Zoom Discipline's offer-don't-dump rule applies to unprompted follow-ups only.
+
+- Enumerate targets from the module inventory. Confirm the list once when it exceeds 3 targets or the scope is ambiguous; proceed unless corrected.
+- One markdown per target in `docs/cartography/` — each the artifact of record for its target. For each, re-verify counts and re-confirm weight/composition shares immediately before writing — one consolidated pass per batch is fine (Zoom Discipline).
+- Include a health report only if the batch request names health/smells.
+- A target too large for one pass: skip it, mark it as "offered — too large for one pass" in the final summary and, when HTML export is part of the batch, in `index.html`. Do not stop the batch to ask.
+- Superseded artifacts from older exports (old-format HTML pages, render scripts): regenerate in place, recommend deleting the superseded script/pages, and never index stale-format files.
+- When HTML export is part of the batch request or separately requested, HTML pages and `index.html` follow the Optional HTML Export section (regenerate the index once at the end, covering all reports).
+
 ## Optional HTML Export
 
-Produce only on request ("export as HTML", "shareable report"). The markdown report is the source of truth; the HTML file is a derived, regenerable view — never hand-edit it, regenerate it from the markdown.
+Produce only on request ("export as HTML", "shareable report"). The markdown report is the source of truth; the HTML files are a derived, regenerable view — never hand-edit them, regenerate them from the markdown.
+
+The export is a **self-contained directory**: all pages plus shared assets under one folder, opening correctly via `file://`, offline, with no server, CDN at view time, or build step. JavaScript is permitted only as a local vendored asset (see Diagrams).
+
+### Output directory
+
+- All exports live in `docs/cartography/` (create directories as needed). If `docs/` does not already exist in the repo, confirm once with the user before creating it.
+- Pages reference assets with relative paths (`assets/...`), never absolute or remote URLs.
+
+### Files
+
+- One page per report: `cartography-<level>-<target>.html` (e.g. `cartography-meso-payments-billing.html`; slugify the target with hyphens, no dots or spaces). The zoom level in the name prevents exports of different levels overwriting each other. Re-exporting the same level+target overwrites the previous file — intended; there is no history.
+- `index.html` — regenerated on every export; never hand-maintained.
+- `assets/mermaid.min.js` — vendored Mermaid v9.4.3 IIFE build, shared by all pages.
+
+### Index
+
+Regenerate `index.html` on every export from what is on disk plus what is known this session:
+
+- Scan `docs/cartography/*.html` (excluding `index.html`), group entries by zoom level (macro / meso / micro / health), sorted alphabetically.
+- Each entry links to the page and shows its target plus a one-line scope taken from the report header.
+- Also list markdown reports known to this session (the artifact of record), linked with a repo-relative path from the HTML location. Do not invent paths for reports you cannot locate.
+- The template must handle N=1 (a single entry) without looking broken.
+- Deterministic: sorted, no timestamps, no generator metadata.
+
+### Navigation
+
+- Every page (including `index.html`) has a plain nav header: `← Index` plus links to parent-context and adjacent-level pages when they exist (meso → its macro page; micro → its macro/meso parent). Relative links only.
+- Static links only — no interactivity. Do not evolve the export into an application — no servers, frameworks, or interactive controls. If live interaction is requested, note it is out of scope for this skill.
+
+### Diagrams
+
+- Render Mermaid client-side with the vendored local asset: `<script src="assets/mermaid.min.js"></script>` plus `<pre class="mermaid">` blocks. Use only the v9.x IIFE build (global `mermaid`); v10+ is ESM-only and is blocked by CORS under `file://`.
+- Asset acquisition: on the first export, download `mermaid.min.js` v9.4.3 into `assets/` if absent (e.g. from jsDelivr); reuse thereafter. If the download fails (offline machine), still emit all pages — diagrams degrade to their source in a styled `<pre>` and the report footer notes "diagrams show source; rerun the export with network access to enable rendering". Never fail the whole export because of assets.
+- Every diagram keeps its Mermaid source in `<details><pre class="mermaid-source">` as the no-JS fallback, so nothing is ever blank.
+- Prose stays pre-rendered HTML — do not client-render markdown. The markdown report remains the artifact of record.
+
+### Handoff
+
+- Final step of any export (including the first): tell the user to open `docs/cartography/index.html` directly in a browser — `file://` works with no server; diagram rendering is guaranteed by the Diagrams section.
+- Never start a server for static reports unless the user explicitly asks.
 
-Produce ONE self-contained file, `cartography-<level>-<target>.html` (e.g. `cartography-meso-payments-billing.html`; slugify the target with hyphens), next to the markdown report — or, if no report file was written this session, ask the user where to save it (default `docs/`). The zoom level in the name prevents exports of different levels overwriting each other.
+### Invariants
 
-- **Self-contained:** one inline `<style>` block. No CDN, no external CSS/JS/fonts, no build step, no server. Must open correctly offline.
-- **No JavaScript:** diagrams render as styled `<pre>` blocks (text diagrams) or inline SVG producible without new dependencies. Keep the Mermaid source in the file (e.g. `<pre class="mermaid-source">`) so the diagram stays manipulable.
+- **Write HTML directly:** no render scripts, build pipelines, or new dependencies (pandoc etc.) — even in batch mode. The regeneration path is re-running this skill, not a committed pipeline; exception only on explicit user request (note the dependency caveat in the reply).
 - **Mirror, don't redesign:** same sections, same order, same content as the markdown report. The HTML adds presentation only (readable typography; `prefers-color-scheme` support optional).
 - **Deterministic:** stable section order, no timestamps, no generator metadata.
 - **Size guard:** render large reports as-is; never paginate, collapse, or add interactivity.
+- **Commit-able:** reports and `assets/` are self-contained and offline-safe; suggest committing them, never silently gitignore.
 
-Do not evolve the export into an application — no servers, frameworks, or interactive controls. If live interaction is requested, note it is out of scope for this skill.
+Decision record: diagrams use a vendored local Mermaid v9.4.3 IIFE; prose is pre-rendered. Rationale: offline rendering, `file://` compatibility, no ESM/CORS issues. Render scripts and build pipelines are banned because agent-regeneration keeps the navigation/diagram/index guarantees that build scripts historically dropped (wai cartography batch, 2026-09-01: a pandoc pipeline produced 12 pages with zero cross-links and unrendered diagrams).

package/content/distilled/codebase-cartography/references/zoom-levels.md

@@ -13,13 +13,19 @@ Adapt import syntax to the language (see language rule below).
 2. Inter-module imports: scan import statements crossing module boundaries. Quoting-safe scan (works in POSIX shells), e.g. JS/TS: `rg 'from ["'"'"']' --type js --type ts` or simply `rg 'import|require'`; then filter by path.
 3. Count edges per pair of modules to get a weighted dependency list.
 4. Determine layering for violation flags: use the repo's declared layering (README/ARCHITECTURE/docs) if present; otherwise infer it from the majority dependency direction and label that inference in the report.
+5. **Weight & composition:** size each module by LOC (default) or file count (mixed-language repos, where LOC is not comparable across languages). Tool: `tokei` (apply the step-1 globs via `tokei -e ...`, or `cloc`); fallback: `rg --files -0 <exclusion globs> | xargs -0 wc -l`, summed per module. Two distinct metrics:
+   - **Weight** (inventory column) — analysis code only, same exclusions as all counts (step 1).
+   - **Composition** (report block) — disk reality: all code grouped by kind (source / test / generated / vendored / config), excluded code included. Classify by path/name conventions (`tests/`, `test_*.py`, `*_test.go`, `*.spec.ts` → test; step-1 exclusion-glob hits → generated/vendored; lockfiles, manifests, dotfiles → config). Works without modules too (flat/script repos): group by top-level directory or language.
+   If neither tool nor fallback works, degrade to file-count-only weight and note it in the report.
 
 **Render:**
 
 Module inventory table:
 
-| Module | Path | Responsibility (one line, from evidence) | Deps out → | Fan-in |
-| :---- | :---- | :---- | :---- | :---- |
+| Module | Path | Responsibility (one line, from evidence) | Weight | Deps out → | Fan-in |
+| :---- | :---- | :---- | :---- | :---- | :---- |
+
+Weight bar: 10-cell `▓/░` bar proportional to the module's share of total weight, rounded to nearest cell, minimum 1 filled cell when weight > 0, followed by an integer percentage — e.g. `▓▓▓▓▓▓▓░░░ 67%`. Weight flags candidate targets for deeper levels; size ≠ complexity (a big cohesive module can be cheaper to map than a small hotspot).
 
 Text dependency matrix (DSM-style). Rows depend on columns; mark `↑` for a dependency that skips a layer or points "backward" against the declared — or inferred (see collect step 4) — layering:
 
@@ -39,7 +45,7 @@ graph TD
   jobs --> core
 ```
 
-**Facts to surface:** layering violations (↑ marks), cycles, hub modules (highest fan-in/out), orphan modules (zero fan-in).
+**Facts to surface:** layering violations (↑ marks), cycles, hub modules (highest fan-in/out), orphan modules (zero fan-in), bulk distribution (largest modules by weight; share of total).
 
 ## Meso — Module / Feature Wiring
 
@@ -97,3 +103,5 @@ RefundRequest{invoiceId, amount} → validated Amount → gateway response → L
 ```
 
 **Facts to surface:** where purity ends (first I/O hop), total hops, state mutated, error paths encountered (report; do not evaluate their quality).
+
+Decision record: macro maps encode scale as a proportional weight bar in the inventory table (treemap area-encoding, phronemophobic "Treemaps are awesome!") plus a Composition block, not as literal treemap graphics — the vendored Mermaid v9.4.3 has no treemap diagram (v11.5+ is ESM-only, CORS-blocked under `file://`) and an ASCII treemap is less diff-able than the bar column. (treemap evaluation, 2026-09-05)

package/content/distilled/context-guardian.md

@@ -12,9 +12,10 @@ You are the Gatekeeper of the Architecture. Before generating any code, always r
 **Directives**:
 1. FORBIDDEN: writing raw logic if a higher-level abstraction exists (no raw fetch() if useApi() exists, no inline error handling if handleError() exists, no raw CSS if a design system exists)
 2. Add `// Reusing: [Name] — avoids duplicating [what]` comments when using existing abstractions
-3. Refusal Protocol: if asked to violate architecture — STOP, explain the rule being violated, propose the resonant alternative instead
+3. File Headers: every new source file opens with a `Purpose / Responsibilities / Rationale` header (see file-headers); when a change alters what a file does or why, update its Rationale in the same change — a stale header misleads. If the Purpose can't be stated in one sentence, the file mixes concerns: flag it for splitting instead of writing a vague header
+4. Refusal Protocol: if asked to violate architecture — STOP, explain the rule being violated, propose the resonant alternative instead
 
 **Output structure for every response**:
 1. Reuse Plan: "I will build X using [existing abstractions]. I need new code for [only what's new]."
 2. Code (with Reusing comments)
-3. Verification checklist: all abstractions reused? no raw logic where abstraction exists? style conventions followed?
+3. Verification checklist: all abstractions reused? no raw logic where abstraction exists? style conventions followed? file headers present (new files) and current (changed files)?

package/content/distilled/create-issues/SKILL.md

@@ -1,4 +1,4 @@
-<!-- skill: create-issues, version: 1.3.0, status: verified -->
+<!-- skill: create-issues, version: 1.4.0, status: verified -->
 # Tracer-Bullet Issue Creation from Plan
 
 Break a reviewed plan into independently grabbable issues using tracer-bullet vertical slices.
@@ -45,6 +45,7 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
      - end-to-end behavior description
      - concrete file paths or subsystems when knowable
      - binary acceptance criteria
+     - a **file-header criterion** when the slice creates source files or changes a file's contract: new files open with `Purpose / Responsibilities / Rationale`; contract-changing edits update Rationale (see `file-headers`)
      - a **Verifiable Value Claim** where measurable: quantified **Must** gate (unit + number, no adjectives), a runnable **Meter** command, the measured **Baseline**, and the **regression suite** that must keep passing
      - **anti-goals** whenever the ticket touches tests, lockfiles, or public interfaces (prohibit test-assertion edits, dependency additions, API breaks)
      - explicit blocked-by field
@@ -83,6 +84,7 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
 - **Workflow integrity:** TDD and Tidy First language is mandatory in every implementation issue.
 - **No guessed IDs:** capture identifiers from actual command output.
 - **Quantify the gate:** every measurable acceptance criterion is a number with a unit, backed by a runnable Meter command.
+- **Self-describing files:** tickets that create source files or change a file's contract carry the file-header criterion (see `file-headers`).
 - **Name the cheats:** add anti-goals wherever the gate could be gamed (test edits, new deps, API breaks).
 - **Anchor staleness:** always record `base_commit` metadata at creation; never publish a ticket anchored to nothing.
 - **Stop and ask:** if the plan only supports horizontal decomposition, propose a vertical rewrite before publishing.

package/content/distilled/create-issues/references/templates.md

@@ -43,6 +43,7 @@ Ref: [Link to plan/spec file and section]
 - [ ] [Binary, observable criterion 1]
 - [ ] [Binary, observable criterion 2]
 - [ ] [Automated tests cover the slice end-to-end]
+- [ ] [When the slice creates source files or changes a file's contract: file-header criterion — new files carry Purpose/Responsibilities/Rationale; changed files update Rationale (see `file-headers`)]
 
 ## Blocked by
 

package/content/distilled/file-headers.md

@@ -0,0 +1,26 @@
+<!-- Full version: content/prompt-system-file-headers.md -->
+You enforce file-header documentation on source code. Every source file must be self-describing: an agent opening any file must learn what it does and why it exists without reading the implementation or hunting for context.
+
+**HEADER FORMAT** (adapt the comment syntax to the language — `#`, `//`, `--`, `"""docstring"""`, or a top doc comment):
+
+```
+# Purpose: <one sentence — what this file does and for whom>
+# Responsibilities:
+# - <bullet 1 — the cohesion contract; one concern per bullet>
+# - <bullet N>
+# Rationale: <latest design decision and why, with issue/PR link>
+#   <earlier rationale entries belong in the issue tracker / git history>
+```
+
+**Rules:**
+1. Every NEW source file opens with a complete header before any logic.
+2. When a modification changes what a file does or why, update the header in the same change — a stale header is worse than none. Do not touch the header for behavior-preserving edits.
+3. Purpose is one sentence. If you cannot state it in one sentence, the file likely mixes concerns — flag it for splitting (see modularity-diagnostician) rather than writing a vague header.
+4. Rationale keeps only the latest entry. History lives in the issue tracker and git, not the file.
+5. Exclusions: generated files, vendored code, config, lockfiles, docs, and build artifacts get no header.
+
+**Scope — "source file" means:** files containing logic or defining structure written by this project (modules, classes, scripts, routes, components, tests). Not applicable to READMEs, org notes, or one-liner re-exports.
+
+**Audit:** to find missing headers: `grep -rLE "(Purpose:|@purpose)" --include=<source-extensions> .` excluding vendored/generated paths. Every hit is a gap.
+
+**Output:** when adding or updating headers, show file → header block. When a file fails Rule 3 (undescribable), report it as a modularity finding with the offending concerns listed.

package/content/distilled/implement-plan/SKILL.md

@@ -11,6 +11,7 @@ Implement an approved plan using Red, Green, Refactor.
    - Implement the minimum code to pass.
    - Refactor while keeping tests green.
    - Run the success criteria checks.
+   - Check file headers: new source files open with Purpose/Responsibilities/Rationale; files whose contract changed have a current Rationale (see `file-headers`).
    - Update the plan with progress.
 4. Use `references/verification-template.md` when reporting phase completion.
 5. Use `references/common-situations.md` when the plan and reality diverge.
@@ -19,5 +20,6 @@ Implement an approved plan using Red, Green, Refactor.
 
 - Never skip the red phase.
 - Complete one phase at a time.
+- Review file headers before declaring a phase complete: new files must carry them, and contract-changing edits must leave the Rationale current (see `file-headers`).
 - Do not blindly follow an outdated plan if the codebase contradicts it.
 - Wait for user confirmation before proceeding to the next phase.

package/content/distilled/implement-plan/references/verification-template.md

@@ -5,6 +5,7 @@ Automated verification:
 - [x] All tests pass
 - [x] Type checking passes
 - [x] Build succeeds
+- [x] File headers current: new files carry Purpose/Responsibilities/Rationale; changed files updated Rationale (see `file-headers`)
 
 Manual verification needed:
 - [ ] [Manual step 1]

package/content/distilled/issue-review/SKILL.md

@@ -28,6 +28,7 @@ Treat the best issue sets as:
 - minimal but sufficient dependency graphs
 - explicit about AFK vs HITL work
 - traceable back to stories, plans, or specs
+- self-describing: tickets that create or reshape source files carry the file-header criterion (see `file-headers`) — undocumented files force agents to re-derive intent
 - machine-verifiable value claims: quantified Must gate, runnable Meter, explicit anti-goals, and a `base_commit` anchor that reveals staleness
 
 ## Rules

package/content/distilled/issue-review/references/pass-5-executability.md

@@ -4,6 +4,7 @@ Focus on:
 - Can another developer or agent pick this up immediately?
 - Are verification steps concrete and end-to-end?
 - Is there a machine-checkable Must gate (quantified, unit + number) backed by a runnable Meter command?
+- Are touched code files self-describing — Purpose/Responsibilities/Rationale header present and current (see `file-headers`)?
 - Are priorities and labels sensible?
 - Are HITL handoff points explicit?
 - Is it clear what demo, test, or observable behavior proves completion?
@@ -15,6 +16,7 @@ Watch for:
 - Qualitative acceptance criteria with no unit or threshold ("fast", "robust", "clean") — a Scale/Meter is missing
 - A Meter command that cannot run at the ticket's `base_commit` (stale claim) or that no fresh agent could execute verbatim
 - Missing anti-goals on tickets touching tests, lockfiles, or public interfaces (reward-hacking surface: nothing stops gaming the gate)
+- Tickets that create or reshape source files with no file-header acceptance criterion — undocumented files force every implementing agent to re-derive intent
 - No regression suite named (pass-to-pass coverage unspecified)
 - HITL work masquerading as AFK
 - Tickets that cannot be closed without information from another issue not listed as a blocker

package/content/distilled/modularity-diagnostician.md

@@ -23,6 +23,7 @@ Step 1 — Detect Modularity Signals: Read all files. Identify:
 - High Afferent Coupling (Medium): module depended upon by many consumers — alterations trigger widespread ripple effects
 - Temporal Coupling (Medium): files co-changing in commits despite no static dependency — reveals hidden dependencies (skip if no git/co-change data provided)
 - Missing Boundary (Medium): related functionality spread across modules with no clear owning package
+- Undescribable Module (Medium): a file's purpose cannot be stated in one sentence — the file-header Purpose is missing, stale, or forced to be vague (see `file-headers`). The header is the cohesion contract; needing three sentences means the module is doing three jobs
 Note file, line range, and description for each.
 
 Step 2 — Classify Modularity Scope: For each signal, assess:

package/content/distilled/resonant-refactor.md

@@ -41,5 +41,6 @@ Self-correction: on failure, attempt fix up to 3 times. If all 3 fail: run `git
 - Run linter on modified files
 - Run full test suite
 - Add docstring to new abstraction: what it does, why it exists, parameters
+- File headers: every touched source file has a `Purpose / Responsibilities / Rationale` header (see `file-headers`); contract-changing edits update the Rationale with this refactor's reason and issue link
 
-**Completion Report**: files modified, verification pass/fail, linter pass/fail, tests pass/fail, abstraction documented, recommended next step.
+**Completion Report**: files modified, verification pass/fail, linter pass/fail, tests pass/fail, abstraction documented, file headers updated, recommended next step.

package/content/distilled/tdd/SKILL.md

@@ -1,4 +1,4 @@
-<!-- skill: tdd, version: 1.1.0, status: verified -->
+<!-- skill: tdd, version: 1.2.0, status: verified -->
 # Plan-Implement-Verify (TDD)
 
 Implement features or fixes using a disciplined, phase-based Test-Driven Development (TDD) workflow to ensure correctness, testability, and incremental progress.
@@ -19,7 +19,7 @@ You are a TDD Practitioner. Your goal is to ensure that no code is written witho
     *   **Step 1: Write Failing Test (RED):** Write a test that describes the desired behavior. Run it and **confirm it fails** for the expected reason.
     *   **Step 2: Implement Minimal Code (GREEN):** Write the simplest code possible to make the test pass. Run tests to confirm they are green.
     *   **Step 3: Refactor If Needed:** Clean up the implementation while keeping tests green.
-    *   **Step 4: Verify Phase Completion:** Run full automated suites (tests, type-check, lint) and perform manual verification.
+    *   **Step 4: Verify Phase Completion:** Run full automated suites (tests, type-check, lint), perform manual verification, and confirm every new source file opens with a Purpose/Responsibilities/Rationale header and every file whose contract changed has a current Rationale (see `file-headers`).
     *   **Step 5: Inform User:** Present a summary of phase completion and wait for verification.
 
 3.  **Verification (CRITICAL):**
@@ -32,6 +32,7 @@ You are a TDD Practitioner. Your goal is to ensure that no code is written witho
 - **One Phase at a Time:** Complete and verify a phase before starting the next.
 - **Keep Tests Green:** Never leave the codebase in a failing state at the end of a turn.
 - **Update Plan:** Mark phases as complete as you progress.
+- **Self-Describing Files:** A phase is not complete if new files lack headers or contract-changing edits left headers stale (see `file-headers`).
 
 ## References
 - **Templates:** Use `references/templates.md` for plans and phase completion summaries.

package/content/distilled/tdd/references/criteria.md

@@ -16,6 +16,7 @@ Use these criteria to evaluate the quality of a TDD session.
 - [ ] Automated tests (unit, integration) cover new logic.
 - [ ] No regressions introduced in existing functionality.
 - [ ] Type-checking and linting are passing globally.
+- [ ] New source files carry Purpose/Responsibilities/Rationale headers; changed files have current Rationale (see `file-headers`).
 - [ ] Plan is updated to reflect current progress.
 
 ## When to Stop & Ask

package/content/distilled/whisper/SKILL.md

@@ -1,97 +1,61 @@
 ---
 name: whisper
-description: "Manage the ~/.whisper/ knowledge workspace: init, check, status, link plan to beads, decommission, and knowledge routing. Trigger when the user says '/whisper', '/w', 'init workspace', 'check workspace', 'workspace status', 'link plan', or 'decommission worktree'."
+description: "Deterministic knowledge workspace management: init, check, status, link plan, decommission, and knowledge routing. Delegates the mechanical steps to the turu CLI (whisper-vibes) when installed; manual fallbacks otherwise. Trigger when the user says '/whisper', '/w', 'init workspace', 'check workspace', 'workspace status', 'link plan', or 'decommission'."
 tools: Read, Write, Edit, Bash
 ---
 
-# Whisper — Accumulated Operational Knowledge
+# Whisper — Deterministic Operational Knowledge
 
-Manage `~/.whisper/` — a global, tiered knowledge directory that accumulates operational knowledge and planning context across all your work. Works with or without beads issue tracking.
+> **This skill is a thin pointer.** The canonical, versioned copy ships with
+> the `turu` CLI ([charly-vibes/whisper](https://github.com/charly-vibes/whisper),
+> `cargo install whisper-vibes`) — install it with `turu skill install`.
+> This file stays so agents without the binary have fallbacks.
 
-## Directory Layout
+The `turu` CLI owns every mechanical step: canonical repo keys, branch slugs,
+worktree slots, and scope routing. Same inputs, same outputs — no more
+hand-rolled shell pipelines.
 
-```
-~/.whisper/
-  rules.md                          ← Global agent behavior rules (bd remember equiv)
+## Decision procedure
 
-  repos/
-    github.com/user/repo/
-      env.md                        ← Repo-wide: deploy commands, infra facts, auth quirks
-      branches/
-        branch-slug/                ← One slot per branch (/ in name → -- in slug)
-          context.md                ← Branch anchor: repo, branch, beads epic ID, status
-          plan.md                   ← Narrative implementation plan
-          notes.md                  ← Free-form scratch and findings
-          agents/                   ← Optional sub-agent files when work is split across agents
-      worktrees/
-        worktree-name/              ← One slot per worktree (basename of worktree path)
-          env.md                    ← Worktree-specific: ports, venvs, credentials, local-only setup
-```
+1. **Is `turu` available?** Run `turu key --json`.
+2. **If yes** — everything mechanical is a turu command:
 
-**Branch slug rule:** `git rev-parse --abbrev-ref HEAD | sed 's|/|--|g'`
-
-**Worktree slot rule:** `basename $(git rev-parse --git-common-dir 2>/dev/null)` (the `.git` worktree dir name), or `basename $(pwd)` when not in a worktree.
-
-**Canonical repo key rule — derive it, never invent it:**
-
-```bash
-repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|http://||;s|ssh://||;s|git@||;s|:|/|g;s|\.git$||')
-[ -z "$repo_url" ] && repo_url="local/$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")"
-```
-
-`git@cv:org/repo.git` → `cv/org/repo`; `https://github.com/u/r` → `github.com/u/r`; no remote → `local/<repo-name>`. Colons always become slashes (keeps keys path-safe). The same key must come out of the same repo on every machine.
-
-If a directory keyed some other way already exists for this repo (bare name like `genesis/`, owner-only like `charly-vibes/`, alias host with a colon like `cv:charly-vibes/`), do **not** add a fourth variant — route new knowledge into the canonical key and offer `/w consolidate` to migrate the legacy one.
-
-## Knowledge Routing
-
-When a session learns something worth keeping, route it by scope:
-
-| Scope | Test | Destination |
-|---|---|---|
-| **Global** | True for every repo and every project | `~/.whisper/rules.md` — append, don't overwrite |
-| **Repo-wide infra** | True regardless of which branch or feature you're on (deploy behavior, gateway/timeout limits, log retention, auth quirks) | `~/.whisper/repos/<host>/<repo>/env.md` — create or extend |
-| **Branch-specific** | Only matters for the work on *this* epic/branch | `~/.whisper/repos/<host>/<repo>/branches/<slug>/notes.md`, or `bd note <epic-id>` if beads is available |
-| **Worktree setup** | Credentials, service IDs, ports, venv/docker specifics for *this checkout* | `~/.whisper/repos/<host>/<repo>/worktrees/<name>/env.md` |
-| **Universal agent rule** | A standing instruction for how the agent should behave, independent of any branch or repo | `bd remember` if available, else `~/.whisper/rules.md` |
-
-**Rules:**
-- **No secrets anywhere.** Never write tokens, keys, passwords, or PII into `~/.whisper/`.
-- **Extend, don't duplicate.** Append to or correct an existing note rather than creating a new one that says the same thing.
-- **One repo, one key.** If more than one `repos/` directory belongs to the same repo, write into the canonical key and propose `/w consolidate` — never create a new variant.
-- **Search first.** Before creating a new entry, check if one already exists for the same topic.
-- If `bd` is not available, everything falls back to `~/.whisper/` files — there's no beads-backed alternative.
-
-## Modes
-
-Determine mode from how the skill is triggered:
-
-| Trigger | Mode |
+| Intent | Command |
 |---|---|
-| `/w init` or `~/.whisper/` does not exist | **init** |
-| `/w` or `/w status` | **status** |
-| `/w check` or called by `renew` | **check** |
-| `/w link [<path>]` or "link plan" | **link** |
-| `/w decommission` | **decommission** |
-| `/w consolidate` or "dedupe whisper repos" | **consolidate** |
-
-See each reference file for the full procedure:
+| Derive repo key / branch slug / worktree slot | `turu key --json` |
+| Find the write destination for a scope | `turu resolve <scope> --json` |
+| Record knowledge (extend, don't duplicate) | `turu append <scope> --text "..."` |
+| Create the workspace layout | `turu init --json` |
+| Inspect paths and existence | `turu status --json` |
+| Validate / detect legacy keys | `turu check --json` · `turu doctor --json` |
+| Refresh the AGENTS.md routing block | `turu sync --json` |
+
+   Scopes: `global` (rules.md), `repo` (env.md), `branch` (notes.md),
+   `worktree` (env.md), `group` (shared workspace for a set of repos).
+   If a `<!-- TURU:START -->` block exists in `AGENTS.md`, read the routing
+   map from there instead of re-deriving paths.
+
+3. **If no** — use the manual fallbacks in `references/` (they remain the
+   source of truth for the shell-snippet procedures) and suggest
+   `cargo install whisper-vibes`.
+
+## Invariants (with or without the binary)
+
+- **No secrets anywhere.** Never write tokens, keys, passwords, or PII into
+  the workspace.
+- **Extend, don't duplicate.** Append to or correct an existing note rather
+  than creating a new one that says the same thing.
+- **One repo, one key.** The canonical key is a pure function of the remote
+  URL; never invent a variant.
+- **Search first.** Before creating a new entry, check if one exists.
 
-- `references/init.md`
-- `references/check.md`
-- `references/status.md`
-- `references/link.md`
-- `references/decommission.md`
-- `references/consolidate.md`
+## Modes
 
-## Rules
+`/w init` → `turu init` · `/w` or `/w status` → `turu status` ·
+`/w check` → `turu check` · `/w link` → `subs/link-manual` (no CLI verb yet)
+· `/w decommission` → `subs/decommission-manual` · `/w consolidate` →
+`subs/consolidate-manual` (detection ships via `turu doctor`).
 
-- Never run `git worktree remove` automatically — always print the command for the user to execute.
-- Never close beads issues during decommission — only defer. Closing is intentional.
-- **One epic per branch, children via `--parent`, not flat siblings.**
-- **`env.md` is shared and immutable across branch switches.** Never overwrite it during init or check — only create if absent.
-- **Branch slug sanitization is mandatory.** Always run `sed 's|/|--|g'` on the branch name before using it as a directory path.
-- **Worktree reuse across branches is normal, not an edge case.** Expect multiple slots to accumulate in `branches/` over time.
-- **Legacy layout is still the common case.** Most worktrees never needed multiple branch slots — only migrate when a mismatch is detected.
-- This skill is self-contained. Do not rely on `create-plan`, `park`, or `create-handoff` having `~/.whisper/` awareness.
-- If `bd` is not initialized in the repo, skip beads steps gracefully and note what was skipped.
+Manual procedures for each mode: `references/init.md`, `references/check.md`,
+`references/status.md`, `references/link.md`, `references/decommission.md`,
+`references/consolidate.md`.