instar 1.3.10 → 1.3.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.10",
+  "version": "1.3.11",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-27T05:11:33.728Z",
-  "instarVersion": "1.3.10",
+  "generatedAt": "2026-05-27T05:23:34.820Z",
+  "instarVersion": "1.3.11",
   "entryCount": 192,
   "entries": {
     "hook:session-start": {
@@ -401,7 +401,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -409,7 +409,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -417,7 +417,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -425,7 +425,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -433,7 +433,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -441,7 +441,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -449,7 +449,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -457,7 +457,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -465,7 +465,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -473,7 +473,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -481,7 +481,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -489,7 +489,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -497,7 +497,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -505,7 +505,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -513,7 +513,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -521,7 +521,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -529,7 +529,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -537,7 +537,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -545,7 +545,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -553,7 +553,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -561,7 +561,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -569,7 +569,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -577,7 +577,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -585,7 +585,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -593,7 +593,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -601,7 +601,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -609,7 +609,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -617,7 +617,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -625,7 +625,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -633,7 +633,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -641,7 +641,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -649,7 +649,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -657,7 +657,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -665,7 +665,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -673,7 +673,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -681,7 +681,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -689,7 +689,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -697,7 +697,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -705,7 +705,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -713,7 +713,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -721,7 +721,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -729,7 +729,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -737,7 +737,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -753,7 +753,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "94f598954bbaa4a106d3b546e822387eea96f3ea04973f2d6a053685aa410724",
+      "contentHash": "768d0dfd6edc7bfa93f3a33e271607a5a4264183c43204900480b84cb9a4e294",
       "since": "2025-01-01"
     },
     "cli:init": {

package/upgrades/1.3.11.md

@@ -0,0 +1,40 @@
+# Instar Upgrade Guide — NEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Framework-Onboarding Mentor System — playbook promotion + observability (§19.5).** The final
+buildable-while-dormant piece. Adds the playbook lifecycle (`none → candidate → extracted →
+superseded`) with a **non-Echo attestation gate**: the mentor can flag a lesson as a candidate, but
+it cannot promote its own lesson into the reusable onboarding checklist — `candidate → extracted`
+requires a non-Echo party to attest, and who attested is recorded. This is the structural anti-gaming
+guard that keeps the playbook from being end-to-end under the proposing agent's control. Also adds an
+adversarial-telemetry read-out: bucket-distribution (a spike in "blame the mentee" is the tell),
+leak-suspected count, probable-loop count, and how many lessons reached the playbook.
+
+Two new read-only routes; the `promoted_by` column migrates forward on existing ledgers via an
+idempotent `ALTER TABLE`. Still part of the dormant mentor system — nothing activates.
+
+## What to Tell Your User
+
+- The mentor can now nominate a lesson for the reusable checklist, but it can't graduate its own
+  lessons — that needs a sign-off from someone other than the mentor, and the system records who.
+- There's a one-glance read-out of the issue mix and the safety counters (leak hits, runaway-loop
+  flags), so drift is visible.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Playbook promotion | `POST /framework-issues/:id/promote` `{status, promotedBy}` — `extracted` requires a non-Echo attester |
+| Observability telemetry | `curl -H "Authorization: Bearer $AUTH" http://localhost:<port>/framework-issues/observability` — bucket distribution + leak/loop/extracted counts |
+
+## Evidence
+
+Net-new feature, not a bug fix — no prior failure to reproduce. The non-Echo gate is proven on both
+sides: a unit test asserts `candidate→extracted` is **refused when the attester is `echo` or empty**
+(throws "non-Echo attestation required") and **allowed + records `promoted_by`** for a non-Echo actor;
+an integration test confirms the same over HTTP (400 for Echo, 200 + `promotedBy` for a non-Echo
+attester). Observability counts are asserted against a seeded ledger. 11 new tests; affected
+push-config suite green vs canonical main; route docs-coverage 56% ≥ 55% floor.

package/upgrades/side-effects/mentor-playbook-observability.md

@@ -0,0 +1,62 @@
+# Side-Effects Review — Playbook promotion (non-Echo gate) + observability (§19.5)
+
+**Spec:** `docs/specs/FRAMEWORK-ONBOARDING-MENTOR-SPEC.md` (converged 5 iters, approved by Justin)
+**Change:** Two additions to the FrameworkIssueLedger (§19.1) + two read-only-ish routes:
+`promotePlaybook()` (none→candidate→extracted→superseded, with a **non-Echo attestation gate** on
+candidate→extracted, §13.6) and `observability()` (bucket-distribution + leak/probable-loop/extracted
+counts, §15). New routes `POST /framework-issues/:id/promote` and `GET /framework-issues/observability`.
+**Files:** `src/monitoring/FrameworkIssueLedger.ts`, `src/server/routes.ts`,
+`src/server/CapabilityIndex.ts`, `tests/unit/FrameworkIssueLedger.test.ts`,
+`tests/integration/framework-issues-routes.test.ts`, `upgrades/NEXT.md`.
+
+## Principle check (Phase 1)
+
+Does this involve a decision point that gates info flow / blocks actions / constrains behavior?
+**Yes — and it's a structural authority boundary, the good kind.** `promotePlaybook` enforces that
+the proposing agent (Echo) cannot promote its own lesson into the reusable playbook — candidate→
+extracted requires a non-Echo attestation. This is a *gate on the agent itself*, not authority over
+the user's world; it can only refuse a promotion (signal/anti-gaming), never block another component.
+`observability` is pure read-only telemetry.
+
+## The seven questions
+
+1. **Over-block.** `promotePlaybook` refuses candidate→extracted by Echo (or an empty attester) —
+   intentional (§13.6). Other transitions (none→candidate, →superseded) are unrestricted. No
+   legitimate promotion by a non-Echo actor is blocked.
+2. **Under-block.** The attester is a free-string compared case-insensitively against `echo`. A
+   determined Echo could pass a different literal — but the route is operator/human-driven and the
+   recorded `promoted_by` makes any promotion auditable (a spoofed attester is visible). The gate is
+   the structural deterrent + the audit trail is the backstop; matches the `difficultyAttestedBy`
+   pattern from §7.3.
+3. **Level-of-abstraction fit.** Both methods live on the ledger that owns the data; the routes are
+   thin pass-throughs. `observability` reuses indexed columns (bucket, playbook_status, signature).
+   Correct layer.
+4. **Signal vs authority.** Compliant. `observability` is signal. `promotePlaybook`'s only authority
+   is to *refuse* a self-promotion (an anti-gaming guard on the proposer) — it never gates messaging,
+   sessions, or other components. Promotion to `extracted` is reserved for a non-Echo actor (§13.6).
+5. **Interactions.** Adds a `promoted_by` column via an idempotent `ALTER TABLE … ADD COLUMN`
+   (duplicate-column errors swallowed in init) so ledgers created by §19.1/§19.2 (v1.3.5–1.3.9)
+   migrate forward on first boot. No interaction with the capture funnel or Stage-A paths.
+6. **External surfaces.** Two routes behind Bearer auth, added to the existing `frameworkIssues`
+   CapabilityIndex entry (no new prefix → no discoverability gap). No template/config change.
+7. **Rollback cost.** Low. Revert removes the routes/methods; the `promoted_by` column is harmless if
+   left. No data migration beyond the additive column.
+
+## Phase 5 — second-pass
+
+**Not required.** The promotion gate is a single pure attestation check (`promotedBy != echo`),
+unit-tested on both sides (Echo refused; non-Echo allowed + recorded); `observability` is read-only.
+No session lifecycle, no spawning, no blocking of another component, nothing named
+sentinel/guard/watchdog. The decision-bearing live loop (§19.4) already carried its dedicated
+second-pass.
+
+## Testing
+
+- Tier 1 (unit, +6): promotePlaybook none→candidate by any actor; **candidate→extracted REFUSED for
+  Echo / empty attester**; allowed + `promoted_by` recorded for a non-Echo actor; invalid-status
+  guard; unknown-issue null; observability bucket-distribution + leak/extracted counts.
+- Tier 2 (integration, +5): observability 503/200; promote rejects Echo (400), allows non-Echo (200),
+  404 unknown.
+- route-completeness + capabilities-discoverability gates pass (new catch uses `instanceof`; new
+  routes fall under the classified `/framework-issues` prefix).
+- Affected push-config suite green vs canonical main; route docs-coverage 56% ≥ 55% floor.