kenaz 0.0.0-stage → 0.3.2

package/core/dev/archive/ansuz/designs/semantic_markdown_extraction.md

@@ -0,0 +1,167 @@
+# Semantic Markdown Extraction Design
+
+## Purpose
+
+This design adds an LLM concept layer on top of the existing structural markdown extractor. It is inspired by graphify v4's corpus extraction pattern, where Claude subagents run over documents to extract concepts, relationships, and design rationale. This document is design-only; it does not implement the feature.
+
+The baseline remains `dashboard/src-tauri/src/features/synapse/scanner.rs:3593` `extract_markdown`. In this worktree the same structural extractor has moved lower in `scanner.rs`, but the design anchor is the existing `extract_markdown(content, file_path)` function. The semantic layer is additive: it reads the markdown body and structural nodes already produced by `extract_markdown`, then proposes additional Concept nodes and LLM-derived relationship edges.
+
+## Structural Baseline
+
+`extract_markdown` currently extracts:
+
+- one `Document` symbol for the markdown file;
+- `Section` symbols from headings;
+- relative links and wikilinks;
+- tags from frontmatter and inline `#tag` syntax.
+
+The per-file carrier is `MarkdownFileData`, defined at `scanner.rs:3564` in the task anchor. The semantic layer reads these current fields as input:
+
+- `doc_id`: structural Document symbol ID for the markdown file.
+- `rel_path`: relative path used as `Symbol.file_path`.
+- `links`: structural link facts as `(source_sym_id, raw_target_path, anchor)`.
+- `tags`: structural tag facts as `(source_sym_id, tag_name)`.
+
+The layer also reads the markdown file content itself and the structural Concept nodes already created from tags. It does not change `extract_markdown`, and it does not reinterpret deterministic structural output.
+
+## Dispatch Model
+
+Decision: use `formation: unit` for per-file semantic extraction. Each markdown file is independent enough for a single lightweight subagent, and batch-level coordination can remain in the caller.
+
+The caller reuses `.formation/tools/headless.js`; no new dispatch primitive is introduced. A future implementation can invoke the existing headless Formation path with a prompt that asks the unit agent to return strict JSON.
+
+Subagent contract:
+
+```json
+{
+  "input": {
+    "project_path": "<absolute project path>",
+    "file_path": "<relative markdown path>",
+    "content_hash": "<sha1 or existing File.content_hash>",
+    "markdown_content": "<raw markdown content>",
+    "document": {"symbol_id": "<doc_id>", "name": "<document name>"},
+    "sections": [{"symbol_id": "<section_id>", "name": "<heading>", "start_line": 1, "end_line": 20}],
+    "structural_concepts": [{"symbol_id": "concept_<project_hash>_<tag>", "name": "<normalized tag>"}]
+  },
+  "output": {
+    "new_concepts": [
+      {
+        "name": "Semantic Extraction",
+        "description": "Short concept description suitable for Symbol.docstring.",
+        "source_span": {"start_line": 10, "end_line": 18},
+        "confidence": 0.84
+      }
+    ],
+    "new_edges": [
+      {
+        "from_concept": "Semantic Extraction",
+        "to_concept": "Structural Markdown Extraction",
+        "relation_type": "refines",
+        "evidence": "Short body-derived rationale.",
+        "confidence": 0.78
+      }
+    ]
+  }
+}
+```
+
+The caller validates the JSON schema, clamps confidence to `[0.0, 1.0]`, resolves concept names to symbol IDs, and persists only validated records.
+
+## Provenance And Layer Isolation
+
+All LLM-derived edges must persist as `EdgeProvenance::Inferred(confidence)` from `dashboard/src-tauri/src/features/synapse/memory.rs:300`. The confidence emitted by the subagent maps directly to the enum:
+
+- `0.0 <= confidence <= 1.0` becomes `EdgeProvenance::Inferred(confidence as f32)`.
+- database serialization uses the existing string form, for example `Inferred(0.78)`.
+
+Structural edges stay `EdgeProvenance::Extracted`. The semantic layer must preserve structural edges and never overwrite `Extracted` provenance. If a semantic proposal duplicates an existing structural edge, the proposal is dropped or stored separately as review evidence; it must not replace the structural row with `Inferred(...)`.
+
+Layer isolation rule: deterministic scanner output owns `Document`, `Section`, structural `Concept`, `LINKS_TO`, `SECTION_OF`, and `TAGGED_WITH` facts. The semantic layer owns only validated LLM concept descriptions and the closed set of semantic inferred relations below. The two layers never overwrite each other.
+
+## Concept Merge Rule
+
+Structural Concepts are project-scoped. The existing insertion path around `scanner.rs:4077-4090` uses Concept records with empty `file_path`, lowercased name as the symbol key, `kind=Concept`, and the stable ID scheme `concept_{project_hash}_{tag_name}`.
+
+Merge rule: deduplicate at the project scope by normalized name, not by file. Normalize by trimming whitespace, lowercasing, replacing internal whitespace with a single space, and applying the same tag-name normalization used by structural concepts. When the LLM proposes a Concept whose normalized name matches an existing structural Concept in the same project, prefer the structural `symbol_id` and never replace it.
+
+Baseline matching is case-insensitive exact normalized-name equality. Optional near-match support may use Levenshtein similarity >= 0.92 only for review suggestions; it must not auto-merge without recording the matched names and confidence. This prevents a same-file bias and keeps the dedup axis project-level normalized name.
+
+## Concept Schema Contract
+
+Chosen option: write the LLM concept description into the existing `Symbol.docstring` field.
+
+Rationale: the structural Concept schema already has fixed fields: `name`, `kind=Concept`, `signature=#tag`, `docstring`, `source`, `language`, `start_line`, `end_line`, and `file_path`. Structural tag Concepts currently leave `docstring` empty, so the semantic layer can enrich that field without adding schema surface. There is no synonyms column, and this design does not add one.
+
+For a new LLM-only Concept:
+
+- `name`: normalized concept name.
+- `kind`: `Concept`.
+- `signature`: `#<normalized-name>` for compatibility with structural concept display.
+- `docstring`: LLM description.
+- `source`: short evidence snippet from the markdown body.
+- `language`: `markdown`.
+- `start_line` / `end_line`: best source span, or `0` when file-level.
+- `file_path`: empty string for project-scoped concepts.
+
+For an existing structural Concept, only an empty `docstring` may be filled with the LLM description. Existing non-empty `docstring` values are preserved unless a future explicit review workflow accepts an update.
+
+## Edge Type Taxonomy
+
+Allowed LLM relation types are a closed set:
+
+- `semantically_similar_to`: concepts express substantially similar meaning.
+- `depends_on`: one concept requires the other to make sense or operate.
+- `contradicts`: concepts make incompatible claims or design choices.
+- `refines`: one concept narrows, specifies, or improves another.
+- `instance_of`: one concept is a concrete instance of a broader concept.
+- `describes`: a concept explains the purpose or behavior of another concept.
+- `motivates`: one concept gives rationale for another.
+
+Excluded structural duplicates: `LINKS_TO` and `PART_OF` are not allowed LLM relation types. `LINKS_TO` remains the deterministic markdown link relation; `PART_OF` is excluded because section/document containment is structural, not semantic inference.
+
+## Incremental Cache
+
+Decision: use a dedicated SQLite table in the existing Synapse memory database for semantic markdown extraction state.
+
+The table should key by `(project_path, file_path)` and store:
+
+- `content_hash`: hash of the exact markdown content sent to the subagent.
+- `model_id`: LLM/model identifier used for extraction.
+- `prompt_version`: semantic extraction prompt/schema version.
+- `extracted_at`: timestamp.
+- `result_hash`: hash of validated output JSON for audit/debugging.
+- `status`: `ok`, `skipped`, or `error`.
+
+Skip rule: if `content_hash`, `model_id`, and `prompt_version` match the cached row, skip semantic extraction for that file. This follows the TASK_1332 content-hash pattern: unchanged content should not re-dispatch expensive work.
+
+Justification: a SQLite table keeps semantic state transactional with memory/provenance state, supports indexed lookup during incremental scans, and avoids managing separate file cleanup for renamed or deleted markdown paths.
+
+## Processing Flow
+
+1. Run structural markdown extraction first via `extract_markdown`.
+2. Insert Document, Section, structural Concept, `SECTION_OF`, `TAGGED_WITH`, and `LINKS_TO` facts exactly as today.
+3. Compute or read the markdown `content_hash`.
+4. Check the semantic markdown cache. Skip unchanged `(content_hash, model_id, prompt_version)` entries.
+5. Dispatch one `unit` Formation agent through `headless.js` with markdown content and existing structural Concept nodes.
+6. Validate output against the subagent contract and closed relation taxonomy.
+7. Merge proposed Concepts at project scope by normalized name.
+8. Persist new LLM semantic edges with `EdgeProvenance::Inferred(confidence)`.
+9. Record cache status only after validation and persistence complete.
+
+## Failure Handling
+
+- Invalid JSON: mark cache status `error`, persist no concepts or edges.
+- Unknown relation type: reject that edge and continue validating the rest.
+- Confidence outside range: clamp only if the value is numeric; reject missing or non-numeric confidence.
+- Duplicate semantic edge: keep the highest-confidence `Inferred(...)` edge for the same `(from, relation_type, to)` tuple, unless a future review layer wants history.
+- Structural duplicate edge: preserve structural output and drop the inferred duplicate.
+
+## Non-goals
+
+- PDF ingestion is explicitly excluded.
+- Image extraction is explicitly excluded.
+- Video extraction is explicitly excluded.
+- Audio extraction is explicitly excluded.
+- Implementation work is explicitly excluded; this document is only the design.
+- This design does not introduce a new Formation dispatch primitive.
+- This design does not modify the deterministic markdown parser.

