incitaciones 0.4.0 → 0.6.0

package/README.md

@@ -93,8 +93,8 @@ After changing distilled content or manifest entries, run `just generate-pi-reso
 ### Publishing a new version
 
 ```bash
-npm version patch   # bumps to 0.2.1, creates a git tag
-npm version minor   # bumps to 0.3.0
+npm version patch   # bumps to 0.5.1, creates a git tag
+npm version minor   # bumps to 0.6.0
 npm version major   # bumps to 1.0.0
 
 git push --tags     # triggers CI → auto-publishes to npm

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

@@ -0,0 +1,51 @@
+# Codebase Cartography
+
+Map a codebase's structure as text-based architecture diagrams at three zoom levels, with optional structural-health triage.
+
+You are a cartographer, not a critic: you document topology, dependencies, and boundaries as they exist. You do not recommend changes unless an explicit diagnostic pass was requested.
+
+## Zoom Levels
+
+- **macro** — whole-system topology: modules/domains, dependency direction, layering.
+- **meso** — one module or feature: internal components, wiring, integration contracts.
+- **micro** — one functionality: call chain, data flow, state mutation, I/O boundaries.
+
+Pick the entry level from the request:
+
+| Request shape | Entry level | Typical ask |
+| :---- | :---- | :---- |
+| "map this repo", onboarding | macro | lay of the land |
+| "how does <module> work", wiring | meso | structure of one district |
+| "trace <functionality>", "where does X happen" | micro | end-to-end path |
+
+## Procedure
+
+1. Clarify the target if ambiguous. State the entry zoom level explicitly in the output.
+2. Gather evidence by searching — imports, entry points, directory layout, call sites. Never infer structure from names alone.
+3. Render the entry-level map plus one adjacent level for context (parent overview when starting micro/meso; child detail when starting macro).
+4. Run the health check only if requested.
+5. Produce the report using the template.
+
+**Reference loading protocol — read on demand:**
+
+- 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`.
+
+## Zoom Discipline
+
+- Offer adjacent levels as follow-ups; never dump all three maps unrequested.
+- 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.
+- If the target is too large for one pass, map boundaries first and ask which module or area to enter.
+
+## Rules
+
+- Describe structure as it exists; no refactor advice outside an explicit diagnostic request.
+- Cycles, hotspots, and boundary violations are facts to report, not flaws to fix.
+- 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.

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

@@ -0,0 +1,75 @@
+# Report Template
+
+Structure the final output by mode. All modes share the closing sections. Keep maps as tables/Mermaid — diff-able artifacts.
+
+## Header (all modes)
+
+```
+## Cartography — <target>
+**Entry zoom level:** macro | meso | micro
+**Scope covered:** <paths examined>
+```
+
+## Mode: macro
+
+1. **Module inventory** — table (module, path, responsibility, 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
+
+## Mode: meso
+
+1. **Parent context** — 2-3 lines: where this module sits in the macro map
+2. **Component table** — components, paths, roles, internal links, external ports
+3. **Wiring graph** — Mermaid with mechanism-labeled edges
+4. Structural observations
+
+## Mode: micro
+
+1. **Entry point** — symbol and file:line
+2. **Call chain** — numbered hops with file:line and purity/I-O markers
+3. **Data flow** — transformation list from input to outputs/side effects
+4. Structural observations
+
+## Mode: health check (additive to any level)
+
+One finding block per pattern (format in `smell-signatures.md`), ordered by severity. If nothing found, state the patterns checked and the evidence gathered — absence of findings without evidence of search is not a result.
+
+## Closing sections (all modes)
+
+**Key Relationships** — top 3-5 dependencies that explain the structure:
+
+```
+- web → api (all requests funnel here; 34 call sites)
+- ledger ← webhooks (cycle with billing; see observations)
+```
+
+**Structural Observations** — facts only, no fixes:
+
+```
+- Cycle: billing → webhooks → ledger → billing (3 modules)
+- Hotspot: core/ledger.ts imported by 14 modules
+- Layer skip: web/cli imports infra/db directly (5 files)
+```
+
+**Open Questions** — what the cartographer could not resolve, for human follow-up:
+
+```
+- Is the billing → ledger edge intentional or legacy? (no test covers it)
+```
+
+**Adjacent levels offered** — one line each, e.g. "meso map of ledger available on request".
+
+## 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 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.
+
+- **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.
+- **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.
+
+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.

package/content/distilled/codebase-cartography/references/smell-signatures.md

@@ -0,0 +1,58 @@
+# Anti-Pattern Signatures — Agent-Computable Proxies
+
+Structural health check. Each anti-pattern from the visual framework is reduced to evidence an agent can gather by search and counting. Report findings; do not propose fixes unless explicitly asked.
+
+## Report Format (per finding)
+
+```
+[PATTERN] severity: high|medium|low
+Evidence: file:line list or matrix marks
+Quantity: loop members / fan-out count / depth / ratio
+```
+
+Severity scales with blast radius: fan-out count, number of affected modules, loop size.
+
+## Signature Catalog
+
+### Circular Dependencies
+
+- **Proxy:** closed loops in the module or component graph. Build the dependency list (see `zoom-levels.md` macro), then trace: if A → B → … → A exists, report the full loop.
+- **Quick scan:** mutual imports between two files (`rg` for A importing B, then B importing A); module-pair matrix marks both ways.
+- **Severity:** loop spanning multiple top-level modules > intra-module pair.
+
+### God Object
+
+- **Proxy:** one file/class with extreme fan-in AND fan-out, plus size. Check: file length (`wc -l`), count of exported methods/attributes, count of distinct importers (`rg -l "from .*<module>" | wc -l`), count of its own imports.
+- **Thresholds:** relative to the repo baseline — flag when a file is ~3× the median size AND importers are ~3× the median. State the baseline numbers used. In tiny repos (< ~10 files of the same kind), the median is meaningless — fall back to absolute judgment (e.g., one file dominating all coupling) and label the weak baseline.
+- **Severity:** grows with importer count (every change touches all of them).
+
+### Shotgun Surgery
+
+- **Proxy:** one concept scattered across many modules. Pick a domain concept from the target question (e.g., "invoice", "permissions") and count modules containing references to it: `rg -l "<concept>" | cut -d/ -f1-2 | sort -u | wc -l`.
+- **Severity:** grows with module count and with coupling between the scattered sites (do they import each other or duplicate?).
+
+### Feature Envy
+
+- **Proxy:** a module imports another module far more than its own internals. Count both sides and compare — imports of the foreign module: `rg -c "from .*<moduleX>" moduleA/`; imports resolving inside moduleA (relative `./` imports): `rg -c "from '\./" moduleA/`. Flag when the foreign count exceeds the local count by ~2× or more.
+- **Severity:** medium when it is one direction; high when the envying module is otherwise nearly disconnected from its own parent.
+
+### Deep Inheritance
+
+- **Proxy:** chains of `extends`/subclassing beyond ~3 levels: `rg "extends "` then follow each chain. Report max depth and the chain.
+- **Severity:** medium; flag deepest chain only, not every chain.
+
+### Pure/Impure Entanglement (functional codebases)
+
+- **Proxy:** business-logic functions directly performing I/O (network, DB, filesystem, clock, randomness) instead of receiving results as parameters. Verify by reading the call chain at micro level: mark the first impure hop and whether logic continues after it.
+- **Severity:** high when the same file mixes domain rules and I/O calls repeatedly (report count).
+
+### Broken Composition (layer-skipping)
+
+- **Proxy:** dependencies that bypass an architectural interface layer — e.g., web module importing infra directly instead of going through the api/service layer. Visible as ↑ marks in the macro matrix (a dependency pointing against the repo's declared or evident layering).
+- **Severity:** scales with how many files take the shortcut.
+
+## Interpretation Rules
+
+- One finding per pattern per target; list all instances under Evidence.
+- If the pattern is suspected but evidence is thin, say "suspected, evidence: <what's missing>" instead of asserting.
+- Findings are facts about structure. The user decides what to do with them.

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

@@ -0,0 +1,99 @@
+# Zoom Levels — Evidence Collection & Rendering
+
+Per-level collection strategy and text rendering formats. Match the rendering to what the level must show; the paradigm-scale principle applies: module-level relations read best as matrices/graphs, functionality reads best as ordered chains.
+
+## Macro — System Topology
+
+**Collect:**
+
+Adapt import syntax to the language (see language rule below).
+
+0. **Language rule:** use the repo's import syntax for scans. JS/TS: `from './x'`; Python: `import x` / `from x import`; Rust: `use x::`; Go: `go list -deps`; Java: `import x.y;`. If the repo is multi-language, run the scan per language.
+1. Top-level directory layout (`ls`, tree to depth 1–2). Identify likely module boundaries (packages, workspaces, domains). Exclude vendored/generated code (`node_modules`, `dist`, `target`, `vendor`, generated committed sources) from all counts — `rg` respects `.gitignore` by default, but generated-but-committed code must be excluded with explicit globs (`-g '!dist'`).
+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.
+
+**Render:**
+
+Module inventory table:
+
+| Module | Path | Responsibility (one line, from evidence) | Deps out → | Fan-in |
+| :---- | :---- | :---- | :---- | :---- |
+
+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:
+
+|  | core | api | web | jobs |
+| :---- | :---- | :---- | :---- | :---- |
+| core | — |  |  |  |
+| api | ✦ | — |  |  |
+| web | ✦ | ✦ | — |  |
+| jobs | ✦ |  | ↑ | — |
+
+Module graph (Mermaid), one node per module, edges labeled with edge counts:
+
+```mermaid
+graph TD
+  web --> api
+  api --> core
+  jobs --> core
+```
+
+**Facts to surface:** layering violations (↑ marks), cycles, hub modules (highest fan-in/out), orphan modules (zero fan-in).
+
+## Meso — Module / Feature Wiring
+
+**Collect:**
+
+1. Entry points of the module: exported symbols, route registrations, message handlers, CLI commands.
+2. Internal components: classes/functions by responsibility; group by subdirectory.
+3. Integration contracts: interfaces implemented, events published/consumed, external clients (HTTP, DB, queues).
+4. Which other modules call in, and which the module calls out to.
+
+**Render:**
+
+Component table:
+
+| Component | Path | Role | Talks to (internal) | External ports |
+| :---- | :---- | :---- | :---- | :---- |
+
+Wiring graph (Mermaid). Show direction and label edges with the mechanism (calls, publishes, reads):
+
+```mermaid
+graph LR
+  routes --> service
+  service --> repo
+  service -- "publishes InvoicePaid" --> bus
+  repo -- SQL --> [(db)]
+```
+
+**Facts to surface:** single points of fan-in, components with no callers, cross-boundary calls that bypass the module's public interface.
+
+## Micro — Functionality Trace
+
+**Collect:**
+
+1. Locate the entry symbol (`rg "symbolName"`); read it fully.
+2. Follow the call chain depth-first through the request's relevant path. Record each hop: `caller → callee (path:line)`.
+3. Mark at each hop: pure logic, state mutation, I/O side effect (network, disk, DB, clock, randomness).
+
+**Render:**
+
+Ordered call chain:
+
+```
+1. POST /refunds        routes/payments.ts:42
+2. refundInvoice()      services/refund.ts:17      [pure until step 4]
+3. validateAmount()     domain/money.ts:88         [pure]
+4. gateway.refund()     infra/stripe.ts:120        [I/O: network]
+5. ledger.record()      infra/ledger.ts:55         [I/O: DB write]
+6. bus.publish()        infra/events.ts:30         [I/O: queue]
+```
+
+Data flow list — what enters, how it transforms, what leaves:
+
+```
+RefundRequest{invoiceId, amount} → validated Amount → gateway response → LedgerEntry → InvoicePaid event
+```
+
+**Facts to surface:** where purity ends (first I/O hop), total hops, state mutated, error paths encountered (report; do not evaluate their quality).

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

@@ -1,4 +1,4 @@
-<!-- skill: create-issues, version: 1.2.0, status: verified -->
+<!-- skill: create-issues, version: 1.3.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,8 @@ 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 **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
      - TDD and Tidy First mandate
 
@@ -55,15 +57,20 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
    - Wire dependencies using actual captured identifiers or explicit body references.
    - Verify each creation step succeeded before continuing.
    - **After each successful creation**, extract the `**Files / Systems:**` bullet list from
-     the issue description and store it as structured metadata:
+     the issue description and store it as structured metadata together with a **base
+     commit anchor** for staleness detection:
      ```bash
