incitaciones 0.3.2 → 0.5.0

package/pi-package/skills/agent-value-alignment/references/layer-2-governance.md

@@ -0,0 +1,74 @@
+# Layer 2 — Governance: Specifying Authorized Behavior
+
+**Question:** What behavior is authorized, prohibited, and escalated — and who reviews it?
+
+## Why agent governance is different
+
+In traditional software, behavior = code; correct code ⇒ correct behavior. In agent systems, behavior emerges from code × model × prompts × tools × execution context — none fully specifiable in advance. Traditional governance (code review, automated tests, deploy gates) is necessary but insufficient. You need mechanisms that detect behavioral drift *even when the code is correct*.
+
+## Core artifacts
+
+| Artifact | Purpose |
+|---|---|
+| **Behavioral Specification Document (BSD)** | Authoritative reference for *how* the agent should behave; source of truth for prompts, evals, audits. Covers: purpose, authorized behaviors, prohibited behaviors, escalation criteria, behavioral principles, success metrics, known limitations/edge cases. |
+| **Agent Charter** | One-page "constitution" readable by non-technical stakeholders: purpose, scope, principles, prohibitions, escalation, success/failure criteria, governance. |
+| **Kill Criteria Document** | Pre-committed stopping conditions, signed before development (see Layer 1). |
+| **Behavioral ADRs (BADRs)** | Record of intent for significant behavioral decisions — context, decision, options, rationale, consequences, implementation. Distinguishes bug from feature when behavior is questioned. |
+| **Falsifiable Value Proposition** | Propagates verbatim into BSD §1, system prompt, and review agenda (see Integration). |
+| **Pre-mortem** | Imagine failure in advance; generate mitigations with owners. |
+
+## The "scope creep by proxy" anti-pattern
+
+The signature governance failure for agents: capabilities expand through accumulation of *individually reasonable* changes — tool proliferation, edge-case capability expansion, behavioral drift from model updates, prompt accumulation. Each change is justified by a use case; the cumulative expansion was never approved. Hard to detect in real time.
+
+**Countermeasure:** explicit scope gates at defined milestones — behavioral scope, tool access, data access, output scope reviews — with deviations either formally approved (via BADR) or rolled back.
+
+## Review ceremonies (augment traditional sprints)
+
+- **Behavioral regression testing** at each sprint boundary — checks alignment, not just functional correctness.
+- **Red-team reviews** at regular intervals — attempt to induce goal drift, specification gaming, scope violations.
+- **Alignment reviews** by team members *not* in the recent sprint — external perspective catches gradual drift invisible to builders.
+- **Incident post-mortems** that classify incidents as goal drift / specification gaming / scope violation, with prevention recommendations. Treat agent behavior incidents with the rigor of security incidents.
+
+## Open-source / distributed governance
+
+Contributors carry different understandings of the objective; PR review is poorly suited to evaluating behavioral alignment. Best practices: versioned behavioral specs, behavioral contribution guidelines, behavioral CI/CD on every PR, designated *alignment maintainers* distinct from technical maintainers.
+
+## Multi-agent systems
+
+If the target is a multi-agent system (orchestrator/worker hierarchies), the
+single-agent checklists are necessary but not sufficient — drift can occur at
+four levels invisible to per-agent review: **orchestrator drift** (task
+decomposition diverges from the objective), **worker drift** (a worker
+diverges from its sub-task), **coordination drift** (orchestrator–worker
+interaction diverges), and **emergent drift** (collective behavior diverges
+in ways not visible at the individual level).
+
+**Additional AUDIT checks for multi-agent targets:**
+- [ ] Every worker sub-task has an explicit, verifiable specification (not a
+      high-level instruction) and a defined success criterion.
+- [ ] The orchestrator verifies worker results against the sub-task spec before
+      incorporating them.
+- [ ] Cross-agent consistency checks exist (outputs of different workers are
+      consistent with each other and the overall objective).
+- [ ] HITL review is configured at both orchestrator (task decomposition) and
+      worker (sub-task execution) levels.
+
+See the synthesis §5.6 for the orchestrator/worker alignment patterns and the
+multi-agent alignment prompts.
+
+## AUDIT checks
+
+- [ ] BSD exists and is version-controlled with the same rigor as code.
+- [ ] Agent Charter exists (≤1 page, readable by non-technical stakeholders).
+- [ ] Prohibited behaviors are explicit (negation), not implicit.
+- [ ] Escalation triggers are specific (not "when uncertain" but the 7 named triggers — see Layer 3).
+- [ ] Scope gates exist at milestones; deviations require BADR.
+- [ ] Behavioral regression tests run at sprint boundaries.
+- [ ] Red-team reviews occur on a cadence.
+- [ ] *(Multi-agent only)* Sub-task specs, result verification, and cross-agent
+      consistency checks exist (see Multi-agent systems above).
+
+## ESTABLISH (Day 2)
+
+- Day 2 (1h): Write the Agent Charter (≤1 page). Draft the BSD (can be expanded later, but purpose/scope/prohibitions/escalation must exist from day one).

