incitaciones 0.7.0 → 0.9.0

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.7.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/SKILL.md

@@ -37,11 +37,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.
@@ -54,4 +55,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/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
 
@@ -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/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