-     bd update <id> --metadata '{"files": ["path/to/file1.py", "path/to/file2.py"]}'
+     base_sha=$(git rev-parse HEAD)
+     bd update <id> --metadata "{\"files\": [\"path/to/file1.py\", \"path/to/file2.py\"], \"base_commit\": \"$base_sha\"}"
      ```
-     This enables automated file-conflict detection by concurrent agents (see `renew` skill
-     **Claiming work** section). If the Files/Systems section is empty or contains only
-     subsystem names without concrete paths, **stop and ask the user for specific file paths
-     before publishing the ticket** — a ticket without concrete paths cannot participate in
-     conflict detection and is incomplete.
+     `base_commit` is HEAD at ticket-creation time. Reviewers and claiming agents diff
+     `base_commit..HEAD` against the ticket's `files` to detect out-of-date tickets (see
+     `issue-review` skill, Pass 0 PRE-003, and `renew` skill **Claiming work** section).
+     This enables automated file-conflict detection by concurrent agents. If the
+     Files/Systems section is empty or contains only subsystem names without concrete
+     paths, **stop and ask the user for specific file paths before publishing the ticket**
+     — a ticket without concrete paths cannot participate in conflict detection and is
+     incomplete.
 
 7. **Final report:**
    - Summarize the approved slice set, created issues, labels, and dependency links.
@@ -75,6 +82,9 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
 - **Traceable:** reference the exact plan/spec section or story.
 - **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.
+- **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.
 
 ## References

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

@@ -12,6 +12,10 @@ Use these criteria to evaluate whether a plan has been translated into strong tr
 | **Actionable Title** | Short, specific, and domain-oriented. Prefer behavior over component names. |
 | **Traceability** | Contains a direct reference to the source plan/spec section or story. |
 | **Verifiability** | Acceptance criteria are binary and observable. |
+| **Quantified Must gate** | Hard acceptance criterion carries a unit and number (Planguage Must), never an adjective. |
+| **Machine-checkable Meter** | An exact runnable command (Meter) whose exit code decides the gate; verifiable at the ticket's `base_commit`. |
+| **Anti-goals** | Negative constraints name prohibited behaviors (test edits, dependency additions, API breaks) so agents can't cheat the gate. |
+| **Baseline anchored** | Measurable claims record the pre-work value and the HEAD SHA as `base_commit` metadata for staleness detection. |
 | **Dependency hygiene** | Only real blockers are encoded; parallel work is not serialized without reason. |
 | **Workflow Mandate** | Includes the mandatory TDD and Tidy First block. |
 | **Execution mode** | Slice is explicitly marked AFK or HITL. |
@@ -23,6 +27,7 @@ Use these checks before publishing:
 - [ ] Does this issue deliver a narrow but complete path through relevant layers?
 - [ ] Could someone demo or verify this slice without waiting for a later ticket?
 - [ ] Is this a user-visible or system-verifiable outcome rather than plumbing-only work?
+- [ ] Could a fresh agent verify the Must gate by running the Meter command verbatim?
 - [ ] If the ticket is preparatory, is that preparatory work itself independently valuable?
 - [ ] Would splitting by backend/frontend/schema create worse horizontal tickets than the current slice?
 

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

@@ -31,6 +31,13 @@ Ref: [Link to plan/spec file and section]
 - `path/to/file2`
 - `[subsystem or surface area if exact files are not yet known]`
 
+## Verifiable Value Claim
+
+**Must (hard gate):** [Quantified threshold defining done, with unit and number — e.g. "P95 latency ≤ 250 ms at 100 req/sec"; never "fast" or "robust"]
+**Meter:** [Exact runnable command that verifies the Must gate — e.g. `pytest tests/val_claims/test_issue_NNN.py -q`; exit 0 = pass]
+**Baseline:** [Measured value before work starts — e.g. "P95 = 450 ms"; omit if not measurable]
+**Regression suite:** [Existing tests that must keep passing — e.g. `pytest tests/core/`]
+
 ## Acceptance Criteria
 
 - [ ] [Binary, observable criterion 1]
@@ -47,6 +54,11 @@ Or: `None - can start immediately`
 **CRITICAL: Follow Test Driven Development and Tidy First workflows.**
 - Write tests *before* writing implementation code.
 - Clean up related code *before* adding new functionality.
+
+**Anti-goals (do NOT):**
+- [Prohibited behavior with obvious reward-hacking payoff — e.g. "modify, disable, or delete tests in `tests/core/`"]
+- [e.g. "add new dependencies or modify lockfiles"]
+- [e.g. "break public API / exported interfaces"]
 ```
 
 ## Issue Creation Summary Template
