incitaciones 0.8.0 → 0.9.0

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/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
 
@@ -65,7 +66,7 @@ One finding block per pattern (format in `smell-signatures.md`), ordered by seve
 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 immediately before writing (Zoom Discipline).
+- 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.

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

package/content/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2026-09-01",
+  "version": "2026-09-15",
   "schema_version": "1.1",
   "prompts": [
     {
@@ -3013,6 +3013,26 @@
         "reviews"
       ]
     },
+    {
+      "name": "file-headers",
+      "type": "system",
+      "title": "File Headers (Self-Describing Source Files)",
+      "description": "Convention enforcing a Purpose/Responsibilities/Rationale header on every source file, so agents learn intent without reverse-engineering and undescribable files expose cohesion violations",
+      "source": "content/prompt-system-file-headers.md",
+      "distilled": "content/distilled/file-headers.md",
+      "tags": [
+        "documentation",
+        "architecture",
+        "modularity",
+        "code-quality",
+        "system-prompt",
+        "rationale"
+      ],
+      "bundles": [
+        "refactoring",
+        "documentation"
+      ]
+    },
     {
       "name": "edge-case-discovery",
       "type": "task",
@@ -3579,7 +3599,7 @@
       "name": "whisper",
       "type": "workflow",
       "title": "Whisper — Accumulated Operational Knowledge",
-      "description": "Manage the ~/.whisper/ knowledge workspace: init, check, status, link plan, decommission, and knowledge routing",
+      "description": "Deterministic knowledge workspace management: init, check, status, link plan, decommission, and knowledge routing. Thin pointer — delegates to the turu CLI (whisper-vibes) when installed, manual fallbacks otherwise",
       "source": "content/prompt-workflow-whisper.md",
       "distilled": "content/distilled/whisper/SKILL.md",
       "skill_format": "progressive-disclosure",
@@ -3893,16 +3913,16 @@
   ],
   "bundles": {
     "essentials": {
-      "description": "Core prompts for everyday development",
+      "description": "Daily-driver skills, selected by measured usage: the top 8 of the pi session skill-usage analysis (621 sessions, 43 repos, 2026-04..07) — commit, rule-of-5-universal, tdd, issue-review, debug, create-issues, create-handoff, grill-me",
       "prompts": [
         "commit",
+        "rule-of-5-universal",
+        "tdd",
+        "issue-review",
         "debug",
-        "describe-pr",
-        "code-review",
-        "research-codebase",
+        "create-issues",
         "create-handoff",
-        "resume-handoff",
-        "whisper"
+        "grill-me"
       ]
     },
     "planning": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "incitaciones",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Reusable prompts and skills for CLI LLM tools, with native pi package support.",
   "repository": {
     "type": "git",

package/pi-package/prompts/file-headers.md

@@ -0,0 +1,10 @@
+---
+description: "Shortcut for the file-headers skill. Convention enforcing a Purpose/Responsibilities/Rationale header on every source file, so agents learn intent without reverse-engineering and undescribable files expose cohesion violations"
+---
+<!-- installed-from: incitaciones -->
+
+Use the installed `file-headers` skill for this task.
+
+If the skill is not automatically loaded, invoke `/skill:file-headers` and follow it.
+
+User context: $@

package/pi-package/prompts/whisper.md

@@ -1,5 +1,5 @@
 ---
-description: "Shortcut for the whisper skill. Manage the ~/.whisper/ knowledge workspace: init, check, status, link plan, decommission, and knowledge routing"
+description: "Shortcut for the whisper skill. Deterministic knowledge workspace management: init, check, status, link plan, decommission, and knowledge routing. Thin pointer — delegates to the turu CLI (whisper-vibes) when installed, manual fallbacks otherwise"
 ---
 <!-- installed-from: incitaciones -->
 

package/pi-package/skills/close/SKILL.md

@@ -14,14 +14,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/pi-package/skills/code-review/SKILL.md

@@ -4,7 +4,7 @@ description: "Multi-pass code review using Rule of 5 principle"
 metadata:
   installed-from: "incitaciones"
 ---
-<!-- 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/pi-package/skills/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/pi-package/skills/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
 
@@ -65,7 +66,7 @@ One finding block per pattern (format in `smell-signatures.md`), ordered by seve
 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 immediately before writing (Zoom Discipline).
+- 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.

package/pi-package/skills/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/pi-package/skills/context-guardian/SKILL.md

@@ -18,9 +18,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/pi-package/skills/create-issues/SKILL.md

@@ -4,7 +4,7 @@ description: "Generate trackable issues from implementation plans"
 metadata:
   installed-from: "incitaciones"
 ---
-<!-- 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.
@@ -51,6 +51,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
@@ -89,6 +90,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/pi-package/skills/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/pi-package/skills/file-headers/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: file-headers
+description: "Convention enforcing a Purpose/Responsibilities/Rationale header on every source file, so agents learn intent without reverse-engineering and undescribable files expose cohesion violations"
+metadata:
+  installed-from: "incitaciones"
+---
+<!-- 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/pi-package/skills/implement-plan/SKILL.md

@@ -17,6 +17,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.
@@ -25,5 +26,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/pi-package/skills/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/pi-package/skills/issue-review/SKILL.md

@@ -34,6 +34,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/pi-package/skills/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/pi-package/skills/modularity-diagnostician/SKILL.md

@@ -29,6 +29,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/pi-package/skills/resonant-refactor/SKILL.md

@@ -47,5 +47,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/pi-package/skills/tdd/SKILL.md

@@ -4,7 +4,7 @@ description: "Test-driven development workflow"
 metadata:
   installed-from: "incitaciones"
 ---
-<!-- 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.
@@ -25,7 +25,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):**
@@ -38,6 +38,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/pi-package/skills/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/pi-package/skills/whisper/SKILL.md

@@ -1,103 +1,67 @@
 ---
 name: whisper
-description: "Manage the ~/.whisper/ knowledge workspace: init, check, status, link plan, decommission, and knowledge routing"
+description: "Deterministic knowledge workspace management: init, check, status, link plan, decommission, and knowledge routing. Thin pointer — delegates to the turu CLI (whisper-vibes) when installed, manual fallbacks otherwise"
 metadata:
   installed-from: "incitaciones"
 ---
 ---
 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`.

package/scripts/cli.mjs

@@ -1,7 +1,12 @@
 #!/usr/bin/env node
+// Purpose: Install incitaciones skills from the manifest into agent tools (pi, Claude Code, Amp, Gemini CLI, etc.) from the command line.
+// Responsibilities:
+// - Resolve the manifest and bundles (npx incitaciones install [--bundle|--tool])
+// - Copy distilled skills into each tool's expected directory layout
+// - List available skills and show per-skill details (list, info)
+// Rationale: standalone npm CLI (bin: scripts/cli.mjs) so installs don't require cloning the repo; manifest is the single source of truth for what ships (bd: incitaciones packaging).
+
 /**
- * incitaciones CLI — Install LLM agent skills across tools.
- *
  * Usage:
  *   npx incitaciones               Install all skills (default)
  *   npx incitaciones install       Install all skills

package/scripts/generate-pi-resources.mjs

@@ -1,4 +1,9 @@
 #!/usr/bin/env node
+// Purpose: Regenerate the pi-package resources (skills + prompts) from content/manifest.json for npm publishing.
+// Responsibilities:
+// - Reset and populate pi-package/skills and pi-package/prompts from the manifest's distilled entries
+// - Run on v* tag pushes via .github/workflows/npm-publish.yml before publish
+// Rationale: pi packages need a flat resource layout that differs from the repo's source+distilled duality; generating keeps the published form derived, never hand-maintained.
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";