package/pi-package/skills/agent-value-alignment/references/layer-3-runtime-prompt.md

@@ -0,0 +1,68 @@
+# Layer 3 — Runtime Prompt: Enforcing Alignment at Execution Time
+
+**Question:** Do the runtime instructions actually anchor behavior to the objective — and are they verified?
+
+## The foundational constraint: lost in the middle
+
+LLM performance follows a **U-shaped curve**: models attend well to the beginning (primacy) and end (recency) of context and systematically underweight the middle (Liu et al., 2023; TACL 2024). Context length *alone* degrades performance 13.9–85% even with perfect retrieval (Du et al., 2025). An objective stated once at the top of a long system prompt, after tool results accumulate, is buried in the middle and statistically underweighted. This is structural, not an intelligence failure.
+
+## Goal-anchoring patterns
+
+| Pattern | Mechanism | Addresses |
+|---|---|---|
+| **Goal Sandwich** | Primary objective verbatim at top *and* bottom of system prompt | U-shaped attention |
+| **Objective Echo** | Agent restates objective before each major action | Active retrieval vs. passive presence |
+| **Scope Fence** | Explicit negation of prohibited actions | Implicit-scope unreliability |
+| **Minimal Footprint Clause** | Resource/side-effect constraints | Instrumental convergence pressure |
+| **Constitutional self-critique** | Critique-then-revise against stated principles (Bai et al., 2022) | Goal alignment at output time |
+| **Persistent objective store** | Objective retrieved from outside the context window | Compression/summarization drift |
+
+**Instruction hierarchy:** primary objective in first and last 5 lines; scope fence + minimal footprint early; operational detail in the (lower-attention) middle; constitutional critique principles near the end. Any constraint that must be reliably followed appears in the first or last 20% of the prompt.
+
+**Critical failure mode:** placing safety/scope constraints only in the middle of a long prompt.
+
+## Drift detection and self-check loops
+
+- **ReAct + alignment verification** — extend Thought → Action → Observation with OBJECTIVE/PROGRESS/ALIGNMENT/SCOPE checks before each action. (ReAct outperformed pure CoT by 34% on ALFWorld.) *Failure mode:* context accumulation; mitigate with observation compaction, step limits, periodic goal re-injection.
+- **OODA self-correction** — Observe/Orient/Decide/Act as a continuous self-monitoring loop after each major action.
+- **Uncertainty/escalation prompts** — structured decision rules forcing stop-and-ask on: ambiguity, scope uncertainty, irreversibility, unexpected state, conflicting instructions, high stakes, confidence below threshold. Implements Anthropic's Minimal Footprint Principle.
+
+## Eval design — the most important shift
+
+From **output correctness** ("is the answer right?") to **outcome achievement** ("did this help the user accomplish their goal?"). A value-focused eval scores 0–4 (DID NOT HELP → FULLY ENABLED) and requires a gap analysis: what would reach Level 4?
+
+**Judges:**
+- **LLM-as-judge** (Zheng et al., 2023) — ~80% agreement with humans, matching human-human. *Mandatory mitigations:* evaluate pairwise in both orders (position bias); instruct against verbosity bias; **never use the same model as both agent and judge** (self-enhancement bias up to 25%).
+- **G-Eval** (Liu et al., 2023) — chain-of-thought form-filling; generates evaluation steps before scoring.
+
+**Behavioral regression tests** detect when a model/prompt/context change breaks previously-passing behavior. Require a golden dataset with ≥30% "failure class" examples (inputs that should trigger escalation/refusal/scope denial) — happy-path-only suites cannot detect regression in failure handling.
+
+## Meta-prompting for goal fidelity
+
+- **Reflexion** (Shinn et al., 2023) — verbal self-reflection in an episodic buffer, prepended to retries; 91% pass@1 on HumanEval vs. GPT-4's prior 80%.
+- **Self-consistency** (Wang et al., 2023) — sample multiple reasoning paths, select the most goal-aligned; +17.9% on GSM8K.
+- **Checkpoint output prompts** — force the agent to emit current goal/state/confidence before each major action (auditable record).
+- **Meta-alignment prompts** — agent generates its own task-specific checklist before beginning.
+
+## The alignment trade-off
+
+- **RLHF / Constitutional AI** — embeds constraints in weights; robust to drift/injection; expensive, can be gamed if reward model is imperfect.
+- **Prompt-based** — flexible, interpretable; subject to drift, overridable.
+
+Production uses both: RLHF/CAI for foundational constraints, prompt-based for task-specific scope. The Claude model specification (principal hierarchy: Anthropic → operators → users → agent; Minimal Footprint, corrigibility, consistency) is the current state of the art.
+
+## AUDIT checks
+
+- [ ] Objective appears verbatim at top *and* bottom (Goal Sandwich); identical wording.
+- [ ] Prohibited actions are explicit negations, not implicit.
+- [ ] Minimal Footprint clause present.
+- [ ] Escalation triggers are the 7 named types, not "when uncertain."
+- [ ] Eval suite measures outcome achievement, not just output correctness.
+- [ ] Golden dataset includes ≥30% failure-class examples.
+- [ ] LLM-as-judge uses a *different* model than the evaluated agent.
+- [ ] Behavioral regression tests run on every prompt/model change.
+
+## ESTABLISH (Day 3–4)
+
+- Day 3 (2h): Implement Goal Sandwich + Scope Fence (≥5 prohibited) + Minimal Footprint + Escalation Triggers. This is the minimum viable goal-anchoring prompt.
+- Day 4 (3h): Write 10 eval cases — 5 happy-path, 3 scope-boundary, 2 drift. Run manually; fix failures before deploy.