@@ -65,6 +77,7 @@ Or: `None - can start immediately`
 - **Total Issues Created:** [count]
 - **Dependencies Defined:** [count]
 - **Labels Applied:** [e.g., needs-triage]
+- **Base Commit Anchored:** [git SHA recorded in `base_commit` metadata]
 
 ### Created Issues
 1. **[ID] [Title]** - [Link/Reference]

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
+- 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-0-preflight.md

@@ -34,4 +34,38 @@ Recommendation: consider a decomposition ticket to split `<file>` before these
 tickets run (see navari-a3cv pattern). If not decomposing now, add a
 co-modification note to all affected tickets.
 
+**Check 3 — stale base commit (freshness):**
+```bash
+bd list --format json | python3 -c "
+import json, subprocess, sys
+issues = json.load(sys.stdin)
+head = subprocess.run(['git','rev-parse','HEAD'], capture_output=True, text=True).stdout.strip()
+for i in issues:
+    meta = i.get('metadata') or {}
+    base = meta.get('base_commit')
+    if not base or base == head:
+        continue
+    files = meta.get('files') or []
+    changed = []
+    if files:
+        changed = subprocess.run(
+            ['git','diff','--name-only', f'{base}..HEAD', '--'] + files,
+            capture_output=True, text=True).stdout.split()
+    if changed:
+        print(i['id'], 'STALE-TOUCHED', changed)
+    else:
+        print(i['id'], 'BEHIND-HEAD')
+"
+```
+Flag `[PRE-003] HIGH` for STALE-TOUCHED: files in the ticket's scope changed since
+`base_commit` — the description, acceptance criteria, or Meter may no longer apply.
+Flag `[PRE-004] LOW` for BEHIND-HEAD: repo moved but ticket files untouched —
+likely still valid, only re-anchor.
+Fix: re-validate the ticket content against the current tree, then re-anchor:
+```bash
+sha=$(git rev-parse HEAD)
+bd update <id> --metadata "{\"base_commit\": \"$sha\"}"
+```
+Tickets missing `base_commit` entirely: flag as part of PRE-001 remediation.
+
 **Prefix:** PRE-001, PRE-002, etc.

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