package/core/dev/archive/ansuz/designs/task_1372_prompt_injects_into.md

@@ -0,0 +1,193 @@
+# TASK_1372 — PROMPT_INJECTS_INTO Edge Design Doc
+
+**Status**: Design ready for implementation
+**Author**: Ansuz (session xyz951610, 2026-04-22)
+**Target task**: TASK_1372
+
+## Goal
+
+Add a KuzuDB edge type to Synapse that tracks which **substrate files** flow into which **prompt-construction code paths**. This is the missing edge between Ansuz's cognitive substrate (`.kenaz/specialist/*.json`, `.synapse/*.json`, `memory.db`) and the prompt strings that ultimately reach the LLM. Prerequisite for TASK_1373 (static substrate-behavior mapping).
+
+## Schema change
+
+File: `dashboard/src-tauri/src/features/synapse/schema.rs`
+Insert after the `COGNITIVE_APPLIES_TO` block (~line 383).
+
+```rust
+// PROMPT_INJECTS_INTO (v21, TASK_1372):
+// File → Symbol edge capturing "this substrate file is read and injected
+// into this prompt-construction function". Source is a File (substrate
+// path like .kenaz/specialist/self_model.json); target is a Symbol
+// (the function that reads it into a prompt, e.g. phase-gate.js
+// enterPhase, muninn-watcher assembleBanner, headless.js buildAgentPrompt).
+//
+// Properties:
+//   injection_phase : where in the agent lifecycle this injection happens.
+//     Values: "phase_0_boot" | "turn_context" | "dispatch_prompt" | "kernel"
+//     | "muninn_observation" | "user_prompt_submit_hook"
+//   read_type       : how the file is consumed.
+//     Values: "full_content" (fs::read_to_string → inline)
+//            | "field_extraction" (parse JSON/YAML, extract named field)
+//            | "section" (read one section from markdown)
+//   extracted_field : when read_type=field_extraction, the field path
+//     (e.g. "blind_spots.B-002", "narrative", "dynamic_user_context"),
+//     else empty string.
+//   confidence      : 1.0 for AST-confirmed literal path reads; 0.6 for
+//     pattern matches where the path is a variable/template.
+//   t_created       : v18 bi-temporal tracking (when edge first appeared)
+//   commit_sha      : commit when edge was first observed
+conn.query(
+    "CREATE REL TABLE IF NOT EXISTS PROMPT_INJECTS_INTO(\
+        FROM File TO Symbol, \
+        injection_phase STRING, \
+        read_type STRING, \
+        extracted_field STRING, \
+        confidence DOUBLE, \
+        t_created TIMESTAMP, \
+        commit_sha STRING, \
+        MANY_MANY\
+    )",
+)
+.map_err(|e| format!("CREATE PROMPT_INJECTS_INTO rel failed: {e}"))?;
+```
+
+## INDEX_FEATURE_VERSION bump
+
+File: `dashboard/src-tauri/src/features/synapse/index.rs:241`
+
+```rust
+const INDEX_FEATURE_VERSION: u32 = 8;  // was 7 — bump for PROMPT_INJECTS_INTO
+```
+
+Also update the assertion in the test near line 3287-3289:
+```rust
+assert_eq!(INDEX_FEATURE_VERSION, 8);
+```
+
+Bumping forces full reindex on first open after this change lands. Document this in the commit message.
+
+## Extractor module (new)
+
+File: `dashboard/src-tauri/src/features/synapse/prompt_injection.rs` (NEW)
+
+Structure:
+```rust
+//! PROMPT_INJECTS_INTO edge extractor.
+//!
+//! Detects 3 patterns across JS and Rust:
+//!   (A) Direct file read: fs::read_to_string(PATH) or readFileSync(PATH)
+//!       where PATH matches a substrate glob.
+//!   (B) JSON/YAML parse after read: the read result is passed to
+//!       JSON.parse / serde_json::from_str / parseYAML.
+//!   (C) String interpolation of extracted value into a prompt template:
+//!       format!("... {} ...", substrate_field) / template literals.
+
+use std::path::Path;
+
+/// Substrate file globs we track.
+const SUBSTRATE_GLOBS: &[&str] = &[
+    ".kenaz/specialist/*.json",
+    ".kenaz/specialist/*.jsonl",
+    ".synapse/*.json",
+    ".synapse/reflex_neurons.json",
+    ".kenaz/experiments/**/*.md",
+    "~/.kenaz/user_profile.json",
+    ".specialist/Ansuz/**/*.yaml",
+    ".specialist/Ansuz/concepts/*.md",
+];
+
+/// Prompt-building files we scan. Conservative start list — broaden later.
+const PROMPT_BUILDER_FILES: &[&str] = &[
+    ".specialist/tools/phase-gate.js",
+    ".formation/tools/muninn-watcher.js",
+    ".formation/tools/headless.js",
+    ".specialist/tools/session.js",
+    ".specialist/tools/context-injection.js",
+    ".specialist/tools/reflex_executor.js",
+];
+
+pub struct PromptInjectionEdge {
+    pub file_path: String,          // substrate file
+    pub target_symbol_id: String,   // prompt-builder symbol
+    pub injection_phase: InjectionPhase,
+    pub read_type: ReadType,
+    pub extracted_field: String,
+    pub confidence: f64,
+}
+
+#[derive(Debug)]
+pub enum InjectionPhase { Phase0Boot, TurnContext, DispatchPrompt, Kernel, MuninnObservation, UserPromptSubmit }
+
+#[derive(Debug)]
+pub enum ReadType { FullContent, FieldExtraction, Section }
+
+/// Extract all PROMPT_INJECTS_INTO edges by scanning the prompt-builder files.
+pub fn extract_edges(project_root: &Path) -> Result<Vec<PromptInjectionEdge>, String> {
+    // For each file in PROMPT_BUILDER_FILES:
+    //   Parse with appropriate language parser (tree-sitter js / rust)
+    //   Walk AST looking for:
+    //     - call to fs.readFileSync / fs.promises.readFile / fs::read_to_string
+    //     - where argument is a string literal or path.join(...) with string components
+    //     - where resolved path matches any SUBSTRATE_GLOBS entry
+    //   Determine injection_phase from the enclosing function name / file path
+    //     - phase-gate.js → phase_0_boot
+    //     - muninn-watcher.js → muninn_observation
+    //     - headless.js → dispatch_prompt
+    //     - turn-context* → turn_context
+    //   Determine read_type:
+    //     - if result is immediately JSON.parse'd or serde::from_str'd → FieldExtraction
+    //     - if result is passed whole into template literal / format! → FullContent
+    //   Determine extracted_field:
+    //     - trace the JSON.parse result usage → which member accesses happen
+    //   Emit PromptInjectionEdge for each (substrate_file, enclosing_function) pair.
+    todo!()
+}
+```
+
+## Integration points
+
+### memory.rs — insert edges after extraction
+
+In the `run_full_index` path (index.rs, after symbol extraction completes):
+1. Call `prompt_injection::extract_edges(project_root)`
+2. For each edge, `INSERT INTO PROMPT_INJECTS_INTO VALUES (...)` via the KuzuDB conn.
+
+Pattern to copy: look at how DATA_FLOWS edges are inserted. They follow the same shape — after symbol+call extraction, a separate pass inserts the typed edge.
+
+### context.rs — expose via synapse_context
+
+When `synapse_context` is called on a symbol:
+- If the symbol is a prompt-builder function → include injected substrates in the response under a new field `prompt_injections: [{file_path, injection_phase, extracted_field}]`
+- If the symbol is a File node with substrate path → include downstream prompts under `prompt_consumers`
+
+Look at how `extends` and `implements` are returned by the existing context path — same pattern, additive.
+
+## Testing
+
+1. After schema bump, run one full reindex and check:
+   `synapse_cypher "MATCH ()-[r:PROMPT_INJECTS_INTO]->() RETURN count(r)"` returns >= 10
+2. Check self_model.json is linked:
+   `synapse_cypher "MATCH (f:File {path: '.kenaz/specialist/ansuz_self_model.json'})-[r:PROMPT_INJECTS_INTO]->(s:Symbol) RETURN s.name, r.injection_phase"` returns at least one row naming phase-gate's enterPhase.
+
+## Risks / open questions
+
+1. **JavaScript support in scanner**: scanner.rs' primary language set includes Rust/TypeScript/Python. Verify .js files produce symbols. If not, the prompt-builder symbols won't exist to target with PROMPT_INJECTS_INTO. Fallback: store target as a File-level edge or materialize synthetic Symbol nodes for the JS functions.
+2. **Path resolution**: substrate paths in code are often joined from variables (`path.join(projectPath, '.kenaz/specialist/', fileName)`). Conservative extractor misses these. Start with literal-string matches only; tag confidence=1.0; accept coverage gaps for v1.
+3. **False positives**: not every `fs::read_to_string` of a JSON file is prompt-injection. Filter to only reads inside the PROMPT_BUILDER_FILES whitelist. False negatives are preferable to false positives for this edge — substrate-behavior mapping needs trustworthy data.
+4. **Migration cost**: INDEX_FEATURE_VERSION bump forces full reindex. KenazAI full index takes ~10-15 min. Plan deployment around a quiet window.
+
+## Dependencies
+
+- No upstream task dependencies.
+- Blocks: TASK_1373 (static substrate-behavior mapping) — do not start 1373 until this lands + reindex verified.
+
+## Estimated effort
+
+- Schema change + INDEX_FEATURE_VERSION bump: 30 min
+- prompt_injection.rs extractor (pattern A only, literal strings): 2-3 hours
+- memory.rs integration: 1 hour
+- context.rs integration: 1 hour
+- Full reindex + verification: 30 min
+- **Total v1 (pattern A only)**: ~5 hours
+
+Pattern B/C (JSON parse tracking, field extraction) deferred to a v2 task once v1 proves the graph is useful.

