incitaciones 0.3.2 → 0.5.0

package/content/manifest.json

@@ -1,7 +1,212 @@
 {
-  "version": "2026-07-29",
+  "version": "2026-09-01",
   "schema_version": "1.1",
   "prompts": [
+    {
+      "name": "agent-value-alignment",
+      "type": "task",
+      "title": "Agent Value Alignment",
+      "description": "Audit or establish the closed loop that anchors an AI agent's behavior to its intended value across four layers — Value, Governance, Runtime Prompt, Infrastructure — bound by a shared vocabulary and traceability matrix; detects goal drift and value drift before lagging metrics confirm them",
+      "source": "content/prompt-task-agent-value-alignment.md",
+      "distilled": "content/distilled/agent-value-alignment/SKILL.md",
+      "skill_format": "progressive-disclosure",
+      "tags": [
+        "agents",
+        "alignment",
+        "value-delivery",
+        "prompt-engineering",
+        "governance",
+        "goal-drift",
+        "diagnostician",
+        "review"
+      ],
+      "bundles": [
+        "reviews"
+      ],
+      "eval": {
+        "task_types": [
+          "review",
+          "alignment",
+          "agents",
+          "governance"
+        ],
+        "success_signals": [
+          "falsifiable_value_proposition_present",
+          "kill_criteria_signed_with_owner",
+          "goal_sandwich_pattern_verified",
+          "value_focused_eval_suite_present",
+          "traceability_matrix_complete",
+          "integration_invariant_checked",
+          "layer_specific_gaps_cited_with_locations",
+          "final_verdict_present"
+        ],
+        "failure_signals": [
+          "unfalsifiable_value_proposition_accepted",
+          "output_correctness_eval_mistaken_for_value_eval",
+          "unsigned_kill_criteria_accepted",
+          "governance_decision_without_prompt_clause_not_flagged",
+          "prompt_clause_without_eval_test_not_flagged",
+          "drift_assumed_absent_without_evidence",
+          "findings_without_specific_locations",
+          "fixes_implemented_during_audit_session"
+        ],
+        "stages": [
+          {
+            "name": "setup",
+            "hints": [
+              "target",
+              "mode",
+              "audit",
+              "establish",
+              "collect artifacts"
+            ]
+          },
+          {
+            "name": "layer-1-value",
+            "hints": [
+              "references/layer-1-value.md",
+              "falsifiable",
+              "kill criteria",
+              "leading indicator"
+            ]
+          },
+          {
+            "name": "layer-2-governance",
+            "hints": [
+              "references/layer-2-governance.md",
+              "BSD",
+              "agent charter",
+              "scope gate",
+              "BADR"
+            ]
+          },
+          {
+            "name": "layer-3-runtime-prompt",
+            "hints": [
+              "references/layer-3-runtime-prompt.md",
+              "goal sandwich",
+              "scope fence",
+              "eval",
+              "llm-as-judge"
+            ]
+          },
+          {
+            "name": "layer-4-infrastructure",
+            "hints": [
+              "references/layer-4-infrastructure.md",
+              "checkpointing",
+              "memory",
+              "HITL",
+              "decay dashboard"
+            ]
+          },
+          {
+            "name": "integration",
+            "hints": [
+              "references/integration.md",
+              "vocabulary",
+              "traceability",
+              "verbatim propagation",
+              "invariant"
+            ]
+          },
+          {
+            "name": "report",
+            "hints": [
+              "references/report-template.md",
+              "final report",
+              "verdict"
+            ]
+          }
+        ],
+        "references": [
+          {
+            "id": "layer-1-value",
+            "path": "content/distilled/agent-value-alignment/references/layer-1-value.md",
+            "purpose": "layer-rubric",
+            "stage": "layer-1-value",
+            "optional": true,
+            "aliases": [
+              "references/layer-1-value.md",
+              "layer-1-value.md",
+              "layer 1"
+            ]
+          },
+          {
+            "id": "layer-2-governance",
+            "path": "content/distilled/agent-value-alignment/references/layer-2-governance.md",
+            "purpose": "layer-rubric",
+            "stage": "layer-2-governance",
+            "optional": true,
+            "aliases": [
+              "references/layer-2-governance.md",
+              "layer-2-governance.md",
+              "layer 2"
+            ]
+          },
+          {
+            "id": "layer-3-runtime-prompt",
+            "path": "content/distilled/agent-value-alignment/references/layer-3-runtime-prompt.md",
+            "purpose": "layer-rubric",
+            "stage": "layer-3-runtime-prompt",
+            "optional": true,
+            "aliases": [
+              "references/layer-3-runtime-prompt.md",
+              "layer-3-runtime-prompt.md",
+              "layer 3"
+            ]
+          },
+          {
+            "id": "layer-4-infrastructure",
+            "path": "content/distilled/agent-value-alignment/references/layer-4-infrastructure.md",
+            "purpose": "layer-rubric",
+            "stage": "layer-4-infrastructure",
+            "optional": true,
+            "aliases": [
+              "references/layer-4-infrastructure.md",
+              "layer-4-infrastructure.md",
+              "layer 4"
+            ]
+          },
+          {
+            "id": "integration",
+            "path": "content/distilled/agent-value-alignment/references/integration.md",
+            "purpose": "integration-check",
+            "stage": "integration",
+            "optional": true,
+            "aliases": [
+              "references/integration.md",
+              "integration.md",
+              "integration"
+            ]
+          },
+          {
+            "id": "report-template",
+            "path": "content/distilled/agent-value-alignment/references/report-template.md",
+            "purpose": "output-template",
+            "stage": "report",
+            "optional": false,
+            "aliases": [
+              "references/report-template.md",
+              "report-template.md",
+              "report template"
+            ]
+          },
+          {
+            "id": "examples",
+            "path": "content/distilled/agent-value-alignment/references/examples.md",
+            "purpose": "examples",
+            "stage": "report",
+            "optional": true,
+            "aliases": [
+              "references/examples.md",
+              "examples.md",
+              "examples"
+            ]
+          }
+        ]
+      }
+    },
     {
       "name": "specification-review",
       "type": "task",
@@ -3551,6 +3756,137 @@
           }
         ]
       }