package/pi-package/skills/agent-value-alignment/references/layer-4-infrastructure.md

@@ -0,0 +1,58 @@
+# Layer 4 — Infrastructure: State, Memory, and Observability
+
+**Question:** How is state preserved, memory managed, and drift observed in production?
+
+## Checkpointing: fault tolerance vs. alignment
+
+- **Fault-tolerant checkpointing** asks: "can we resume after a crash?"
+- **Alignment-oriented checkpointing** asks: "is the agent still pursuing the right goal, and can we roll back to a known-good state if it has drifted?"
+
+The latter requires **goal-state verification at each checkpoint**, not just state persistence.
+
+**LangGraph** (1.0 GA, Oct 2025) is the most mature production option: checkpoints at every super-step, pluggable backends (`PostgresSaver` for production), first-class `interrupt()` API for HITL resumable via `Command(resume=...)`, time-travel debugging, state mutation. Powers agents at ~400 companies (LinkedIn, Uber, Replit) with 8% latency overhead. **MemGPT/Letta** provides OS-inspired tiered memory (main context / recall DB / archival vector store) with LLM-managed tier movement.
+
+Caveat: OpenAI Agents SDK and AutoGen lack native durable execution — teams must add Temporal/DBOS. Google ADK loses in-memory session state on Cloud Run restarts. Configure persistent storage from day one; retrofitting is significantly harder.
+
+## Memory architecture as a first-class concern
+
+"Memory deserves the same level of engineering investment as the LLM itself" (Du, 2026). Three dimensions:
+
+- **Temporal scope** — working (subject to lost-in-the-middle), episodic (concrete experience records), semantic (abstracted knowledge; over-generalization risk), procedural (reusable skills; Voyager without its skill library showed 15.3× slower progression).
+- **Representational substrate** — context-resident text (compression drift), vector stores, structured stores, executable repositories.
+- **Control policy** — heuristic, prompted self-control (MemGPT; silent orchestration failure risk), learned/RL (e.g., AgeMem, per Du 2026; most capable, requires training infra).
+
+Empirical stakes: Generative Agents without reflection degenerated to repetitive responses within 48 simulated hours; on MemoryArena (2026), active memory agents achieved 80%+ task completion vs. ~45% for long-context-only baselines. Models near-saturating LoCoMo plummet to 40–60% on MemoryArena — a deep gap between passive recall and active, decision-relevant memory.
+
+## Safe stopping, rollback, and HITL
+
+Safe stopping criteria (distinct from error conditions): uncertainty threshold, scope boundary, resource limit, anomaly detection, human review trigger. LangGraph's `interrupt()` provides the mechanism; the *design* challenge is choosing when to pause, what to surface, and how to incorporate feedback: approve / modify / rollback-and-retry / abort.
+
+**Cost calculus favors false positives:** unnecessary human reviews are far cheaper than undetected goal drift leading to irreversible actions. Configure HITL at all irreversible action boundaries.
+
+## Observability for drift detection
+
+**Quantitative signals:** task completion rate, goal retention score, scope violation rate, rollback rate, HITL trigger rate, token efficiency (useful work / total tokens — flags unproductive spinning).
+
+**Qualitative signals:** execution traces, reasoning traces, state snapshots, anomaly detection.
+
+**Decay detection dashboard** tiers these into:
+- Behavioral health (weekly) — eval pass rate, goal achievement, scope violations, escalations, errors.
+- Adoption health (weekly) — WAU, tasks/user, retention, satisfaction.
+- Value health (monthly) — primary value metric, cost/task, cost/user.
+
+**Automatic review triggers:** eval pass rate drops >10% week-over-week; any red metric persists 2+ weeks; model or prompt change deployed (re-run full eval suite).
+
+## AUDIT checks
+
+- [ ] Checkpointing is alignment-oriented (goal-state verification, not just resume).
+- [ ] Persistent backend configured from day one (not in-memory in production).
+- [ ] Memory architecture is a deliberate choice across all three dimensions, not an afterthought.
+- [ ] HITL interrupts configured at all irreversible action boundaries.
+- [ ] Tracing/observability deployed before production (LangSmith or equivalent).
+- [ ] Decay detection dashboard exists with the three tiers and automatic triggers.
+- [ ] Full eval suite re-runs on every model/prompt change.
+
+## ESTABLISH (Day 5)
+
+- Day 5a (30 min): Schedule the first Value Realization Review for 90 days out.
+- Day 5b (30 min – ½ day): Stand up the decay detection dashboard. *30 min only if metrics are already instrumented; up to half a day if instrumentation must be built.* Do not skip — without it, drift cannot be detected before lagging outcome metrics confirm it.

