kenaz 0.0.0-stage → 0.3.2

package/core/.specialist/REFLECTION_TO_CONTROL.md

@@ -0,0 +1,347 @@
+# Reflection-to-Control Contract (TASK_1071, schema: TASK_1075)
+
+## Schema Reference
+
+| Artifact | Path |
+|----------|------|
+| JSON Schema (canonical) | `.specialist/shared/guard_schema.json` |
+| Guard store (Ansuz) | `.specialist/Ansuz/guards/lesson_guards.yaml` |
+| Guard store (other specialists) | `.specialist/{SpecialistName}/guards/lesson_guards.yaml` |
+| Acted-on log | `.kenaz/specialist/lesson_guard_acted_on.jsonl` |
+
+The JSON Schema at `.specialist/shared/guard_schema.json` is the single source of truth for the guard document format. It defines `LessonGuardDocument`, `GuardEntry`, `PhaseInjectionContract`, `PromotionRequest`, and cross-field `ValidationRules`. Tools must validate against this schema before writing. Parsers must reject documents with `version` higher than their supported version.
+
+## Problem
+
+Reflections from Synapse runes, Muninn episode lessons, and post-session cognitive
+checkpoints exist as **narrative-only artifacts**. They are read at session start but do
+not alter phase-gate behavior in a verifiable, trackable way. Repeated failure modes
+persist across sessions because the gap between *knowing a lesson* and *enforcing it at
+decision time* is never closed.
+
+## Solution: Lesson Guards
+
+A **lesson guard** (L-XXX) is a durable reflection that has been **promoted into an
+executable condition** injected automatically at phase-gate enter time. Unlike blind spot
+guards (B-XXX, which come from the self-model), lesson guards originate from:
+
+- Synapse runes (`synapse_inscribe` outputs)
+- Muninn episode lessons (episodic memory lessons)
+- Manual reflection promotion (any text the specialist deems worth enforcing)
+
+## Files
+
+| File | Role |
+|------|------|
+| `.specialist/Ansuz/guards/lesson_guards.yaml` | Canonical guard store — source of truth |
+| `.specialist/tools/lesson-guard.js` | CLI tool for the full promotion/tracking lifecycle |
+| `.specialist/tools/phase-gate.js` | Phase-gate consumes lesson guards at `enterPhase()` |
+| `.kenaz/specialist/lesson_guard_acted_on.jsonl` | Append-only log of guard-influenced decisions |
+
+## Control-Path Flow
+
+```
+Reflection origin                Phase-gate injection          Effectiveness tracking
+─────────────────                ────────────────────          ──────────────────────
+Synapse rune / Muninn            enterPhase(N) calls           record-acted-on appends
+episode lesson / manual text     readLessonGuardsForPhase(N)   to lesson_guard_acted_on.jsonl
+        │                        → injects guard text into      AND increments
+        ▼                          phase output JSON            acted_on_count in YAML
+  lesson-guard.js promote         (field: lesson_guards)
+        │
+        ▼
+  lesson_guards.yaml
+  (status: active)
+```
+
+## Guard Lifecycle
+
+Full lifecycle (from raw reflection to expired guard):
+
+```
+[Raw Reflection]
+  Synapse rune / Muninn lesson / manual text
+        │
+        ▼ lesson-guard.js promote
+   ┌─────────┐
+   │ pending │  ← awaiting review (when promotion_policy=explicit_review)
+   └────┬────┘
+        │ review pass (or self_promote policy — goes directly here)
+        ▼
+   ┌────────┐
+   │ active │  ← injected at phase enter; tracked for effectiveness
+   └────┬───┘
+        │
+   ┌────┴──────┐
+   ▼           ▼
+┌──────────┐  ┌─────────┐
+│suspended │  │ expired │  (final state — no new guards from here; create new)
+└────┬─────┘  └─────────┘
+     │ resume
+     └──────► active
+```
+
+| Status | Injected at phase enter? | Tracked? | Notes |
+|--------|--------------------------|----------|-------|
+| `pending` | No | No | Created but not yet approved for injection |
+| `active` | Yes | Yes | Default state after self-promote promotion |
+| `suspended` | No | Retained for audit | Temporarily paused; resumable |
+| `expired` | No | Retained for audit | Final state; non-reversible |
+
+**Allowed transitions:**
+
+| From | To | Who may trigger |
+|------|----|-----------------|
+| `pending` | `active` | reviewer (explicit_review policy) or tool (self_promote policy) |
+| `pending` | `expired` | reviewer (rejection) |
+| `active` | `suspended` | owning specialist or human |
+| `active` | `expired` | owning specialist, human, or auto (expires_after_sessions) |
+| `suspended` | `active` | owning specialist or human |
+| `suspended` | `expired` | owning specialist or human |
+| `expired` | anything | **FORBIDDEN** — create a new guard instead |
+
+## CLI Reference
+
+### Promote a reflection into a guard
+
+```bash
+node .specialist/tools/lesson-guard.js promote \
+  --lesson="Never skip kenaz_lsp_callers before editing a function with >3 callers" \
+  --phases="[1,2,3]" \
+  --source=synapse \
+  --source-id="rune_abc123" \
+  --condition-1="Phase 1 planning: identify all functions with >3 callers; require pulse before scheduling." \
+  --condition-3="Phase 3 dispatch: include explicit pulse instruction in agent prompt for high-fan-out symbols."
+```
+
+If no `--condition-N` flags are given, the `--lesson` text is used as the condition for all declared phases.
+
+### List active guards
+
+```bash
+node .specialist/tools/lesson-guard.js list --status=active
+```
+
+### Record that a guard influenced a decision
+
+Call this when you notice that an injected lesson guard actually changed what you did:
+
+```bash
+node .specialist/tools/lesson-guard.js record-acted-on L-002 session-xyz-20260410 \
+  --reason="Guard prompted me to run kenaz_lsp_callers before editing dispatch.js — found 5 callers I had missed"
+```
+
+### View effectiveness statistics
+
+```bash
+node .specialist/tools/lesson-guard.js status --verbose
+```
+
+### Suspend a guard (temporarily pause without deleting)
+
+```bash
+node .specialist/tools/lesson-guard.js suspend L-002 --reason="Condition no longer relevant after refactor"
+```
+
+### Expire a guard (final state)
+
+```bash
+node .specialist/tools/lesson-guard.js expire L-002
+```
+
+## Phase-Gate Integration
+
+`phase-gate.js enterPhase()` loads lesson guards for phases >= 1. The output JSON includes:
+
+```json
+{
+  "lesson_guards": [
+    {
+      "id": "L-002",
+      "lesson": "Always check for existing MCP tool before building a new one",
+      "guard": "Phase 1: Before designing the approach, run Grep to check whether the capability already exists.",
+      "source": "synapse",
+      "source_id": "rune_def456"
+    }
+  ]
+}
+```
+
+When `lesson_guards` is non-null, the specialist must acknowledge and apply each guard
+condition. The `lesson_guards_injected` field in the phase chart records which guard IDs
+were present when the phase was entered.
+
+## Adoption Pattern for Specialists
+
+When Ansuz or another specialist notices a non-obvious lesson during Phase 9 or Phase 11:
+
+1. Inscribe it as a Synapse rune (`synapse_inscribe`)
+2. Promote it to a lesson guard:
+   ```bash
+   node .specialist/tools/lesson-guard.js promote \
+     --lesson="<lesson text>" \
+     --phases="[1,2,3]" \
+     --source=synapse \
+     --source-id="<rune_id>"
+   ```
+3. In future sessions, when the phase output includes `lesson_guards`, apply them
+4. If the guard actually changed a decision, record it:
+   ```bash
+   node .specialist/tools/lesson-guard.js record-acted-on <id> <session-id>
+   ```
+
+## Effectiveness Measurement
+
+A guard is **effective** when `acted_on_count > 0`. A guard that has been injected many
+times but never acted on is a candidate for expiration (either the lesson was not
+actionable, or it was already so internalized that no explicit reminder is needed).
+
+Review guards periodically:
+```bash
+node .specialist/tools/lesson-guard.js status --verbose
+```
+
+## Relationship to Blind Spot Guards
+
+| Dimension | Blind Spot Guards (B-XXX) | Lesson Guards (L-XXX) |
+|-----------|---------------------------|-----------------------|
+| Source | Self-model (`ansuz_self_model.json`) | Synapse rune / Muninn / manual |
+| Phases | >= 3 | >= 1 |
+| ID pattern | B-001, B-002 | L-001, L-002 |
+| Managed by | `phase-gate.js` + self-model | `lesson-guard.js` |
+| Effectiveness tracking | No | Yes (`acted_on_count`) |
+
+Both systems are additive. A lesson guard can encode the same behavior as a blind spot
+guard, but with more flexible sourcing, finer phase targeting, and explicit effectiveness
+measurement.
+
+## Validation Rules
+
+These rules are defined in `guard_schema.json/$defs/ValidationRules` and must be enforced by all tools that write guard documents.
+
+| Rule | Level | Description |
+|------|-------|-------------|
+| `conditions_cover_phases` | ERROR | Every integer in `phases` must have a key in `conditions`. Guards with missing entries must not be injected. |
+| `acted_on_count_sync` | ERROR | `acted_on_count` must equal `len(acted_on_sessions)`. The promotion tool recomputes on write. |
+| `source_id_for_non_manual` | WARN | Guards with `source=synapse` or `source=muninn` should have a non-empty `source_id`. |
+| `no_reverse_transitions` | ERROR | `expired` is a terminal state. Attempting to transition away from it must fail with an error. |
+| `lesson_immutable` | ERROR | The `lesson` field must not change after creation. To update a lesson, expire the old guard and promote a new one. |
+| `phases_non_empty` | ERROR | `phases` must contain at least one entry (enforced by `minItems: 1` in JSON Schema). |
+| `id_pattern` | ERROR | Guard IDs must match `^L-[0-9]{3,}$`. Consumers must reject non-conforming IDs. |
+
+## Ownership Boundaries
+
+Ownership governs who may create, approve, and retire guards. The `owner` and `reviewed_by` fields in `GuardEntry` record this at the artifact level.
+
+| Action | Allowed Principals |
+|--------|--------------------|
+| Promote (create pending/active) | Any specialist agent, any human |
+| Approve pending → active | Any specialist agent or human with `promotion_policy=explicit_review`; automatic for `self_promote` |
+| Suspend active guard | Owning specialist or human |
+| Expire guard | Owning specialist, human, or auto-expiry via `expires_after_sessions` |
+| Modify `lesson` (forbidden) | Nobody — expire and recreate instead |
+| Append to `acted_on_sessions` | Any specialist that observed guard influence on a decision |
+
+**Promotion policies** (set per specialist in `capability.yaml`):
+- `self_promote` (default): `promote` command writes directly to `active`. The `reviewed_by` field is set to the promoting agent's identity.
+- `explicit_review`: `promote` writes to `pending`. A separate approval step (human or designated reviewer agent) transitions to `active` and sets `reviewed_by`.
+
+## Multi-Specialist Support
+
+The schema is specialist-agnostic. Each specialist maintains its own guard store:
+
+```
+.specialist/Ansuz/guards/lesson_guards.yaml   ← Ansuz-owned guards
+.specialist/Amelia/guards/lesson_guards.yaml  ← Amelia-owned guards (future)
+.specialist/Huginn/guards/lesson_guards.yaml  ← Huginn-owned guards (future)
+```
+
+All stores conform to the same JSON Schema (`guard_schema.json`). Guards in a specialist-specific file implicitly scope to that specialist even when the `specialist` field is empty.
+
+The `lesson-guard.js` tool resolves the correct guard store path based on which specialist is invoking it. Shared guards (applying to all specialists) can be stored in a future `.specialist/shared/lesson_guards.yaml` when multi-specialist injection is implemented.
+
+## Phase Injection Contract
+
+When `phase-gate.js enterPhase(N)` loads guards for phase N, it emits a `lesson_guards` array in its output JSON. Each element conforms to `guard_schema.json/$defs/PhaseInjectionContract`:
+
+```json
+{
+  "lesson_guards": [
+    {
+      "id": "L-002",
+      "lesson": "Always check for existing MCP tool before building a new one",
+      "guard": "Phase 1: Before designing the approach, run Grep to check whether the capability already exists.",
+      "source": "synapse",
+      "source_id": "rune_def456"
+    }
+  ]
+}
+```
+
+**Specialist obligation when `lesson_guards` is present:**
+1. Acknowledge each guard in the `lesson_guards` array.
+2. Apply the `guard` condition to decisions made in this phase.
+3. If the guard demonstrably altered a decision, call `record-acted-on` before phase exit.
+
+The `lesson_guards_injected` field in the phase chart records which guard IDs were present at phase entry (for audit purposes).
+
+## Design Principles
+
+- **Explicit control-path hooks over implicit prompt growth** — guards are injected at
+  discrete phase boundaries, not appended to every prompt.
+- **Graceful degradation** — if `lesson-guard.js` is unavailable, phase-gate continues
+  normally (try/catch in `enterPhase`).
+- **Append-only audit log** — `lesson_guard_acted_on.jsonl` is never modified; it is
+  the ground-truth record that guards were applied.
+- **No external dependencies** — pure Node.js, same pattern as `phase-gate.js`.
+- **Schema-first stability** — `guard_schema.json` is the contract; tools and specialists consume it without parsing narrative text. Changes to the schema increment `version`; consumers must handle older versions gracefully.
+
+
+## Failure Detector Integration (TASK_1653, R0 shadow mode)
+
+### failure_signature: string vs. object form
+
+The `failure_signature` field on a guard entry accepts **two forms**:
+
+| Form | Example | Validated by |
+|------|---------|--------------|
+| String (legacy/heuristic) | `failure_signature: "revert"` | `validateGuardEntry`: must be string or object |
+| **Object (canonical)** | see below | `validateGuardEntry`: object must have a `type` field |
+
+The JSON Schema (`guard_schema.json`) documents `failure_signature` as a string field — this is a **schema/code drift**. `validateGuardEntry` in `lesson-guard.js` already accepts the object form (lines 541-547) and `serializeLessonGuardsYaml` serializes it as a YAML block. The schema version remains **v2** (no version bump required — the object form is a transparent extension).
+
+**Object form schema** (enforced by `validateGuardEntry`):
+```yaml
+failure_signature:
+  type: git_commit_pattern   # required; must be one of the 5 detector types
+  keywords: [revert, conflict]   # optional; used for commit-message matching
+  rationale: "why this signature detects the guard condition"   # optional; documentation
+```
+
+Valid `type` values: `git_commit_pattern`, `acceptance_grep_miss`, `merge_conflict`, `regression_test_failure`, `surprise_file_in_scope`.
+
+When `type` is set, `failure-detector.js:inferDetectorType()` uses it directly (object form wins over keyword heuristic).
+
+### detector_mode field
+
+A passthrough field (not in JSON Schema v2, serialized via the unknown-field path in `serializeLessonGuardsYaml`):
+
+| Value | Behavior |
+|-------|----------|
+| `shadow` | Log detections to `guard_detector_shadow.jsonl` only; NO stat mutation (`hit_rate`, `inferred_acted_on`, `inferred_failure` remain unset) |
+| `live` | Update guard stats; auto-expire eligible guards |
+
+Guards without `detector_mode` are treated as `shadow` by `runDetectorsForTask` (safe default: `isShadow = guardFromYaml.detector_mode !== 'live'`).
+
+### Chart-source for lesson_guards_injected (TASK_1653 finding)
+
+`lesson_guards_injected` and `lesson_guards_snapshot` are written by `phase-gate.js:enterPhase()` into the **Ansuz session chart** (e.g., `chart_diagnose_webview_memory.json`), NOT into dispatched worker task charts (`chart_TASK_XXXX.json`).
+
+Consequence for the failure detector: `failure-detector.js cmdRun` reads `chart_<taskId>.json` which is the worker chart — this file never has `lesson_guards_injected`. The production caller (`.formation/tools/post-complete.js` Step 4.6) solves this by reading guard snapshots **directly from `lesson_guards.yaml`** via `readGuards()`, building minimal snapshots for all active guards with `failure_signature != null`. This is reliable regardless of which chart the session used.
+
+### post-complete wiring (Step 4.6)
+
+`.formation/tools/post-complete.js` Step 4.6 calls `runDetectorsForTask` immediately after Step 4.5 (attribution report). Pattern: same fire-and-forget / try-catch resilience — any detector failure is swallowed and logged as a warning. Does NOT block post-complete.
+
+Shadow log output: `.kenaz/specialist/guard_detector_shadow.jsonl`
+CLI to inspect: `node .specialist/tools/failure-detector.js shadow-log --limit 20`