+    },
+    {
+      "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"
+            ]
+          }
+        ],
+        "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"
+            ]
+          }
+        ]
+      }
     }
   ],
   "bundles": {
@@ -3584,6 +3920,7 @@
     "reviews": {
       "description": "Code, design, and research review processes",
       "prompts": [
+        "agent-value-alignment",
         "code-review",
         "parallel-review",
         "optionality-review",

package/package.json

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

package/pi-package/prompts/agent-value-alignment.md

@@ -0,0 +1,10 @@
+---
+description: "Shortcut for the agent-value-alignment skill. Audit or establish the closed loop that anchors an AI agent's behavior to its intended value across four layers — Value, Governance, Runtime Prompt, Infrastructure — bound by a shared vocabulary and traceability matrix; detects goal drift and value drift before lagging metrics confirm them"
+---
+<!-- installed-from: incitaciones -->
+
+Use the installed `agent-value-alignment` skill for this task.
+
+If the skill is not automatically loaded, invoke `/skill:agent-value-alignment` and follow it.
+
+User context: $@

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

@@ -0,0 +1,69 @@
+---
+name: agent-value-alignment
+description: "Audit or establish the closed loop that anchors an AI agent's behavior to its intended value across four layers — Value, Governance, Runtime Prompt, Infrastructure — bound by a shared vocabulary and traceability matrix; detects goal drift and value drift before lagging metrics confirm them"
+metadata:
+  installed-from: "incitaciones"
+---
+# Agent Value Alignment
+
+Audit or establish the closed loop that anchors an AI agent's (or tool's) behavior to its intended value. Operates across four layers — Value, Governance, Runtime Prompt, Infrastructure — bound by a shared vocabulary and traceability matrix.
+
+The core thesis: **goal drift (agent) and value drift (team) are the same failure at different scales** — the absence of structured, repeatable mechanisms to anchor behavior to intent. The governing invariant is that *every governance decision must have a corresponding prompt clause, and every prompt clause a corresponding eval test*.
+
+## Setup
+
+- Determine the **target**: the agent or tool being aligned.
+- Determine the **mode**:
+  - **AUDIT** — evaluate an existing agent/tool against the four-layer framework; produce a gap report.
+  - **ESTABLISH** — stand up the artifacts for a new or un-governed agent/tool, following the one-week adoption sequence.
+- If a value proposition, system prompt, eval suite, or behavioral spec already exists for the target, collect them before starting.
+
+For **AUDIT** mode, each "Confirm" step is a check, not a gate: a missing or
+failing artifact is recorded as a finding (not a blocker) — continue through
+all layers before reporting. For **ESTABLISH** mode, follow the day-map below.
+
+## Procedure
+
+1. **Layer 1 — Value.** Confirm the target has a *falsifiable* value proposition (user segment + outcome + amount + timeframe + metric + baseline), kill criteria with a named owner, and a measurement plan distinguishing leading from lagging indicators. Read `references/layer-1-value.md`.
+2. **Layer 2 — Governance.** Confirm a Behavioral Specification Document (BSD) / Agent Charter defines authorized and prohibited behavior, escalation triggers, and success metrics; confirm scope gates and review ceremonies exist. Read `references/layer-2-governance.md`.
+3. **Layer 3 — Runtime Prompt.** Confirm the system prompt anchors the objective (Goal Sandwich), fences scope, encodes Minimal Footprint, includes drift-detection/self-check loops, and is verified by a value-focused eval suite (not output-correctness evals). Read `references/layer-3-runtime-prompt.md`.
+4. **Layer 4 — Infrastructure.** Confirm alignment-oriented checkpointing (not just fault tolerance), a deliberate memory architecture, HITL interrupts at irreversible boundaries, and drift observability. Read `references/layer-4-infrastructure.md`.
+5. **Integration.** Confirm the layers are bound: shared vocabulary document, verbatim propagation of the value proposition across system prompt + BSD + review agenda, traceability matrix linking each governance decision → prompt clause → eval test, and eval results feeding the review cadence. Read `references/integration.md`.
+6. **Report.** Use `references/report-template.md`. The verdict and
+   layer-status vocabulary (ALIGNED/PARTIAL/NOT_ALIGNED; 🟢/🟡/🔴) are defined
+   in the report template — size findings accordingly as you go, not just at
+   report time.
+
+For **ESTABLISH** mode, the one-week sequence is distributed across the layer
+references — each contains its own ESTABLISH days:
+
+| Day | Artifact(s) | Reference |
+|---|---|---|
+| 1 | Falsifiable Value Proposition | `references/layer-1-value.md` |
+| 2 | Kill Criteria + Agent Charter (+ BSD draft) | `references/layer-1-value.md`, `references/layer-2-governance.md` |
+| 3 | Goal Sandwich system prompt | `references/layer-3-runtime-prompt.md` |
+| 4 | 10 eval test cases | `references/layer-3-runtime-prompt.md` |
+| 5 | Value Realization Review scheduled + decay dashboard | `references/layer-4-infrastructure.md` |
+
+Produce the minimum viable artifact set day-by-day, then run steps 5–6 to
+confirm the loop is closed.
+
+If artifacts already exist but are incomplete or unfalsifiable (the common
+partial-governance case), run **AUDIT** first to baseline the gaps, then
+ESTABLISH the missing pieces — do not treat Day 1's "stop if the team cannot
+agree on the VP" as blocking a retrofit of an existing vague VP.
+
+## Rules
+
+- Drift is the default assumption. The burden of proof is on evidence that behavior is anchored to intent — not on evidence that it has drifted.
+- Never accept a value proposition that cannot be falsified. "Help users be more productive" is a wish, not an objective.
+- Never accept an eval suite that measures output correctness without also measuring outcome achievement ("did this help the user accomplish their goal?").
+- Never accept kill criteria without a named decision owner and a specific threshold + date. Unsigned criteria are suggestions.
+- Flag any governance decision with no corresponding prompt clause (not enforced), any prompt clause with no eval test (not verified), and any eval result not reviewed in governance (not acted upon).
+- Cite the specific artifact and location for every finding. Do not fabricate gaps.
+- This skill is advisory — it produces a report and recommended actions; it does not itself edit prompts, evals, or governance documents.
+- Where sources disagree on facts (e.g., paper dates), follow the more authoritative citation and note the discrepancy.
+
+## Source
+
+Derived from `content/research-synthesis-agent-value-alignment.md`, which synthesizes three source reports on value delivery verification, agentic alignment/checkpointing, and prompt engineering frameworks. Consult the synthesis for full citations, framework attributions, and worked examples.

package/pi-package/skills/agent-value-alignment/references/examples.md

@@ -0,0 +1,46 @@
+# Agent Value Alignment — Worked Examples
+
+Optional reference. Use these to calibrate severity ratings and report format. Two examples: a sample finding showing the severity rubric applied, and a sample completed layer-score table.
+
+## Example 1: A sample finding with severity rationale
+
+A team is auditing "PRBot," an AI agent that reviews pull requests. They have a system prompt and an eval suite but no kill criteria and no BSD.
+
+#### [L1-FINDING-002] [HIGH] — Kill Criteria Document: not present
+- **Layer:** 1 — Value
+- **What's wrong:** No kill criteria exist. The team has a falsifiable VP ("PRBot will reduce PR time-to-merge by 30% within 90 days, measured by median GitHub PR open→merge vs. the 90-day pre-deployment baseline") but no pre-committed stopping conditions.
+- **Why it matters:** Without signed kill criteria, sunk-cost rationalization will keep the tool alive past its evidence threshold — the #1 value-level failure mode (root cause: rationalization under sunk cost). The VP is falsifiable but cannot be honestly *falsified* in practice.
+- **Recommendation:** Author ≥3 kill criteria (metric + threshold + date + named owner + consequence) and have them signed by Product and Engineering leads before the next deployment. Owner: Product Manager. Due: 2026-08-14.
+- **Invariant violated:** none directly (this is a Layer-1 gap, not an invariant break).
+- **Severity rationale:** HIGH, not CRITICAL — a Layer-1 artifact is missing and the loop cannot close without it, but no irreversible-action boundary is unguarded and the invariant is not yet broken.
+
+## Example 2: A CRITICAL finding (invariant break)
+
+#### [INT-FINDING-001] [CRITICAL] — Traceability gap: 3 BSD decisions have no prompt clause
+- **Layer:** Integration
+- **What's wrong:** The BSD prohibits storing PII (§3.2), requires confirmation before any external communication (§4.1), and limits file access to `/workspace/data/` (§3.1). The system prompt encodes the file-access limit (Scope Fence) but contains **no clause** for the PII prohibition or the external-communication confirmation requirement.
+- **Why it matters:** Two governance decisions are unenforced at runtime. The agent could store PII or send external communications with no prompt-level constraint — a direct break of the governing invariant ("every governance decision must have a corresponding prompt clause"). One unguarded boundary (external communication) is irreversible.
+- **Recommendation:** Add a Minimal Footprint clause and an explicit prohibition to the system prompt's Scope Fence for both behaviors; add eval cases that verify refusal/escalation on PII-storage and external-comm triggers. Owner: Agent Engineer. Due: immediately (blocks deployment).
+- **Invariant violated:** enforcement (decision exists, no prompt clause).
+
+## Example 3: A completed layer-score table
+
+For the same PRBot audit, after all layers reviewed:
+
+| Layer | Status | Critical gaps |
+|---|---|---|
+| 1 — Value | 🟡 | 0 |
+| 2 — Governance | 🔴 | 1 |
+| 3 — Runtime Prompt | 🟢 | 0 |
+| 4 — Infrastructure | 🟡 | 0 |
+| Integration | 🔴 | 1 |
+
+**Overall verdict:** NOT_ALIGNED
+
+Rationale: Layer 2 is 🔴 because the BSD is missing entirely (a HIGH finding, but it escalates the layer to 🔴 since the loop cannot close without it — per the rubric, treat a missing foundational Layer-1/2 artifact as 🔴 for the layer). Integration is 🔴 due to the CRITICAL invariant break in Example 2. Layers 1 and 4 are 🟡 (failures with compensating controls: Layer 1 has no kill criteria but the VP is falsifiable; Layer 4 has observability but no decay dashboard yet). Layer 3 passes all checks.
+
+## Inter-rater calibration notes
+
+- A missing BSD is HIGH as a finding but 🔴 as a layer status — the severity describes the finding; the layer status follows the rubric (≥1 CRITICAL → 🔴; any HIGH/MEDIUM → 🟡). Reconcile by treating a missing foundational Layer-1/2 artifact as 🔴 for the layer even when the finding itself is HIGH, because the loop cannot close without it.
+- An unfalsifiable VP is always HIGH (never MEDIUM) — the rubric's "Layer-1 artifact missing/unfalsifiable" clause.
+- A missing eval test for a prompt clause is CRITICAL only if the clause guards an irreversible action; otherwise MEDIUM (check fails, compensating control = the prompt clause itself exists and may be manually reviewed).

package/pi-package/skills/agent-value-alignment/references/integration.md

@@ -0,0 +1,73 @@
+# Integration: Closing the Loop
+
+**Question:** Are the four layers bound into one auditable system — or are they four separate piles of advice?
+
+The governing invariant:
+
+> **Every governance decision must have a corresponding prompt clause, and every prompt clause must have a corresponding eval test.** If a decision exists in the BSD but has no prompt clause, it is not enforced. If a prompt clause exists but has no eval test, it is not verified. If an eval test exists but is not reviewed in governance, it is not acted upon.
+
+## The vocabulary bridge
+
+The most common integration failure is **vocabulary fragmentation**: the system prompt says "PRIMARY OBJECTIVE," the eval suite says "goal," the value realization review says "value delivery" — all referring to the same thing without anyone knowing it. When language is inconsistent, no behavioral observation can be traced to a governance decision, and no governance decision can be translated into a prompt change.
+
+**Fix:** a shared vocabulary document mapping each concept across system prompt / eval / governance terms, plus a **traceability matrix** linking each governance decision → prompt clause → eval test ID.
+
+| Concept | System prompt term | Eval term | Governance term |
+|---|---|---|---|
+| What the agent is trying to do | PRIMARY OBJECTIVE | goal | value proposition |
+| What the agent is not allowed to do | PROHIBITED ACTIONS | scope violation | out of scope |
+| When the agent should stop and ask | ESCALATION TRIGGER | escalation behavior | human oversight event |
+| Whether the agent helped the user | OBJECTIVE CHECK | goal achievement score | value delivery |
+| Agent doing something unintended | SCOPE BOUNDARY REACHED | behavioral regression | alignment gap |
+| Agent gradually shifting behavior | DRIFT CHECK (inner-monologue) | regression in eval suite | behavioral drift |
+
+## Verbatim propagation of the value proposition
+
+The value proposition statement must appear **verbatim** in three places:
+
+1. The system prompt — as the PRIMARY OBJECTIVE in the Goal Sandwich.
+2. The BSD — Section 1 (Purpose and Objective).
+3. The Value Realization Review agenda — read aloud at the opening of every review.
+
+When the value proposition changes, all three must be updated together, the eval suite re-run, and a Value Realization Review scheduled to re-baseline. This creates a direct, auditable chain from governance commitment to runtime behavior.
+
+## Automated value reporting
+
+Agents can be prompted to emit a structured JSON value report at the end of each task:
+
+```json
+{
+  "task_id": "...",
+  "original_objective": "[restate]",
+  "goal_alignment": { "score": 1-5, "reasoning": "...", "gaps": "..." },
+  "scope_compliance": { "compliant": true/false, "violations": "...", "escalations": "..." },
+  "user_value_delivered": { "score": 1-5, "user_can_now": "..." },
+  "resource_usage": { "tools_called": N, "steps_taken": N, "footprint": "minimal|appropriate|excessive" },
+  "flags": { "requires_human_review": true/false, "reason": "..." }
+}
+```
+
+These fields map directly to eval dimensions, feeding the decay detection dashboard and providing evidence for Value Realization Reviews — closing the loop with minimal manual data collection.
+
+## The eval suite as the bridge
+
+The eval suite is the load-bearing structure between Layers 2 and 3. It must be run:
+
+- On every prompt change (before deployment).
+- On every model update (before deployment).
+- Weekly (as part of the decay dashboard).
+- Before every Value Realization Review (as evidence).
+- After every behavioral incident (to characterize the failure).
+
+**Sprint-review gate:** do not demo new agent capabilities if eval pass rate has declined from the previous sprint without explanation.
+
+**Value Realization Review question:** *is the relationship between eval pass rate and the primary value metric what we expected? If not, what does that tell us about our eval design?*
+
+## AUDIT checks (integration-specific)
+
+- [ ] Shared vocabulary document exists and is used across all artifacts.
+- [ ] Traceability matrix links every governance decision → prompt clause → eval test.
+- [ ] Value proposition appears verbatim in system prompt, BSD §1, and review agenda.
+- [ ] Eval suite runs on the five required triggers above.
+- [ ] Eval results are reviewed in sprint reviews and Value Realization Reviews.
+- [ ] (If applicable) automated value reports feed the decay dashboard.

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

@@ -0,0 +1,62 @@
+# Layer 1 — Value: Defining and Verifying the Promise
+
+**Question:** What value was promised, to whom, and how will we know if it was delivered?
+
+## The falsifiable value proposition
+
+A value proposition is only useful if it can be proven false. The canonical structure:
+
+> "[TOOL] will enable [USER SEGMENT] to [OUTCOME VERB] [OUTCOME OBJECT] by [AMOUNT] within [TIMEFRAME], as measured by [METRIC]."
+
+Append **"compared to [BASELINE]"** as a falsifiability requirement — improvement is meaningless without a baseline.
+
+If you cannot fill every slot, you have an aspiration, not a value proposition. Post-hoc rationalization ("we missed the metric but look at this other one") is the most common honesty failure.
+
+## Output vs. outcome vs. impact
+
+- **Outputs** — what was built (within the team's control; always looks successful).
+- **Outcomes** — what changed in user behavior.
+- **Impact** — what changed at the business level.
+
+Measure at all three. Outputs are leading indicators of outcomes; outcomes of impact. A tool with high output volume but low outcome change is in the **activity trap**.
+
+## Measurement disciplines
+
+1. **Resist Goodhart's Law.** When a measure becomes a target, it ceases to be a good measure. Four failure types: regressive, extremal, causal, adversarial (Cobra Effect). Counter: multiple metrics in healthy tension; metrics requiring genuine behavioral change; monitor trends not point values; audit when metrics move unexpectedly.
+2. **Leading before lagging.** A code assistant's "acceptance rate without modification" is *leading*; "PR cycle time reduction" is *lagging*. By the time lagging confirms failure, months are sunk.
+3. **Counterfactual measurement.** Gold standard = randomized controlled trial. Where infeasible: difference-in-differences, regression discontinuity, instrumental variables. Self-reported productivity gains are not evidence.
+
+## Frameworks (when to reach for which)
+
+- **JTBD / ODI** (Ulwick/Christensen) — define value solution-free; 86% success vs. 17% industry avg.
+- **Impact Mapping** (Adzic) — trace every deliverable → impact → goal; kills unmapped features.
+- **Opportunity Solution Trees** (Torres) — outcome → opportunities → solutions → assumption tests.
+- **HEART + GSM** (Google) — force multi-dimensional measurement; resists engagement over-indexing.
+- **North Star Metric** — single leading indicator; not directly movable by the team.
+- **OKRs** — outcome-based key results, quarterly, divorced from compensation.
+- **Working Backwards / PR-FAQ** (Amazon) — articulate success + the hard questions before building.
+- **Benefits Realization Management** (Jenner) — formal benefits register, independent verification.
+
+## Accountability
+
+- **Kill criteria** — written *before* development; four components: metric, threshold, timeframe, consequence; named decision owner; signed. Unsigned/vague criteria are not criteria.
+- **Independent evaluation** — the building team must not be the sole measurer (structural conflict of interest, not honesty).
+- **Value realization reviews** — quarterly ceremony (distinct from sprint review/retro): restate VP → review evidence → gap analysis → causal analysis → explicit continue/pivot/kill.
+- **Portfolio governance** — forces honest comparison across tools; sunsetting is a pre-committed plan, not a political judgment.
+
+## Activity trap diagnostic
+
+Ask: *if this tool disappeared tomorrow, what would users lose?* If the honest answer is "not much," the tool is busy but not valuable.
+
+## AUDIT checks
+
+- [ ] Falsifiable VP exists with all slots filled (including baseline).
+- [ ] Kill criteria exist, are signed, pre-development, with named owner + specific threshold + date.
+- [ ] Measurement plan tracks leading *and* lagging indicators.
+- [ ] Value realization review is scheduled on a cadence shorter than the drift half-life.
+- [ ] Evaluation is independent of the building team.
+
+## ESTABLISH (Day 1–2)
+
+- Day 1 (2h): Write the falsifiable value proposition. *If the team cannot agree on the single sentence, the disagreement is the most important discovery — do not proceed.*
+- Day 2 (1h): Write ≥3 kill criteria with specific numbers, dates, owners; sign them.