package/core/dev/archive/ansuz/designs/thought_stack.md

@@ -0,0 +1,286 @@
+# Thought Stack
+
+Status: proposed tactical memory primitive
+Owner: Ansuz
+Related: `.specialist/Ansuz/concepts/commitment_layer.yaml`
+
+## Purpose
+
+Ansuz currently has:
+
+- `ansuz_session_handoff` / ISBAR: a single-slot fatigue handoff for preserving the current session's minimum viable continuity.
+- `commitment_layer`: a user-ratified, cross-session strategic layer for commitments that survive across days to weeks.
+
+Missing is a tactical interrupt memory for thoughts that matter right now but do not deserve strategic commitment. This design introduces a small LIFO thought stack for minutes-to-hours continuity: "remember this before you commit to the next move", "circle back after current subtask", "when TASK_1330 completes, clear this tactical reminder".
+
+The design goal is to fill the tactical gap without duplicating `commitment_layer`. Thought Stack is private, tactical, and disposable. `commitment_layer` is strategic, visible, and user-ratified.
+
+## Granularity Boundary
+
+| Layer | Time scale | Capacity | Author | Typical content | Persistence model |
+| --- | --- | --- | --- | --- | --- |
+| ISBAR / `ansuz_session_handoff` | current session, fatigue edge | single slot | automatic capture | "what is happening right now?" | overwrite-on-next-handoff |
+| Thought Stack | minutes to hours, one task or nearby tasks | max 5 thoughts, LIFO | explicit push/pop by Ansuz tools or lifecycle hooks | "after this branch, verify X", "do not forget Y before completing TASK_1330" | tactical, auto-expiring |
+| `commitment_layer` | days to weeks, cross-session push | multiple commitments | Ansuz draft + user ratification | recurring strategic pushes, unresolved multi-session intent | durable until completed/abandoned |
+
+Rule: if a thought would still matter after 7 days, or requires user witnessing to become real, it does not belong in Thought Stack. It should become a draft or ratified item in `commitment_layer.yaml`.
+
+## File Schema
+
+Canonical file: `.kenaz/specialist/ansuz_thoughts_stack.json`
+
+```json
+{
+  "schema_version": 1,
+  "specialist": "Ansuz",
+  "stack": [
+    {
+      "id": "TH-20260421-001",
+      "text": "Before committing the design, verify Phase 0 precedence against ISBAR and commitment_layer.",
+      "context": "TASK_1330 tactical design pass",
+      "project": "KenazAI",
+      "related_task_id": "TASK_1330",
+      "created_at": "2026-04-21T10:30:00Z",
+      "expires_at": "2026-04-28T10:30:00Z"
+    }
+  ]
+}
+```
+
+### Thought Object Contract
+
+- `id`: unique stable thought id. Recommended format: `TH-{UTC compact timestamp}-{3-digit counter}`.
+- `text`: required tactical reminder text. Keep under 240 characters. One actionable thought, not a paragraph.
+- `context`: optional short source context. Example: current phase, file, or subproblem.
+- `project`: optional project identifier. Required when the same specialist may operate across projects; otherwise may be omitted and inferred from active project.
+- `related_task_id`: optional task anchor. Used by task lifecycle hooks for automatic resolution.
+- `created_at`: required ISO-8601 UTC timestamp.
+- `expires_at`: required ISO-8601 UTC timestamp, default `created_at + 7 days`.
+
+### Stack Invariants
+
+- `schema_version` must exist and be integer `1` for v1.
+- `stack` is ordered oldest -> newest in storage.
+- The logical top of stack is the last element in `stack`.
+- Maximum stack size is 5 thoughts.
+- Thoughts are specialist-local, not shared across specialists.
+- Expired thoughts are removed before any read or write result is returned.
+
+## MCP Tool Surface
+
+Three new MCP tools expose the primitive.
+
+### `thought_push`
+
+Signature:
+
+```ts
+thought_push(
+  text: string,
+  context?: string,
+  related_task_id?: string
+) => { id: string }
+```
+
+Behavior:
+
+- Validates non-empty `text`.
+- Creates a thought object with generated `id`, inferred `project`, `created_at = now`, and `expires_at = now + 7 days`.
+- Appends to the top of the stack.
+- Runs expiry sweep before append.
+- If append would exceed 5 items, drop the oldest surviving thought before write.
+- Returns the new thought `id`.
+
+### `thought_pop`
+
+Signature:
+
+```ts
+thought_pop(id?: string) => {
+  thought: {
+    id: string,
+    text: string,
+    context?: string,
+    project?: string,
+    related_task_id?: string,
+    created_at: string,
+    expires_at: string
+  } | null
+}
+```
+
+Behavior:
+
+- Runs expiry sweep first.
+- `thought_pop()` with no `id` pops the top-most live thought (LIFO).
+- `thought_pop(id)` removes the matching live thought from anywhere in the stack and returns it.
+- Returns `null` if no matching live thought exists.
+- Primary use cases:
+  - implicit top-of-stack tactical recall;
+  - task completion hook removal by `related_task_id`;
+  - explicit dismissal of a stale tactical reminder.
+
+### `thought_stack_list`
+
+Signature:
+
+```ts
+thought_stack_list() => {
+  schema_version: number,
+  stack: Array<{
+    id: string,
+    text: string,
+    context?: string,
+    project?: string,
+    related_task_id?: string,
+    created_at: string,
+    expires_at: string
+  }>
+}
+```
+
+Behavior:
+
+- Runs expiry sweep first.
+- Returns the persisted stack in storage order oldest -> newest.
+- Consumers that need the next tactical item should read the last element, not the first.
+
+## Phase 0 Integration
+
+Thought Stack ranks between ISBAR and `commitment_layer`.
+
+### Precedence Rule
+
+When both ISBAR and Thought Stack are present:
+
+1. ISBAR is shown first because it answers the emergency continuity question: "what was I doing when the session degraded or paused?"
+2. Thought Stack is shown second because it contains tactical interrupts that may change the immediate next action once baseline continuity is restored.
+3. `commitment_layer` appears after Thought Stack because it shapes agenda across sessions, not the first tactical move inside the resumed session.
+
+This yields:
+
+1. Recover minimum session state from ISBAR.
+2. Apply tactical interrupts from Thought Stack.
+3. Re-anchor longer-horizon intent from `commitment_layer`.
+
+### Coexistence Model
+
+- ISBAR remains single-slot and loss-tolerant. Thought Stack does not replace or expand ISBAR.
+- Thought Stack is not auto-generated from fatigue capture. It must be intentionally pushed by Ansuz or by explicit lifecycle hook.
+- `commitment_layer` remains the place for durable, user-ratified commitments. Thoughts do not require ratification and should not surface as commitments unless they recur or survive beyond tactical horizon.
+- A thought may escalate into `commitment_layer` only after repeated re-push, repeated expiry without resolution, or evidence that it spans days/weeks rather than hours.
+
+### Suggested Phase 0 Rendering
+
+```text
+ISBAR
+- {single session handoff}
+
+Thought Stack
+- [top] {newest tactical thought}
+- [older] {previous tactical thought}
+
+Commitment Layer
+- {active or draft commitments}
+```
+
+If the stack is empty after expiry sweep, Thought Stack is omitted entirely from the preamble.
+
+## Task Completion Hook Contract
+
+The task API complete path gets a tactical cleanup hook.
+
+### Contract
+
+On `task-api complete TASK_xxx`:
+
+1. Emit `task_completed` event with payload:
+
+```json
+{
+  "task_id": "TASK_1330",
+  "completed_at": "2026-04-21T11:00:00Z",
+  "source": "task-api.complete"
+}
+```
+
+2. Load `.kenaz/specialist/ansuz_thoughts_stack.json`.
+3. Sweep expired thoughts.
+4. Auto-pop every thought whose `related_task_id == completed task id`.
+5. Persist the stack after removals.
+6. Emit a follow-up completion-cleanup event summarizing removed thoughts.
+
+### Cleanup Event Shape
+
+```json
+{
+  "event": "thought_stack.auto_pop",
+  "task_id": "TASK_1330",
+  "removed_ids": ["TH-20260421-001"],
+  "removed_count": 1,
+  "completed_at": "2026-04-21T11:00:00Z"
+}
+```
+
+### Semantics
+
+- Auto-pop is many-match, not single-match. A task may own multiple tactical reminders.
+- Matching is by exact `related_task_id`.
+- Cleanup is best-effort and should not fail task completion if the stack file is missing or malformed. The completion path should log the cleanup error and continue.
+- This specifically closes the B-001 parent-task-lifecycle gap: tactical reminders anchored to a task must disappear when that task is explicitly completed.
+
+## Expiry, Ceiling, and Overflow Policy
+
+### Expiry
+
+- Default TTL: 7 days from `created_at`.
+- Expiry is lazy: executed before every list, push, or pop.
+- Expired thoughts are deleted silently; they are reminders, not archival records.
+
+### Ceiling
+
+- Maximum 5 live thoughts after expiry sweep.
+- Limit is per specialist stack file, not per task.
+
+### Overflow
+
+- On push, if the live stack is already at 5, drop the oldest item before appending the new thought.
+- Overflow policy is FIFO-drop-oldest, even though access semantics are LIFO. This preserves the newest tactical interrupts and sacrifices the stalest reminder first.
+- Optional implementation detail: emit an overflow diagnostic event for observability, but do not block the push.
+
+## Operational Examples
+
+### Example: explicit tactical interrupt
+
+Ansuz notices a side concern during design work:
+
+```ts
+thought_push(
+  "Before finalizing, verify task completion auto-pop does not collide with plain top-of-stack pop.",
+  "design review",
+  "TASK_1330"
+)
+```
+
+Later, after returning to the main flow, `thought_pop()` retrieves the newest unresolved reminder.
+
+### Example: task completion cleanup
+
+If the stack contains three thoughts and two carry `related_task_id: "TASK_1330"`, then completing `TASK_1330` removes both in one pass and leaves unrelated tactical thoughts untouched.
+
+## Non-Goals
+
+- No user-ratification flow. That belongs to `commitment_layer`.
+- No long-term archive or audit log. Expired or popped thoughts are disposable.
+- No priority scoring. LIFO order is sufficient for v1.
+- No cross-specialist sharing. This is Ansuz-local tactical memory.
+
+## Design Summary
+
+Thought Stack is a narrow tactical primitive:
+
+- more structured than ad hoc session text,
+- lighter and shorter-lived than `commitment_layer`,
+- safer than overloading ISBAR with multiple pending interrupts.
+
+Its role is to preserve the next few tactical reminders until they are popped, auto-resolved by `related_task_id`, or allowed to expire.