@@ -3,6 +3,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 priorities and labels sensible?
 - Are HITL handoff points explicit?
 - Is it clear what demo, test, or observable behavior proves completion?
@@ -11,6 +12,10 @@ Watch for:
 - Hidden conversational context
 - "You know what to do"
 - Missing verification commands or test references
+- 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)
+- 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/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2026-07-31",
+  "version": "2026-09-01",
   "schema_version": "1.1",
   "prompts": [
     {
@@ -3756,6 +3756,139 @@
           }
         ]
       }
+    },
+    {
+      "name": "codebase-cartography",
+      "type": "task",
+      "title": "Codebase Cartography",
+      "description": "Navigate and understand a codebase by mapping its structure as text-based architecture diagrams at three zoom levels (macro/meso/micro), with optional structural-health triage using anti-pattern signatures",
+      "source": "content/prompt-task-codebase-cartography.md",
+      "distilled": "content/distilled/codebase-cartography/SKILL.md",
+      "skill_format": "progressive-disclosure",
+      "tags": [
+        "architecture",
+        "navigation",
+        "visualization",
+        "codebase",
+        "dependency-analysis",
+        "diagnostician"
+      ],
+      "bundles": [
+        "essentials"
+      ],
+      "eval": {
+        "task_types": [
+          "research",
+          "architecture",
+          "navigation"
+        ],
+        "success_signals": [
+          "entry_zoom_level_stated_explicitly",
+          "file_references_present_for_claims",
+          "dependency_directions_stated",
+          "maps_rendered_as_tables_or_mermaid",
+          "inference_labeled_as_inference",
+          "structural_observations_separated_from_advice"
+        ],
+        "failure_signals": [
+          "all_three_levels_dumped_without_request",
+          "refactor_advice_without_diagnostic_request",
+          "dependency_relations_without_direction",
+          "structure_assumed_without_search_evidence",
+          "findings_without_file_references"
+        ],
+        "stages": [
+          {
+            "name": "scope",
+            "hints": [
+              "target",
+              "zoom level",
+              "clarify",
+              "entry level"
+            ]
+          },
+          {
+            "name": "collect",
+            "hints": [
+              "references/zoom-levels.md",
+              "imports",
+              "entry points",
+              "search evidence"
+            ]
+          },
+          {
+            "name": "render",
+            "hints": [
+              "references/zoom-levels.md",
+              "matrix",
+              "mermaid",
+              "call chain",
+              "tables"
+            ]
+          },
+          {
+            "name": "health-check",
+            "hints": [
+              "references/smell-signatures.md",
+              "cycles",
+              "god object",
+              "fan-out",
+              "severity"
+            ]
+          },
+          {
+            "name": "report",
+            "hints": [
+              "references/report-template.md",
+              "key relationships",
+              "observations",
+              "open questions",
+              "html export"
+            ]
+          }
+        ],
+        "references": [
+          {
+            "id": "zoom-levels",
+            "path": "content/distilled/codebase-cartography/references/zoom-levels.md",
+            "purpose": "collection-and-rendering-guide",
+            "stage": "collect",
+            "optional": false,
+            "aliases": [
+              "references/zoom-levels.md",
+              "zoom-levels.md",
+              "zoom levels",
+              "levels"
+            ]
+          },
+          {
+            "id": "smell-signatures",
+            "path": "content/distilled/codebase-cartography/references/smell-signatures.md",
+            "purpose": "diagnostic-rubric",
+            "stage": "health-check",
+            "optional": true,
+            "aliases": [
+              "references/smell-signatures.md",
+              "smell-signatures.md",
+              "smells",
+              "health check"
+            ]
+          },
+          {
+            "id": "report-template",
+            "path": "content/distilled/codebase-cartography/references/report-template.md",
+            "purpose": "output-template",
+            "stage": "report",
+            "optional": false,
+            "aliases": [
+              "references/report-template.md",
+              "report-template.md",
+              "report template",
+              "html export"
+            ]
+          }
+        ]
+      }
     }
   ],
   "bundles": {

package/package.json

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

package/pi-package/prompts/codebase-cartography.md

@@ -0,0 +1,10 @@
+---
+description: "Shortcut for the codebase-cartography skill. Navigate and understand a codebase by mapping its structure as text-based architecture diagrams at three zoom levels (macro/meso/micro), with optional structural-health triage using anti-pattern signatures"
+---
+<!-- installed-from: incitaciones -->
+
+Use the installed `codebase-cartography` skill for this task.
+
+If the skill is not automatically loaded, invoke `/skill:codebase-cartography` and follow it.
+
+User context: $@

package/pi-package/skills/codebase-cartography/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: codebase-cartography
+description: "Navigate and understand a codebase by mapping its structure as text-based architecture diagrams at three zoom levels (macro/meso/micro), with optional structural-health triage using anti-pattern signatures"
+metadata:
+  installed-from: "incitaciones"
+---
+# Codebase Cartography
+
+Map a codebase's structure as text-based architecture diagrams at three zoom levels, with optional structural-health triage.
+
+You are a cartographer, not a critic: you document topology, dependencies, and boundaries as they exist. You do not recommend changes unless an explicit diagnostic pass was requested.
+
+## Zoom Levels
+
+- **macro** — whole-system topology: modules/domains, dependency direction, layering.
+- **meso** — one module or feature: internal components, wiring, integration contracts.
+- **micro** — one functionality: call chain, data flow, state mutation, I/O boundaries.
+
+Pick the entry level from the request:
+
+| Request shape | Entry level | Typical ask |
+| :---- | :---- | :---- |
+| "map this repo", onboarding | macro | lay of the land |
+| "how does <module> work", wiring | meso | structure of one district |
+| "trace <functionality>", "where does X happen" | micro | end-to-end path |
+
+## Procedure
+
+1. Clarify the target if ambiguous. State the entry zoom level explicitly in the output.
+2. Gather evidence by searching — imports, entry points, directory layout, call sites. Never infer structure from names alone.
+3. Render the entry-level map plus one adjacent level for context (parent overview when starting micro/meso; child detail when starting macro).
+4. Run the health check only if requested.
+5. Produce the report using the template.
+
+**Reference loading protocol — read on demand:**
+
+- 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`.
+
+## Zoom Discipline
+
+- Offer adjacent levels as follow-ups; never dump all three maps unrequested.
+- 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.
+- If the target is too large for one pass, map boundaries first and ask which module or area to enter.
+
+## Rules
+
+- Describe structure as it exists; no refactor advice outside an explicit diagnostic request.
+- Cycles, hotspots, and boundary violations are facts to report, not flaws to fix.
+- 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.

package/pi-package/skills/codebase-cartography/references/report-template.md

@@ -0,0 +1,75 @@
+# Report Template
+
+Structure the final output by mode. All modes share the closing sections. Keep maps as tables/Mermaid — diff-able artifacts.
+
+## Header (all modes)
+
+```
+## Cartography — <target>
+**Entry zoom level:** macro | meso | micro
+**Scope covered:** <paths examined>
+```
+
+## Mode: macro
+
+1. **Module inventory** — table (module, path, responsibility, 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
+
+## Mode: meso
+
+1. **Parent context** — 2-3 lines: where this module sits in the macro map
+2. **Component table** — components, paths, roles, internal links, external ports
+3. **Wiring graph** — Mermaid with mechanism-labeled edges
+4. Structural observations
+
+## Mode: micro
+
+1. **Entry point** — symbol and file:line
+2. **Call chain** — numbered hops with file:line and purity/I-O markers
+3. **Data flow** — transformation list from input to outputs/side effects
+4. Structural observations
+
+## Mode: health check (additive to any level)
+
+One finding block per pattern (format in `smell-signatures.md`), ordered by severity. If nothing found, state the patterns checked and the evidence gathered — absence of findings without evidence of search is not a result.
+
+## Closing sections (all modes)
+
+**Key Relationships** — top 3-5 dependencies that explain the structure:
+
+```
+- web → api (all requests funnel here; 34 call sites)
+- ledger ← webhooks (cycle with billing; see observations)
+```
+
+**Structural Observations** — facts only, no fixes:
+
+```
+- Cycle: billing → webhooks → ledger → billing (3 modules)
+- Hotspot: core/ledger.ts imported by 14 modules
+- Layer skip: web/cli imports infra/db directly (5 files)
+```
+
+**Open Questions** — what the cartographer could not resolve, for human follow-up:
+
+```
+- Is the billing → ledger edge intentional or legacy? (no test covers it)
+```
+
+**Adjacent levels offered** — one line each, e.g. "meso map of ledger available on request".
+
+## 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 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.
+
+- **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.
+- **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.
+
+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.

package/pi-package/skills/codebase-cartography/references/smell-signatures.md

@@ -0,0 +1,58 @@
+# Anti-Pattern Signatures — Agent-Computable Proxies
+
+Structural health check. Each anti-pattern from the visual framework is reduced to evidence an agent can gather by search and counting. Report findings; do not propose fixes unless explicitly asked.
+
+## Report Format (per finding)
+
+```
+[PATTERN] severity: high|medium|low
+Evidence: file:line list or matrix marks
+Quantity: loop members / fan-out count / depth / ratio
+```
+
+Severity scales with blast radius: fan-out count, number of affected modules, loop size.
+
+## Signature Catalog
+
+### Circular Dependencies
+
+- **Proxy:** closed loops in the module or component graph. Build the dependency list (see `zoom-levels.md` macro), then trace: if A → B → … → A exists, report the full loop.
+- **Quick scan:** mutual imports between two files (`rg` for A importing B, then B importing A); module-pair matrix marks both ways.
+- **Severity:** loop spanning multiple top-level modules > intra-module pair.
+
+### God Object
+
+- **Proxy:** one file/class with extreme fan-in AND fan-out, plus size. Check: file length (`wc -l`), count of exported methods/attributes, count of distinct importers (`rg -l "from .*<module>" | wc -l`), count of its own imports.
+- **Thresholds:** relative to the repo baseline — flag when a file is ~3× the median size AND importers are ~3× the median. State the baseline numbers used. In tiny repos (< ~10 files of the same kind), the median is meaningless — fall back to absolute judgment (e.g., one file dominating all coupling) and label the weak baseline.
+- **Severity:** grows with importer count (every change touches all of them).
+
+### Shotgun Surgery
+
+- **Proxy:** one concept scattered across many modules. Pick a domain concept from the target question (e.g., "invoice", "permissions") and count modules containing references to it: `rg -l "<concept>" | cut -d/ -f1-2 | sort -u | wc -l`.
+- **Severity:** grows with module count and with coupling between the scattered sites (do they import each other or duplicate?).
+
+### Feature Envy
+
+- **Proxy:** a module imports another module far more than its own internals. Count both sides and compare — imports of the foreign module: `rg -c "from .*<moduleX>" moduleA/`; imports resolving inside moduleA (relative `./` imports): `rg -c "from '\./" moduleA/`. Flag when the foreign count exceeds the local count by ~2× or more.
+- **Severity:** medium when it is one direction; high when the envying module is otherwise nearly disconnected from its own parent.
+
+### Deep Inheritance
+
+- **Proxy:** chains of `extends`/subclassing beyond ~3 levels: `rg "extends "` then follow each chain. Report max depth and the chain.
+- **Severity:** medium; flag deepest chain only, not every chain.
+
+### Pure/Impure Entanglement (functional codebases)
+
+- **Proxy:** business-logic functions directly performing I/O (network, DB, filesystem, clock, randomness) instead of receiving results as parameters. Verify by reading the call chain at micro level: mark the first impure hop and whether logic continues after it.
+- **Severity:** high when the same file mixes domain rules and I/O calls repeatedly (report count).
+
+### Broken Composition (layer-skipping)
+
+- **Proxy:** dependencies that bypass an architectural interface layer — e.g., web module importing infra directly instead of going through the api/service layer. Visible as ↑ marks in the macro matrix (a dependency pointing against the repo's declared or evident layering).
+- **Severity:** scales with how many files take the shortcut.
+
+## Interpretation Rules
+
+- One finding per pattern per target; list all instances under Evidence.
+- If the pattern is suspected but evidence is thin, say "suspected, evidence: <what's missing>" instead of asserting.
+- Findings are facts about structure. The user decides what to do with them.

package/pi-package/skills/codebase-cartography/references/zoom-levels.md

@@ -0,0 +1,99 @@
+# Zoom Levels — Evidence Collection & Rendering
+
+Per-level collection strategy and text rendering formats. Match the rendering to what the level must show; the paradigm-scale principle applies: module-level relations read best as matrices/graphs, functionality reads best as ordered chains.
+
+## Macro — System Topology
+
+**Collect:**
+
+Adapt import syntax to the language (see language rule below).
+
+0. **Language rule:** use the repo's import syntax for scans. JS/TS: `from './x'`; Python: `import x` / `from x import`; Rust: `use x::`; Go: `go list -deps`; Java: `import x.y;`. If the repo is multi-language, run the scan per language.
+1. Top-level directory layout (`ls`, tree to depth 1–2). Identify likely module boundaries (packages, workspaces, domains). Exclude vendored/generated code (`node_modules`, `dist`, `target`, `vendor`, generated committed sources) from all counts — `rg` respects `.gitignore` by default, but generated-but-committed code must be excluded with explicit globs (`-g '!dist'`).
+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.
+
+**Render:**
+
+Module inventory table:
+
+| Module | Path | Responsibility (one line, from evidence) | Deps out → | Fan-in |
+| :---- | :---- | :---- | :---- | :---- |
+
+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:
+
+|  | core | api | web | jobs |
+| :---- | :---- | :---- | :---- | :---- |
+| core | — |  |  |  |
+| api | ✦ | — |  |  |
+| web | ✦ | ✦ | — |  |
+| jobs | ✦ |  | ↑ | — |
+
+Module graph (Mermaid), one node per module, edges labeled with edge counts:
+
+```mermaid
+graph TD
+  web --> api
+  api --> core
+  jobs --> core
+```
+
+**Facts to surface:** layering violations (↑ marks), cycles, hub modules (highest fan-in/out), orphan modules (zero fan-in).
+
+## Meso — Module / Feature Wiring
+
+**Collect:**
+
+1. Entry points of the module: exported symbols, route registrations, message handlers, CLI commands.
+2. Internal components: classes/functions by responsibility; group by subdirectory.
+3. Integration contracts: interfaces implemented, events published/consumed, external clients (HTTP, DB, queues).
+4. Which other modules call in, and which the module calls out to.
+
+**Render:**
+
+Component table:
+
+| Component | Path | Role | Talks to (internal) | External ports |
+| :---- | :---- | :---- | :---- | :---- |
+
+Wiring graph (Mermaid). Show direction and label edges with the mechanism (calls, publishes, reads):
+
+```mermaid
+graph LR
+  routes --> service
+  service --> repo
+  service -- "publishes InvoicePaid" --> bus
+  repo -- SQL --> [(db)]
+```
+
+**Facts to surface:** single points of fan-in, components with no callers, cross-boundary calls that bypass the module's public interface.
+
+## Micro — Functionality Trace
+
+**Collect:**
+
+1. Locate the entry symbol (`rg "symbolName"`); read it fully.
+2. Follow the call chain depth-first through the request's relevant path. Record each hop: `caller → callee (path:line)`.
+3. Mark at each hop: pure logic, state mutation, I/O side effect (network, disk, DB, clock, randomness).
+
+**Render:**
+
+Ordered call chain:
+
+```
+1. POST /refunds        routes/payments.ts:42
+2. refundInvoice()      services/refund.ts:17      [pure until step 4]
+3. validateAmount()     domain/money.ts:88         [pure]
+4. gateway.refund()     infra/stripe.ts:120        [I/O: network]
+5. ledger.record()      infra/ledger.ts:55         [I/O: DB write]
+6. bus.publish()        infra/events.ts:30         [I/O: queue]
+```
+
+Data flow list — what enters, how it transforms, what leaves:
+
+```
+RefundRequest{invoiceId, amount} → validated Amount → gateway response → LedgerEntry → InvoicePaid event
+```
+
+**Facts to surface:** where purity ends (first I/O hop), total hops, state mutated, error paths encountered (report; do not evaluate their quality).

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.2.0, status: verified -->
+<!-- skill: create-issues, version: 1.3.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,8 @@ 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 **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
      - TDD and Tidy First mandate
 
@@ -61,15 +63,20 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
    - Wire dependencies using actual captured identifiers or explicit body references.
    - Verify each creation step succeeded before continuing.
    - **After each successful creation**, extract the `**Files / Systems:**` bullet list from
-     the issue description and store it as structured metadata:
+     the issue description and store it as structured metadata together with a **base
+     commit anchor** for staleness detection:
      ```bash
-     bd update <id> --metadata '{"files": ["path/to/file1.py", "path/to/file2.py"]}'
+     base_sha=$(git rev-parse HEAD)
+     bd update <id> --metadata "{\"files\": [\"path/to/file1.py\", \"path/to/file2.py\"], \"base_commit\": \"$base_sha\"}"
      ```
-     This enables automated file-conflict detection by concurrent agents (see `renew` skill
-     **Claiming work** section). If the Files/Systems section is empty or contains only
-     subsystem names without concrete paths, **stop and ask the user for specific file paths
-     before publishing the ticket** — a ticket without concrete paths cannot participate in
-     conflict detection and is incomplete.
+     `base_commit` is HEAD at ticket-creation time. Reviewers and claiming agents diff
+     `base_commit..HEAD` against the ticket's `files` to detect out-of-date tickets (see
+     `issue-review` skill, Pass 0 PRE-003, and `renew` skill **Claiming work** section).
+     This enables automated file-conflict detection by concurrent agents. If the
+     Files/Systems section is empty or contains only subsystem names without concrete
+     paths, **stop and ask the user for specific file paths before publishing the ticket**
+     — a ticket without concrete paths cannot participate in conflict detection and is
+     incomplete.
 
 7. **Final report:**
    - Summarize the approved slice set, created issues, labels, and dependency links.
@@ -81,6 +88,9 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
 - **Traceable:** reference the exact plan/spec section or story.
 - **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.
+- **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.
 
 ## References

package/pi-package/skills/create-issues/references/criteria.md

@@ -12,6 +12,10 @@ Use these criteria to evaluate whether a plan has been translated into strong tr
 | **Actionable Title** | Short, specific, and domain-oriented. Prefer behavior over component names. |
 | **Traceability** | Contains a direct reference to the source plan/spec section or story. |
 | **Verifiability** | Acceptance criteria are binary and observable. |
+| **Quantified Must gate** | Hard acceptance criterion carries a unit and number (Planguage Must), never an adjective. |
+| **Machine-checkable Meter** | An exact runnable command (Meter) whose exit code decides the gate; verifiable at the ticket's `base_commit`. |
+| **Anti-goals** | Negative constraints name prohibited behaviors (test edits, dependency additions, API breaks) so agents can't cheat the gate. |
+| **Baseline anchored** | Measurable claims record the pre-work value and the HEAD SHA as `base_commit` metadata for staleness detection. |
 | **Dependency hygiene** | Only real blockers are encoded; parallel work is not serialized without reason. |
 | **Workflow Mandate** | Includes the mandatory TDD and Tidy First block. |
 | **Execution mode** | Slice is explicitly marked AFK or HITL. |
@@ -23,6 +27,7 @@ Use these checks before publishing:
 - [ ] Does this issue deliver a narrow but complete path through relevant layers?
 - [ ] Could someone demo or verify this slice without waiting for a later ticket?
 - [ ] Is this a user-visible or system-verifiable outcome rather than plumbing-only work?
+- [ ] Could a fresh agent verify the Must gate by running the Meter command verbatim?
 - [ ] If the ticket is preparatory, is that preparatory work itself independently valuable?
 - [ ] Would splitting by backend/frontend/schema create worse horizontal tickets than the current slice?
 

package/pi-package/skills/create-issues/references/templates.md

@@ -31,6 +31,13 @@ Ref: [Link to plan/spec file and section]
 - `path/to/file2`
 - `[subsystem or surface area if exact files are not yet known]`
 
+## Verifiable Value Claim
+
+**Must (hard gate):** [Quantified threshold defining done, with unit and number — e.g. "P95 latency ≤ 250 ms at 100 req/sec"; never "fast" or "robust"]
+**Meter:** [Exact runnable command that verifies the Must gate — e.g. `pytest tests/val_claims/test_issue_NNN.py -q`; exit 0 = pass]
+**Baseline:** [Measured value before work starts — e.g. "P95 = 450 ms"; omit if not measurable]
+**Regression suite:** [Existing tests that must keep passing — e.g. `pytest tests/core/`]
+
 ## Acceptance Criteria
 
 - [ ] [Binary, observable criterion 1]
@@ -47,6 +54,11 @@ Or: `None - can start immediately`
 **CRITICAL: Follow Test Driven Development and Tidy First workflows.**
 - Write tests *before* writing implementation code.
 - Clean up related code *before* adding new functionality.
+
+**Anti-goals (do NOT):**
+- [Prohibited behavior with obvious reward-hacking payoff — e.g. "modify, disable, or delete tests in `tests/core/`"]
+- [e.g. "add new dependencies or modify lockfiles"]
+- [e.g. "break public API / exported interfaces"]
 ```
 
 ## Issue Creation Summary Template
@@ -65,6 +77,7 @@ Or: `None - can start immediately`
 - **Total Issues Created:** [count]
 - **Dependencies Defined:** [count]
 - **Labels Applied:** [e.g., needs-triage]
+- **Base Commit Anchored:** [git SHA recorded in `base_commit` metadata]
 
 ### Created Issues
 1. **[ID] [Title]** - [Link/Reference]

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
+- 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-0-preflight.md

@@ -34,4 +34,38 @@ Recommendation: consider a decomposition ticket to split `<file>` before these
 tickets run (see navari-a3cv pattern). If not decomposing now, add a
 co-modification note to all affected tickets.
 
+**Check 3 — stale base commit (freshness):**
+```bash
+bd list --format json | python3 -c "
+import json, subprocess, sys
+issues = json.load(sys.stdin)
+head = subprocess.run(['git','rev-parse','HEAD'], capture_output=True, text=True).stdout.strip()
+for i in issues:
+    meta = i.get('metadata') or {}
+    base = meta.get('base_commit')
+    if not base or base == head:
+        continue
+    files = meta.get('files') or []
+    changed = []
+    if files:
+        changed = subprocess.run(
+            ['git','diff','--name-only', f'{base}..HEAD', '--'] + files,
+            capture_output=True, text=True).stdout.split()
+    if changed:
+        print(i['id'], 'STALE-TOUCHED', changed)
+    else:
+        print(i['id'], 'BEHIND-HEAD')
+"
+```
+Flag `[PRE-003] HIGH` for STALE-TOUCHED: files in the ticket's scope changed since
+`base_commit` — the description, acceptance criteria, or Meter may no longer apply.
+Flag `[PRE-004] LOW` for BEHIND-HEAD: repo moved but ticket files untouched —
+likely still valid, only re-anchor.
+Fix: re-validate the ticket content against the current tree, then re-anchor:
+```bash
+sha=$(git rev-parse HEAD)
+bd update <id> --metadata "{\"base_commit\": \"$sha\"}"
+```
+Tickets missing `base_commit` entirely: flag as part of PRE-001 remediation.
+
 **Prefix:** PRE-001, PRE-002, etc.

package/pi-package/skills/issue-review/references/pass-5-executability.md

@@ -3,6 +3,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 priorities and labels sensible?
 - Are HITL handoff points explicit?
 - Is it clear what demo, test, or observable behavior proves completion?
@@ -11,6 +12,10 @@ Watch for:
 - Hidden conversational context
 - "You know what to do"
 - Missing verification commands or test references
+- 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)
+- 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