package/core/.specialist/ansuz_session_handoff.json

@@ -0,0 +1,96 @@
+{
+  "session_id": "ansuz-autonomous-2026-05-20-14-43",
+  "generated_at": "2026-05-20T14:48:30Z",
+  "trigger": "live_phase_exit",
+  "last_milestone": "TASK_1460 complete + knowledge consolidation (10 runes inscribed on health metrics, EmberCard patterns, KuzuDB safety)",
+  "isbar": {
+    "situation": "Session resumed autonomously multiple times. All P1 tasks complete (TASK_1460: Training Hours Widget). Health metrics trust system fully operational from previous session. System in stable state with no critical issues.",
+    "background": "Recent work: (1) Health metric trust audit + SUBMETRIC_REGRESSION verdict + reflog cross-check + KuzuDB connection safety (TASK_1459), (2) Training Hours Widget implementation (TASK_1460), (3) Rune consolidation on high-heat code areas",
+    "assessment": "System healthy: connection safety working, no rune conflicts, no orphan code detected. All safeguards operational. Knowledge preservation active (10 runes inscribed with confidence 0.8-0.92). KuzuDB at max capacity due to active indexing (expected, gracefully degraded). No pending proposals.",
+    "recommendation": "Continue autonomous work on strategic initiatives: (1) NeuralLink integration verification, (2) Episode consolidation review (20 episodes queued), (3) ARC-AGI CognitiveLabs collaboration, (4) EMBER Phase C integration"
+  },
+  "completed_work": [
+    {
+      "task_id": "TASK_1460",
+      "title": "Training Hours Widget",
+      "status": "complete",
+      "merge_landed": true,
+      "branch": "xyz951610",
+      "files_changed": 3,
+      "commit": "b5dd26de"
+    }
+  ],
+  "runes_inscribed": [
+    {
+      "symbol": "health.js:measureHealthScoreSync",
+      "type": "decision",
+      "confidence": 0.85,
+      "topic": "HTTP child process for SNN health measurement"
+    },
+    {
+      "symbol": "health.js:computeSubMetricDeltas",
+      "type": "insight",
+      "confidence": 0.9,
+      "topic": "SUBMETRIC_REGRESSION detection engine"
+    },
+    {
+      "symbol": "health.js:saveTaskHealthSnapshot",
+      "type": "decision",
+      "confidence": 0.85,
+      "topic": "Health snapshot persistence with metric_trust"
+    },
+    {
+      "symbol": "synapse.rs:compute_metric_trust",
+      "type": "insight",
+      "confidence": 0.88,
+      "topic": "Metric trust weighting and index staleness penalties"
+    },
+    {
+      "symbol": "post-complete.js:SUBMETRIC_REGRESSION logic",
+      "type": "decision",
+      "confidence": 0.9,
+      "topic": "Per-dimension degradation detection"
+    },
+    {
+      "symbol": "post-complete.js:trust-gated REVERT",
+      "type": "decision",
+      "confidence": 0.9,
+      "topic": "Trust threshold override to prevent false positives"
+    },
+    {
+      "symbol": "connection/mod.rs:acquire_connection_slot",
+      "type": "insight",
+      "confidence": 0.92,
+      "topic": "KuzuDB concurrency safety with MAX_TOTAL_CONNECTIONS=6"
+    },
+    {
+      "symbol": "EmberCard.tsx:calcActivation",
+      "type": "decision",
+      "confidence": 0.8,
+      "topic": "SNN activation metric computation from Thalamus potentials"
+    },
+    {
+      "symbol": "EmberCard.tsx:pollThalamus",
+      "type": "insight",
+      "confidence": 0.85,
+      "topic": "Real-time dashboard feedback from Thalamus SNN"
+    }
+  ],
+  "ddx_signals": {
+    "current": "DDx neurons firing on EmberCard (high-heat, low-knowledge). Curiosity spike resolved via rune inscription.",
+    "pattern": "High-heat symbols (frequently accessed/displayed) benefit from knowledge documentation",
+    "next_probes": ["NeuralLink Ansuz integration", "Episode consolidation review", "EMBER Phase C status"]
+  },
+  "system_status": {
+    "connection_pool": "7/6 slots (at max due to indexing — expected, gracefully degraded)",
+    "pending_proposals": 0,
+    "episodes_due_consolidation": 20,
+    "active_tasks": 0,
+    "rune_conflicts": 0
+  },
+  "next_phase": {
+    "immediate": "Check NeuralLink Ansuz integration status; verify episode consolidation pipeline",
+    "strategic": "EMBER Phase C integration, ARC-AGI CognitiveLabs collaboration, Cognitive Evolution validation",
+    "user_dependent": "Await direction on next strategic initiative; autonomy contract enables self-directed agenda"
+  }
+}