package/pi-package/skills/agent-value-alignment/references/report-template.md

@@ -0,0 +1,113 @@
+# Agent Value Alignment — Report Template
+
+Use this for both AUDIT and ESTABLISH modes. Replace `[ ]` placeholders.
+
+## Severity rubric
+
+Apply consistently to every finding so two auditors rate the same gap alike:
+
+| Severity | Definition |
+|---|---|
+| **CRITICAL** | Breaks the governing invariant (an unenforced decision / unverified clause / unacted eval result) **or** leaves an irreversible-action boundary unguarded (no HITL, no rollback) |
+| **HIGH** | A Layer-1 or Layer-2 artifact is missing, unfalsifiable, or unsigned (e.g., no kill criteria, no BSD, vague VP) — the loop cannot close without it |
+| **MEDIUM** | An AUDIT check fails but a compensating control exists (e.g., eval suite present but golden dataset lacks failure-class examples) |
+| **LOW** | Cadence or documentation gap (e.g., Value Realization Review not yet scheduled, dashboard not yet live) |
+
+A layer is 🔴 if it has ≥1 CRITICAL finding; 🟡 if it has ≥1 HIGH/MEDIUM but no CRITICAL; 🟢 if all AUDIT checks pass.
+
+---
+
+## Agent Value Alignment Report
+
+**Target:** [agent/tool name and version]
+**Mode:** [AUDIT | ESTABLISH]
+**Date:** [YYYY-MM-DD]
+**Reviewer:** [name/role]
+**Sources consulted:** [system prompt, BSD, eval suite, dashboard, etc.]
+
+---
+
+### Executive Summary
+
+[2–4 sentences. State the single most important finding: is the closed loop intact, and if not, where is it broken?]
+
+**Overall verdict:** [ALIGNED | PARTIAL | NOT_ALIGNED]
+
+### Layer Scores
+
+| Layer | Status | Critical gaps |
+|---|---|---|
+| 1 — Value | [🟢/🟡/🔴] | [count] |
+| 2 — Governance | [🟢/🟡/🔴] | [count] |
+| 3 — Runtime Prompt | [🟢/🟡/🔴] | [count] |
+| 4 — Infrastructure | [🟢/🟡/🔴] | [count] |
+| Integration | [🟢/🟡/🔴] | [count] |
+
+Status: 🟢 all AUDIT checks pass · 🟡 ≥1 check fails, no critical · 🔴 ≥1 critical gap.
+
+---
+
+### Findings
+
+#### [LAYER-N-FINDING-001] [CRITICAL|HIGH|MEDIUM|LOW] — [Location]
+- **Layer:** [1 Value | 2 Governance | 3 Runtime | 4 Infra | Integration]
+- **What's wrong:** [specific gap, citing the artifact and location]
+- **Why it matters:** [which root cause or failure mode this enables]
+- **Recommendation:** [specific action — which artifact to create/change, by whom]
+- **Invariant violated:** [enforcement | verification | action] (if applicable)
+
+[repeat for each finding]
+
+---
+
+### Invariant Check
+
+The governing invariant: *every governance decision → prompt clause → eval test → governance review*.
+
+- Decisions with no prompt clause (not enforced): [list, or "none"]
+- Prompt clauses with no eval test (not verified): [list, or "none"]
+- Eval results not reviewed in governance (not acted upon): [list, or "none"]
+
+---
+
+### Value Proposition (as currently stated)
+
+> "[verbatim current VP, or 'NOT DEFINED']"
+
+**Falsifiable?** [Yes/No — which slot is missing]
+**Propagated verbatim across prompt + BSD + review agenda?** [Yes/No]
+
+---
+
+### Kill Criteria Status
+
+[Cite each criterion, its threshold, the current value, and status: on-track / at-risk / triggered. Or "NOT DEFINED".]
+
+---
+
+### Recommended Actions (priority order)
+
+1. [Action] — Owner: [role] — Layer: [N] — Due: [date]
+2. [Action] — Owner: [role] — Layer: [N] — Due: [date]
+3. [Action] — Owner: [role] — Layer: [N] — Due: [date]
+
+### Next Review
+
+**Value Realization Review scheduled:** [date, or "NOT SCHEDULED — schedule within 90 days"]
+**Decay dashboard live:** [Yes/No]
+
+---
+
+### For ESTABLISH mode only: Minimum Viable Artifact Set
+
+| Artifact | Status | Location |
+|---|---|---|
+| Falsifiable Value Proposition | [Done/In progress/Not started] | [path] |
+| Kill Criteria (signed) | | |
+| Agent Charter | | |
+| Goal Sandwich system prompt | | |
+| 10 eval test cases | | |
+| Value Realization Review scheduled | | |
+| Decay detection dashboard | | |
+
+*Do not consider the loop closed until every artifact above is "Done" AND the invariant check shows zero unenforced/unverified/unacted items.*

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

@@ -0,0 +1,55 @@
+---
+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.
+
+## 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.

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

@@ -0,0 +1,61 @@
+# 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".

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