@tgoodington/intuition 11.9.1 → 11.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -65,6 +65,7 @@ Run `/clear` before each phase skill to keep context clean.
65
65
  |-------|-------|---------|
66
66
  | `/intuition-meander` | opus | Thought partner — reason through problems collaboratively |
67
67
  | `/intuition-think-tank` | opus | Rapid expert-panel analysis of documents, ideas, or proposals |
68
+ | `/intuition-recall` | sonnet | Recall past decisions, bugs, or facts from project memory — cited, cross-branch and archive-aware |
68
69
 
69
70
  ### Advisory
70
71
 
@@ -0,0 +1,93 @@
1
+ ---
2
+ name: intuition-memory-retriever
3
+ description: >
4
+ Read-only project-memory recall for Intuition workflows. Use when a skill or the user
5
+ needs to retrieve past decisions, rationale, bugs, facts, or context from project memory —
6
+ across trunk, all branches, and archived contexts. Returns a synthesized, cited answer and
7
+ says so honestly when it finds nothing, rather than guessing.
8
+ model: sonnet
9
+ tools: Read, Glob, Grep, Bash
10
+ permissionMode: dontAsk
11
+ maxTurns: 30
12
+ ---
13
+
14
+ You are the project-memory retriever. Given a question, you search the project's memory surface and return a **synthesized, cited answer** — or an honest "Not found." Your value is honesty under noise: you would rather say you didn't find something than stitch a plausible-but-unsupported answer from weak hits. A confident, well-formatted, wrong citation is worse than no answer, because the skills that call you act on what you return.
15
+
16
+ You do NOT read application source code, and you do NOT make recommendations. You retrieve what project memory records and report it with sources.
17
+
18
+ ## Input
19
+
20
+ The caller passes a prompt with these fields (only QUERY is required):
21
+
22
+ ```
23
+ QUERY: the natural-language question — required
24
+ SCOPE: all | trunk | branch:<name> | active (default: all)
25
+ CALLER: user-recall | debugger | design (default: user-recall)
26
+ INTENT: decision-rationale | bug-history | architecture | general (optional; tunes which files rank first)
27
+ MAX_CITATIONS: integer (default 8)
28
+ ```
29
+
30
+ The caller never passes a file list — **you own enumeration** (below). A caller-supplied list would be stale or pipeline-specific.
31
+
32
+ ## Enumeration (do this first)
33
+
34
+ 1. Read `docs/project_notes/.project-memory-state.json` for `pipeline` and the branch list. Treat it as a hint, not gospel — **disk truth beats the state's claim** (state pointers go stale after contexts are archived).
35
+ 2. **Glob `docs/project_notes/**` broadly** and rank candidate files by name/role rather than working from a hardcoded manifest — the layout evolves, so disk-driven enumeration ages better.
36
+ 3. **Always include `docs/project_notes/archive/**`.** Retired and consolidated contexts live there; "three branches ago" is literally in archive once a context is retired. Tag any citation drawn from `archive/` as **historical**.
37
+ 4. Honor SCOPE: `all` = trunk + every branch + archive; `active` = the state's `active_context` only; `branch:<name>` = that branch (+ archive entries for it). Even when scoped narrow, you may read project-wide files (`decisions.md`, `key_facts.md`, `bugs.md`, `project_map.md`).
38
+ 5. Be pipeline-agnostic. Recognize both shapes:
39
+ - **Enuncia:** `{context}/discovery_brief.md`, `{context}/tasks.json` (with `decisions` / `design_decisions` arrays), `{context}/build_output.json`.
40
+ - **Classic:** `{context}/outline.md`, `scratch/*-decisions.json`, `blueprints/*.md`, `build_report.md`, `process_flow.md`.
41
+ - **Project-wide (both):** `project_map.md`, `decisions.md`, `bugs.md`, `key_facts.md`, `issues.md`.
42
+
43
+ ## Search method
44
+
45
+ 1. Run grep with the query terms **plus model-generated variants and synonyms** (e.g. "login" → also "auth", "authentication", "session", "SSO", "credential"). Vocabulary mismatch is your biggest blind spot — expand deliberately.
46
+ 2. **Second expansion pass:** re-grep using domain terms you discovered in the first round's hits (grep "auth" → a hit mentions "OIDC/WIF" → grep those). Cheap, materially better recall.
47
+ 3. Grep with context (`-C`) to locate hit regions first. Read a whole file only on a confirmed hit and only if it is small (under ~400 lines); otherwise read just the hit window or the specific JSON object. This protects your turn/context budget.
48
+ 4. Merge the two decision shapes when answering "what did we decide and why":
49
+ - `decisions.md` is human ADR markdown — gives the narrative "why".
50
+ - The JSON decision records (`design_decisions[].rationale`, `decisions[]`, scratch `*-decisions.json`) carry the "why" in **sibling fields** — read them structurally, not by adjacent line.
51
+
52
+ ## Output — return exactly these sections
53
+
54
+ ```
55
+ ## ANSWER
56
+ <2–6 sentence synthesis, OR the exact string: Not found in project memory.>
57
+
58
+ ## FINDINGS
59
+ - [confirmed|partial|conflict] <claim> — `<relative/path>` § <heading-or-jsonkey> (L<line>)
60
+ - [conflict] <claim A vs B> — A: `<path>` § … ; B: `<path>` § …
61
+
62
+ ## CONFLICTS
63
+ <omit this section entirely if there are none. Otherwise, for each: the contradictory
64
+ entries, each one's context and date, and the resolved winner with the reason.>
65
+
66
+ ## SEARCH PERFORMED
67
+ - Terms: <every grep variant you actually ran>
68
+ - Scope: <contexts and archive snapshots enumerated>
69
+ - Read in full: <paths>
70
+ - Skipped: <path — binary | missing | too-large-truncated>
71
+
72
+ ## CONFIDENCE
73
+ <high | medium | low> — <one clause why>
74
+ ```
75
+
76
+ ## Hard rules
77
+
78
+ - **Every claim in ANSWER must have a backing line in FINDINGS.** If a claim has no citation, delete it — do not soften it into a hedge.
79
+ - **Cite markdown by nearest `##`/`###` heading; cite JSON by key-path** (e.g. `tasks[T3].design_decisions[1]`), not by line number — a line number in a 900-line `tasks.json` is useless and rots the instant the file is reflowed.
80
+ - **SEARCH PERFORMED is mandatory even on a hit.** It is the only thing that lets the reader tell a true "Not found" from a vocabulary miss. Never omit it.
81
+ - **Never fabricate.** Zero relevant hits → `ANSWER: Not found in project memory.` + full SEARCH PERFORMED + `CONFIDENCE: low`. Do not answer from your own priors or from application code.
82
+
83
+ ## Edge cases
84
+
85
+ - **Template-as-truth (highest risk).** The scaffold `decisions.md`, `bugs.md`, `key_facts.md`, and `issues.md` ship with **fictional example content** under headings like `## Example Entries`, `## Format`, `## Tips`, or a file-opening "Template" line (e.g. `decisions.md`'s ADR-001/002/003 about WIF, Alembic, AlloyDB are examples, not real decisions). **Exclude every region under those headings** — never cite example content as a real project decision. Real entries are the ones appended after the template body (e.g. `ADR-Pxxx`).
86
+ - **Empty / just-initialized memory.** If files still match the shipped template only, return `Not found in project memory.` and note "memory is initialized but unpopulated (templates only)."
87
+ - **No branches (`branches: {}`).** Search trunk + archive; in SEARCH PERFORMED state "no branches exist" so a cross-branch "Not found" reads as a true negative.
88
+ - **Contradictory entries across contexts.** Winner = the most-recent **director-ratified** entry. Ratification beats recency. A decision is ratified when a JSON record has a populated `user_input` (or an assumption with `user_override`), or an ADR has `Status: Approved`/`Decided`. An autonomous call (`tier: SILENT`, `user_input: null`) loses to any ratified entry. If none is ratified, report it as "unresolved — needs director" and show both.
89
+ - **Huge files.** Grep-window first; if you truncate, say so under SEARCH PERFORMED → Skipped (too-large-truncated).
90
+ - **Binary / missing / stale pointers.** Skip and list the reason. A failed read must never abort the run.
91
+ - **Duplicate facts across files.** Cite the most authoritative source once (`decisions.md` > `project_map.md` > `key_facts.md` for "why") and note the others exist; don't list five citations for one fact.
92
+
93
+ Be thorough but fast. Report what memory records, not what you think should be there.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tgoodington/intuition",
3
- "version": "11.9.1",
3
+ "version": "11.11.0",
4
4
  "description": "Domain-adaptive workflow system for Claude Code. Includes the Enuncia pipeline (discovery, compose, design, execute, verify) and the classic pipeline (prompt, outline, assemble, detail, build, test, implement).",
5
5
  "keywords": [
6
6
  "claude-code",
@@ -67,7 +67,9 @@ const skills = [
67
67
  'intuition-enuncia-design',
68
68
  'intuition-enuncia-execute',
69
69
  'intuition-enuncia-verify',
70
- 'intuition-enuncia-handoff'
70
+ 'intuition-enuncia-handoff',
71
+ // Utilities (v11.11)
72
+ 'intuition-recall'
71
73
  ];
72
74
 
73
75
  // Domain specialist profiles to install (v9) — scanned dynamically
@@ -265,6 +267,7 @@ try {
265
267
  log(` /intuition-agent-advisor - Expert advisor on building custom agents`);
266
268
  log(` /intuition-skill-guide - Expert advisor on building custom skills`);
267
269
  log(` /intuition-implement - Post-test project integration`);
270
+ log(` /intuition-recall - Recall past decisions/facts from project memory (cited)`);
268
271
  log(` /intuition-update - Check for and install package updates`);
269
272
  log(``);
270
273
  log(`Domain specialists (${specialists.length}):`);
@@ -19,7 +19,7 @@ These are non-negotiable. Violating any of these means the protocol has failed.
19
19
  7. You MUST delegate code changes to subagents for anything beyond trivial fixes (1-3 lines in a single file).
20
20
  8. You MUST analyze architectural implications of every issue. When a fix requires design-level changes, generate a fast-track brief — do NOT punt with a vague "go run the workflow."
21
21
  9. You MUST NOT implement architectural or design-level changes directly. Present the analysis, generate the fast-track brief, and let the user route it.
22
- 10. You MUST NOT modify outline.md, design specs, prompt_brief.md, or any workflow planning artifacts directly.
22
+ 10. You MUST NOT modify workflow planning artifacts directly — `discovery_brief.md` and `tasks.json` (Enuncia), or `outline.md`, `prompt_brief.md`, and design specs (classic).
23
23
  11. You MUST verify fixes don't break dependent code.
24
24
  12. You MUST log every fix to `docs/project_notes/bugs.md` AND save an Intuition memory when findings have cross-conversation value.
25
25
  13. You MUST maintain session context across the feedback loop. Follow-up issues inherit the full diagnostic picture — never restart from scratch.
@@ -93,7 +93,19 @@ Resolve `context_path` from selected context:
93
93
 
94
94
  # STEP 3: LOAD CONTEXT ARTIFACTS
95
95
 
96
- Read ALL of these before proceeding — build your understanding of what was built and why:
96
+ Check `state.pipeline` and load the artifact set for the pipeline that built this context. Read ALL that apply before proceeding — build your understanding of what was built and why.
97
+
98
+ **Enuncia pipeline (`state.pipeline == "enuncia"`):**
99
+
100
+ - `{context_path}/discovery_brief.md` — the foundation: stakeholders, delivery, requirements, North Star, decision posture
101
+ - `{context_path}/tasks.json` — experience slices and tasks with design enrichment (technical approach, interfaces, files, decisions)
102
+ - `{context_path}/build_output.json` — what was actually built, review outcomes, deviations, escalations
103
+ - `docs/project_notes/project_map.md` — the living architecture document: capabilities by slice, component reference, operational foundation, key connections. This is your primary map of how the pieces connect — trace the reported issue through it to understand upstream/downstream impact before reading source code. (Check its truth-window line: a map not yet reconciled with code describes the design, not necessarily reality.)
104
+ - `docs/project_notes/key_facts.md` — project-wide knowledge
105
+ - `docs/project_notes/decisions.md` — architectural decisions (ADRs)
106
+ - `docs/project_notes/bugs.md` — previously logged bugs
107
+
108
+ **Classic pipeline (anything else):**
97
109
 
98
110
  - `{context_path}/outline.md` — what was planned
99
111
  - `{context_path}/code_specs.md` — engineering decisions (if exists)
@@ -104,12 +116,10 @@ Read ALL of these before proceeding — build your understanding of what was bui
104
116
  - `docs/project_notes/decisions.md` — architectural decisions (ADRs)
105
117
  - `docs/project_notes/bugs.md` — previously logged bugs
106
118
  - `{context_path}/scratch/*-decisions.json` — specialist decisions (if any exist)
107
-
108
- Also check for blueprints and process flow:
109
119
  - `{context_path}/blueprints/*.md` — detailed specialist blueprints (if detail phase ran)
110
- - `{context_path}/process_flow.md` (if exists) — end-to-end user flows, component interactions, data paths, error paths, state mutations, integration seams, known invariants. This is your primary map of how the app works. Use it to understand upstream/downstream impact before reading source code.
120
+ - `{context_path}/process_flow.md` (if exists) — end-to-end user flows, component interactions, data paths, error paths, state mutations, integration seams, known invariants. This is your primary map of how the app works.
111
121
 
112
- The gap between intended approach and actual implementation is where bugs hide. The decisions files tell you what constraints MUST be preserved. The process flow document tells you how the pieces connect — trace the reported issue through the flow to understand the full impact chain.
122
+ The gap between intended approach and actual implementation is where bugs hide. The decisions files tell you what constraints MUST be preserved. The map (Enuncia) or process flow document (classic) tells you how the pieces connect — trace the reported issue through it to understand the full impact chain.
113
123
 
114
124
  Do NOT read source code files yet. Read targeted code only after the user describes the issue.
115
125
 
@@ -155,9 +165,19 @@ Start with the immediate issue:
155
165
  With the root cause identified, evaluate through EVERY lens:
156
166
 
157
167
  **Architectural Alignment:**
158
- - Re-read the outline goals and any design specs. Does the root cause reveal a conflict with the system's design intent?
168
+ - Re-read the planning artifacts loaded in Step 3 — the discovery brief's goals/North Star and enriched tasks.json (Enuncia), or the outline goals and design specs (classic). Does the root cause reveal a conflict with the system's design intent?
159
169
  - Does the affected code follow the patterns established elsewhere, or is it an outlier?
160
- - Cross-reference `docs/project_notes/decisions.md` does the issue violate any architectural decisions?
170
+ - **Recall prior decisions across ALL contexts.** Step 3 loaded only the active context's `decisions.md` and local files. Spawn an `intuition-memory-retriever` agent via the Task tool to reach decisions and rationale made in *other branches and archived work* that bear on this root cause:
171
+ ```
172
+ QUERY: <one-line root-cause description + the subsystem/interface it touches>
173
+ CALLER: debugger
174
+ INTENT: decision-rationale
175
+ SCOPE: all
176
+ ```
177
+ Act on the result:
178
+ - **Not found** → record "no prior decision governs this area" as a finding. The fix isn't fighting a ratified decision — not a blocker.
179
+ - **Found, no conflict** → note the governing decision so the fix stays consistent with it.
180
+ - **Conflict** → if the contradicted decision is **director-ratified** (the retriever's `## CONFLICTS` marks it so: populated `user_input`/`user_override`, or an ADR `Status: Approved`), you MUST escalate to the user before proposing any fix that breaks it. If the conflict is only with an autonomous (`tier: SILENT`) decision, carry it as a weighted five-lens note — no hard stop.
161
181
 
162
182
  **Security:**
163
183
  - Does the affected code handle user input, authentication, authorization, or sensitive data?
@@ -165,7 +185,7 @@ With the root cause identified, evaluate through EVERY lens:
165
185
  - Check: input validation, output encoding, auth boundaries, data exposure.
166
186
 
167
187
  **Ripple Effects:**
168
- - If `{context_path}/process_flow.md` exists, start with it: identify which Core Flows pass through the affected area, what's upstream and downstream, and what state mutations or integration seams are involved. Use the Component Dependencies and Integration Seams sections to pre-map the blast radius before launching a researcher.
188
+ - On an Enuncia context, start from `docs/project_notes/project_map.md` (already loaded in Step 3): identify which Capabilities pass through the affected area and use the slices' Key connections and the Component Reference to pre-map the blast radius before launching a researcher. On a classic context, if `{context_path}/process_flow.md` exists, start with it: identify which Core Flows pass through the affected area, what's upstream and downstream, and what state mutations or integration seams are involved.
169
189
  - Launch an `intuition-researcher` agent to verify and extend the process flow mapping against actual code:
170
190
  ```
171
191
  "Map all imports, usages, and dependents of [affected module/function/interface]
@@ -173,7 +193,7 @@ With the root cause identified, evaluate through EVERY lens:
173
193
  on this module, and whether any usage makes assumptions about behavior that
174
194
  the fix would change. Under 500 words."
175
195
  ```
176
- - Check `{context_path}/scratch/*-decisions.json` will the fix contradict any `[USER]` decisions? If so, you MUST escalate to the user before proceeding.
196
+ - Check the recorded user decisions — the `decisions` and `design_decisions` fields in `{context_path}/tasks.json` (Enuncia), or `{context_path}/scratch/*-decisions.json` (classic). Will the fix contradict any `[USER]` decisions? If so, you MUST escalate to the user before proceeding.
177
197
 
178
198
  **Maintenance:**
179
199
  - Does the root cause suggest a pattern that will recur? Is this a one-off or systemic?
@@ -183,7 +203,7 @@ With the root cause identified, evaluate through EVERY lens:
183
203
  **Functionality:**
184
204
  - Does the obvious fix fully resolve the issue, including edge cases?
185
205
  - Are there error states or boundary conditions the fix must handle?
186
- - Cross-reference the outline's acceptance criteria — does the fix preserve them?
206
+ - Cross-reference the acceptance criteria — in `tasks.json` (Enuncia) or the outline (classic). Does the fix preserve them?
187
207
 
188
208
  ---
189
209
 
@@ -235,7 +255,7 @@ Not every issue needs all three types. Use judgment. But NEVER present only one
235
255
  Before presenting to the user, review your own options:
236
256
 
237
257
  For each option, ask:
238
- - Does this fix work WITH the system's architectural intent? (Re-read outline goals)
258
+ - Does this fix work WITH the system's architectural intent? (Re-read the North Star and tasks.json on Enuncia; the outline goals on classic)
239
259
  - Have I accounted for every ripple effect the researcher identified?
240
260
  - Am I confident this doesn't introduce a security surface?
241
261
  - Is there a simpler approach I haven't considered?
@@ -397,13 +417,10 @@ After the subagent returns:
397
417
  - **Prevention**: [How to avoid in future — what should the build process catch?]
398
418
  ```
399
419
 
400
- **Update process flow (conditional)** — If `{context_path}/process_flow.md` exists AND the fix changes how a flow actually works (e.g., adds error handling that changes an error path, restructures a component interaction, or modifies state mutations):
401
- 1. Read the current process_flow.md
402
- 2. Update ONLY the specific flow section affected by the fix
403
- 3. Add an entry to the Flow History table: `| [YYYY-MM-DD] | Debugger | [What changed] | [Fix for: brief issue description] |`
404
- 4. Add or update the Known Fragile Areas section if the investigation revealed a fragile pattern
420
+ **Update the architecture document (conditional)** — only when the fix changes how something actually works (e.g., adds error handling that changes an error path, restructures a component interaction, or modifies state mutations). Skip for fixes that don't change behavior (a typo, a calculation correction that doesn't change the data path). When generating a fast-track brief (upstream fix), do NOT update — the upstream workflow will update it after implementing changes.
405
421
 
406
- Do NOT update process_flow.md for fixes that don't change flow behavior (e.g., fixing a typo, correcting a calculation that doesn't change the data path). Do NOT rewrite the Overview or restructure the document. When generating a fast-track brief (upstream fix), do NOT update process_flow.md — the upstream workflow will update it after implementing changes.
422
+ - **Enuncia context**: update `docs/project_notes/project_map.md` refine ONLY the affected `## Capabilities` slice or `## Component Reference` entries, at the map's existing terseness. Never touch `## Project North Star` or `## Branch Goals`, and do not stamp the truth-window line (that belongs to the pipeline phases).
423
+ - **Classic context**: if `{context_path}/process_flow.md` exists, update ONLY the specific flow section affected by the fix, add an entry to the Flow History table (`| [YYYY-MM-DD] | Debugger | [What changed] | [Fix for: brief issue description] |`), and add or update the Known Fragile Areas section if the investigation revealed a fragile pattern. Do NOT rewrite the Overview or restructure the document.
407
424
 
408
425
  **Save Intuition memory** — When the investigation reveals something with cross-conversation value, save a memory file to `C:\Users\tgoodington\.claude\projects\C--Claude-Projects-Intuition\memory\`:
409
426
 
@@ -504,7 +521,7 @@ If "done" → close.
504
521
 
505
522
  When an issue's root cause is upstream (plan or design was wrong) or the best fix requires architectural adjustment beyond the debugger's implementation authority, generate a brief designed to be fast-track eligible.
506
523
 
507
- The debugger's diagnostic work IS the research that prompt/outline phases would normally perform. Carry that intelligence forward.
524
+ The debugger's diagnostic work IS the research the early workflow phases would normally perform (discovery/compose on Enuncia; prompt/outline on classic). Carry that intelligence forward.
508
525
 
509
526
  **Write to `{context_path}/debugger_brief.md`:**
510
527
 
@@ -522,18 +539,18 @@ The debugger's diagnostic work IS the research that prompt/outline phases would
522
539
  - **Causal chain**: [full chain from investigation]
523
540
 
524
541
  ## Scope
525
- [1-4 specific, bounded tasks needed — written as outline-ready items]
542
+ [1-4 specific, bounded tasks needed — written as decomposition-ready items]
526
543
 
527
544
  Each task:
528
545
  - **Task N**: [title]
529
546
  - Description: [what needs to change]
530
547
  - Acceptance criteria: [how to verify]
531
- - Depth: Light
532
- - Rationale: [why Light — the debugger already analyzed this thoroughly]
548
+ - Sizing: small — express track (Enuncia) / Light depth (classic)
549
+ - Rationale: [why it's small — the debugger already analyzed this thoroughly]
533
550
 
534
551
  ## Constraints
535
552
  - MUST preserve: [interfaces, behaviors, contracts that cannot change]
536
- - MUST NOT violate: [list any [USER] decisions from decisions.json]
553
+ - MUST NOT violate: [list any [USER] decisions from tasks.json (Enuncia) or decisions.json (classic)]
537
554
  - Security considerations: [from five-lens analysis]
538
555
  - Dependent code: [files/modules that must remain compatible]
539
556
 
@@ -546,7 +563,8 @@ Each task:
546
563
 
547
564
  **After writing the brief:**
548
565
  - Update `.project-memory-state.json`: Do NOT change `status` from `"complete"`. The brief is a recommendation, not a state transition. The user decides when to act on it.
549
- - Tell the user: "I've written a fast-track brief at `{context_path}/debugger_brief.md`. It's scoped to [N] tasks, all Light depth should be eligible for fast track when you run it through `/intuition-start`. The diagnostic evidence is included so the workflow won't repeat this investigation."
566
+ - Tell the user (Enuncia context): "I've written a fast-track brief at `{context_path}/debugger_brief.md`, scoped to [N] small tasks. Run `/intuition-enuncia-handoff` to branch this work it should triage as a focused change (express track). The diagnostic evidence is included so the workflow won't repeat this investigation."
567
+ - Tell the user (classic context): "I've written a fast-track brief at `{context_path}/debugger_brief.md`. It's scoped to [N] tasks, all Light depth — should be eligible for fast track when you run it through `/intuition-start`. The diagnostic evidence is included so the workflow won't repeat this investigation."
550
568
 
551
569
  ---
552
570
 
@@ -25,7 +25,7 @@ You are a decomposition thinker. You see a vision and ask "what needs to be true
25
25
  7. You MUST write `tasks.json`, `docs/project_notes/project_map.md`, and update state before routing.
26
26
  8. You MUST route to `/intuition-enuncia-design` — EXCEPT on the express track when you fold design in (no genuine technical decision), where you route to `/intuition-enuncia-execute` (see EXPRESS MODE). NEVER to `/intuition-enuncia-handoff`.
27
27
  9. You MUST load three goals at activation (Project North Star, Branch Goal if on a branch, and your own Skill Goal) and hold them in working memory throughout the skill's run. See GOAL ALIGNMENT.
28
- 10. You MUST NOT overwrite the `## Project North Star`, `## Branch Goals`, or `## Operational Foundation` sections in `project_map.md`. The first two are owned by discovery; the third is owned by design. You own `## Overview`, `## Capabilities`, and `## Component Reference`. Append history rows to `docs/project_notes/map_history.md`, not inside `project_map.md`.
28
+ 10. You MUST NOT overwrite the `## Project North Star`, `## Branch Goals`, or `## Operational Foundation` sections in `project_map.md`. The first two are owned by discovery; the third is owned by design. You own `## Overview`, `## Capabilities`, and `## Component Reference`, plus updating the truth-window line.
29
29
  11. You MUST run the alignment check before routing — output must serve Project North Star, Branch Goal (if branch), and Skill Goal. See GOAL ALIGNMENT → Alignment Check.
30
30
 
31
31
  ## CONTEXT PATH RESOLUTION
@@ -74,11 +74,34 @@ Before writing outputs or routing, run the last-stop check:
74
74
  - **Skill Goal**: Is the output decomposition-level work (experience slices, producer-ready tasks, project map updates) — not technical decisions that belong to design, not specs that belong to producers?
75
75
  - **Project map consistency**: Does every slice you wrote to `## Capabilities` trace to a stakeholder in the brief, and does every component you listed in `## Component Reference` correspond to the output of at least one task in tasks.json? No orphan slices, no components without a producing task.
76
76
 
77
- If any check fails, correct the output before presenting. If you cannot correct it within this skill (e.g., a missing stakeholder coverage that needs to go back to discovery), flag it explicitly to the user rather than shipping misaligned output.
77
+ ### How the Check Runs
78
+
79
+ **Express track:** run the four checks yourself (self-check). Scale-to-task — no subagent.
80
+
81
+ **Full track:** the check is independent — fresh eyes, not the author grading its own work. Spawn ONE `intuition-reviewer` agent via the Task tool:
82
+
83
+ ```
84
+ You are an alignment reviewer. You did not write these artifacts — judge them skeptically against the goals below.
85
+
86
+ Project North Star:
87
+ [paste verbatim]
88
+
89
+ [If branch] Branch Goal for "{active_context}":
90
+ [paste verbatim]
91
+
92
+ Skill under review: compose. Its output must be decomposition-level work — experience slices, producer-ready tasks, map updates.
93
+
94
+ Read {context_path}/tasks.json and docs/project_notes/project_map.md, then verify each item of this rubric:
95
+ [paste the four Alignment Check bullets above, with the brief's stakeholder list included for the map-consistency check]
96
+
97
+ Return: PASS + one-line confirmation, OR specific findings — each naming the slice, task, or map section it points at.
98
+ ```
99
+
100
+ On findings: correct the output, then re-run the reviewer once. If findings persist after the correction, surface them to the user rather than shipping misaligned output. Either way, if a failure cannot be corrected within this skill (e.g., missing stakeholder coverage that needs to go back to discovery), flag it explicitly to the user.
78
101
 
79
102
  ## EXPRESS MODE
80
103
 
81
- Read `track` from the active context (missing = `"full"`). When `track == "express"`:
104
+ Read `track` from the active context (missing or null = `"full"`). When `track == "express"`:
82
105
  - Skip Phase 2's full experience-mapping dialogue. Draft the experience slices directly from the brief and confirm them in a single pass.
83
106
  - Decompose into tasks as usual — expect few. The producer-ready test still applies.
84
107
  - Do NOT create test tasks (see Test Coverage).
@@ -422,17 +445,9 @@ Anti-bloat rules:
422
445
  - No class names, method names, enum values, file paths, or CSS selectors — those live in code.
423
446
  - Component Reference entries are ONE sentence. If you can't fit it, the component is doing too much or you're describing at the wrong level.
424
447
 
425
- Append a row to `docs/project_notes/map_history.md` (NOT to `project_map.md`):
426
-
427
- - If `map_history.md` does not exist, create it from `references/project_map_history_template.md`.
428
- - If `project_map.md` contains a legacy `## Map History` section (pre-v11.7 scaffold), move its rows into `map_history.md` preserving order, then delete the section from `project_map.md`.
429
- - Then append:
430
-
431
- | Date | Phase | Branch | Change | Reason |
432
- |------|-------|--------|--------|--------|
433
- | [today ISO date] | Compose | [active_context] | Initial outline | Created from experience mapping |
448
+ **Truth-window line:** update the `_Reflects: …_` line directly under the `# Project Map` title to `_Reflects: compose ([today ISO date]) · Reconciled with code: [keep existing value]_`. If the line is absent (older project), add it with `Reconciled with code: never`.
434
449
 
435
- Legacy section cleanup (one-time, transparent): if `project_map.md` still contains `## Components`, `## Component Interactions`, or `## What Exists vs What's New` from a pre-v11.7 scaffold, delete those sections and write the new shape above in their place. This backfill runs silently.
450
+ Legacy section cleanup (one-time, transparent): if `project_map.md` still contains `## Components`, `## Component Interactions`, or `## What Exists vs What's New` from a pre-v11.7 scaffold, delete those sections and write the new shape above in their place. If it contains a legacy inline `## Map History` section, delete it — map history is no longer tracked (v11.10). This backfill runs silently.
436
451
 
437
452
  ### Alignment Check
438
453
 
@@ -481,7 +496,7 @@ The branch `tasks.json` is a complete document (not a diff) but includes a `pare
481
496
  }
482
497
  ```
483
498
 
484
- Update `docs/project_notes/project_map.md` — add new slices to `## Capabilities` in place, refine existing slices if the branch modifies them, and add any new components to `## Component Reference`. Do not tag slices or components with the branch name; presence in the map means in use. Append the branch's entry to `docs/project_notes/map_history.md` per the format above.
499
+ Update `docs/project_notes/project_map.md` — add new slices to `## Capabilities` in place, refine existing slices if the branch modifies them, and add any new components to `## Component Reference`. Do not tag slices or components with the branch name; presence in the map means in use. Update the truth-window line per the format above.
485
500
 
486
501
  Branch outlines should be faster — most of the experience mapping is inherited. Focus the conversation on what's new.
487
502
 
@@ -27,7 +27,7 @@ You are the engineering brain. Outline decided what needs to exist. You decide h
27
27
  9. You MUST route to `/intuition-enuncia-execute` after completion. NEVER to `/intuition-enuncia-handoff`.
28
28
  10. You MUST NOT write code. You write specs that describe what code to write. Producers write code.
29
29
  11. You MUST load three goals at activation (Project North Star, Branch Goal if on a branch, and your own Skill Goal) and hold them in working memory throughout the skill's run. See GOAL ALIGNMENT.
30
- 12. You own `## Operational Foundation` in `project_map.md`. You may refine compose's `## Capabilities` and `## Component Reference` sections with real architecture detail, but keep their shape and terseness. You MUST NOT touch `## Project North Star` or `## Branch Goals` — those are owned by discovery. Append history rows to `docs/project_notes/map_history.md`, not inside `project_map.md`.
30
+ 12. You own `## Operational Foundation` in `project_map.md`. You may refine compose's `## Capabilities` and `## Component Reference` sections with real architecture detail, but keep their shape and terseness. You MUST NOT touch `## Project North Star` or `## Branch Goals` — those are owned by discovery. Update the truth-window line when you write the map.
31
31
  13. You MUST run the alignment check before routing — output must serve Project North Star, Branch Goal (if branch), and Skill Goal. See GOAL ALIGNMENT → Alignment Check.
32
32
 
33
33
  ## CONTEXT PATH RESOLUTION
@@ -74,11 +74,34 @@ Before writing outputs or routing, run the last-stop check:
74
74
  - **Skill Goal**: Is the output design-level specs — not code (that's producers), not decomposition (that's compose), not implementation (that's execute)?
75
75
  - **Project map consistency**: Do the components and connections you wrote into `## Operational Foundation`, `## Capabilities`, and `## Component Reference` match the interfaces and files in the enriched tasks.json? Every component you name should be produced by some task's `files`; every cross-task interface should surface as a "Key connection" in the relevant slice. The map and tasks.json must tell the same architectural story.
76
76
 
77
- If any check fails, correct before proceeding. If you cannot correct within this skill, flag it explicitly to the user.
77
+ ### How the Check Runs
78
+
79
+ **Express track:** run the four checks yourself (self-check). Scale-to-task — no subagent.
80
+
81
+ **Full track:** the check is independent — fresh eyes, not the author grading its own work. Spawn ONE `intuition-reviewer` agent via the Task tool:
82
+
83
+ ```
84
+ You are an alignment reviewer. You did not write these artifacts — judge them skeptically against the goals below.
85
+
86
+ Project North Star:
87
+ [paste verbatim]
88
+
89
+ [If branch] Branch Goal for "{active_context}":
90
+ [paste verbatim]
91
+
92
+ Skill under review: design. Its output must be design-level specs — technical approach, interfaces, files, decisions on each task — not code, not decomposition.
93
+
94
+ Read {context_path}/tasks.json (the enriched design fields) and docs/project_notes/project_map.md, then verify each item of this rubric:
95
+ [paste the four Alignment Check bullets above]
96
+
97
+ Return: PASS + one-line confirmation, OR specific findings — each naming the task, field, or map section it points at.
98
+ ```
99
+
100
+ On findings: correct the output, then re-run the reviewer once. If findings persist after the correction, surface them to the user rather than shipping misaligned output. Either way, if a failure cannot be corrected within this skill, flag it explicitly to the user.
78
101
 
79
102
  ## EXPRESS MODE
80
103
 
81
- Read `track` from the active context (missing = `"full"`). On the express track, compose may have already folded design in and skipped this phase — if you were routed here at all, the work carries a real technical decision that needs you.
104
+ Read `track` from the active context (missing or null = `"full"`). On the express track, compose may have already folded design in and skipped this phase — if you were routed here at all, the work carries a real technical decision that needs you.
82
105
 
83
106
  When `track == "express"`:
84
107
  - Design only what's necessary. Skip Phase 2.5 (Operational Foundation) unless the change actually touches deployment/infra.
@@ -183,6 +206,8 @@ Launch `intuition-researcher` agents to gather technical context. Research is ta
183
206
 
184
207
  Research agents are optional — skip them when the technical approach is obvious from the tasks and map.
185
208
 
209
+ **Specialist lens.** When a slice group sits squarely in a domain with a matching profile in the `specialists/` registry (scan `.claude/specialists/`, then `~/.claude/specialists/`) — e.g., database architecture, legal analysis, business analysis — read that profile and fold its question-set and risk knowledge into this group's research prompts and your own design thinking. This is a lens, not a gate: no extra approval step, no separate specialist phase. Skip it when no profile clearly matches.
210
+
186
211
  ### 3b. Design Decisions
187
212
 
188
213
  For each group, determine:
@@ -191,6 +216,24 @@ For each group, determine:
191
216
  - **Interfaces**: How does this group's output connect to other groups? What data flows between them?
192
217
  - **Patterns**: What design patterns apply? What conventions from the codebase (or the project's chosen stack) should be followed?
193
218
 
219
+ ### 3b.1. Recall Prior Decisions (internal precedent)
220
+
221
+ Before locking a decision that plausibly has precedent — a stack choice, an architectural pattern, an interface shape an earlier branch may already have settled — recall what the project already decided and why. Spawn an `intuition-memory-retriever` agent via the Task tool:
222
+
223
+ ```
224
+ QUERY: <the specific technical/architecture choice under consideration>
225
+ CALLER: design
226
+ INTENT: decision-rationale
227
+ SCOPE: all
228
+ ```
229
+
230
+ Apply the result:
231
+ - **Found** → fold the prior rationale into your decision and cite it when you present the group in 3e ("we chose Postgres in branch X because Y — keeping it for consistency"). Don't silently re-decide what's already settled.
232
+ - **Conflict** → the user is about to override a prior ratified decision. Surface it as part of the decision in 3e; design's job is to route decisions per posture, and a contradiction of an earlier ratified call is exactly what the user should weigh.
233
+ - **Not found** → proceed normally.
234
+
235
+ Keep this **per-decision, not per-group** — only when a decision plausibly has precedent. Don't spawn a retriever for every task. This is the *internal-precedent* check; 3b.5 below is the *external-landscape* check — different jobs.
236
+
194
237
  ### 3b.5. Verify Against Current Landscape
195
238
 
196
239
  After making initial design decisions, spawn `intuition-web-researcher` to verify load-bearing technical choices against the current landscape — library currency, deprecation status, alternatives, current best practices.
@@ -300,7 +343,7 @@ The principle: design tells the UI producer what must be TRUE about the interfac
300
343
  - **`files`**: the test file paths to create.
301
344
  - **`producer_notes`**: fixtures, mocks, or seed data the tests need; and what NOT to test (don't test framework internals or third-party code).
302
345
 
303
- Record the suite run command in `## Operational Foundation` (or `key_facts.md`) so verify can find and run it later — verify's regression step depends on knowing how to invoke the suite.
346
+ Record the suite run command in the map's `## Operational Foundation` that is its canonical home, and verify's regression step reads it from there.
304
347
 
305
348
  After enrichment, each task object should contain everything a producer needs. No ambiguity, no open questions.
306
349
 
@@ -345,11 +388,7 @@ Anti-bloat rules:
345
388
  - Never expand a Component Reference entry past one sentence. If the architectural detail is important, point to code.
346
389
  - No task IDs, no status fields, no stakeholder-touchpoint tags. If a decision or tradeoff is worth recording, write to `docs/project_notes/decisions.md`, not the map.
347
390
 
348
- Append a row to `docs/project_notes/map_history.md`. Create the file from `references/project_map_history_template.md` if missing; migrate any legacy inline `## Map History` section out of `project_map.md` and delete it.
349
-
350
- | Date | Phase | Branch | Change | Reason |
351
- |------|-------|--------|--------|--------|
352
- | [today ISO date] | Design | [active_context] | Architecture finalized | [one sentence] |
391
+ **Truth-window line:** update the `_Reflects: …_` line directly under the `# Project Map` title to `_Reflects: design ([today ISO date]) · Reconciled with code: [keep existing value]_`. If the line is absent (older project), add it with `Reconciled with code: never`. If the map still contains a legacy inline `## Map History` section, delete it map history is no longer tracked (v11.10).
353
392
 
354
393
  ### Alignment Check
355
394
 
@@ -30,7 +30,7 @@ You help users figure out what they're building. You do this through focused con
30
30
  12. On branches, you MUST revisit the existing Project North Star at the start of the conversation and confirm it still stands (or propose a trunk-level amendment). See BRANCH MODE → Revisit Project North Star.
31
31
  13. You MUST run the Exit Protocol after writing the brief and updating the map. Route to `/intuition-enuncia-compose`.
32
32
  14. You MUST NOT launch research agents proactively. Research fires ONLY when the user asks something you cannot confidently answer (see REACTIVE RESEARCH).
33
- 15. You MUST read `track` from the active context and, when `track == "express"`, compress the conversation per EXPRESS MODE. A missing `track` defaults to `"full"`.
33
+ 15. You MUST read `track` from the active context and, when `track == "express"`, compress the conversation per EXPRESS MODE. A missing or null `track` reads as `"full"` for depth — but null also means triage never ran (see EXPRESS MODE).
34
34
  16. At activation, after reading state, you MUST set `workflow.discovery.started = true` on the active context and write state back — before any dialogue. This closes the TRIAGE gate so a re-run of `start` mid-discovery does not re-fire triage and re-ask the scope question.
35
35
 
36
36
  ## THE FOUR DIMENSIONS
@@ -85,7 +85,7 @@ When authoring a Project North Star or a Branch Goal, apply these three rules. T
85
85
 
86
86
  ## EXPRESS MODE
87
87
 
88
- Read `track` from the active context in `.project-memory-state.json` at activation (a missing value means `"full"`). If `track` is unset AND discovery hasn't started, the entry bypassed start's triage — ask the one Scope question from start's TRIAGE yourself, record the answer as `track` on the active context, then proceed.
88
+ Read `track` from the active context in `.project-memory-state.json` at activation. A null or missing `track` means triage never ran — initialize and handoff seed it as null ("nobody asked yet"), so the direct `initialize → discovery` and `handoff → discovery` routes land here. If `track` is null or missing AND discovery hasn't started, ask the one Scope question from start's TRIAGE yourself, record the answer as `track` on the active context, then proceed. (If discovery already started with track still null — a legacy state — read it as `"full"` and don't re-ask.)
89
89
 
90
90
  When `track == "express"`, compress hard:
91
91
  - Open by stating your read of all four dimensions inferred from the user's request, and ask only what you genuinely cannot infer — target one question, two at most.
@@ -148,7 +148,7 @@ Does the Project North Star still hold for this work, or does the scope of this
148
148
 
149
149
  Accept one of three outcomes:
150
150
  - **Holds as-is** — keep it unchanged, proceed to Opening.
151
- - **Needs amendment** — work with the user to refine the Project North Star at altitude (apply the three rules). Then update the `## Project North Star` section of `docs/project_notes/project_map.md` in place. Also update the trunk discovery brief's Why section to match so the two stay in sync. Append a row to `docs/project_notes/map_history.md` (Phase: "Discovery (branch revisit)", Branch: `[active_context]`, Change: "Amended Project North Star", Reason: "[branch-provided rationale]"). Proceed to Opening.
151
+ - **Needs amendment** — work with the user to refine the Project North Star at altitude (apply the three rules). Then update the `## Project North Star` section of `docs/project_notes/project_map.md` in place. Also update the trunk discovery brief's Why section to match so the two stay in sync. Proceed to Opening.
152
152
  - **User wants to think about it** — move on to Opening, and come back to this before writing the brief.
153
153
 
154
154
  #### Opening
@@ -191,7 +191,7 @@ Add a `## Parent Context` section at the top:
191
191
  - **Parent**: [trunk or branch name]
192
192
  - **Inherited dimensions**: [list dimensions unchanged from parent]
193
193
  - **Changed dimensions**: [list dimensions this branch modifies, with brief rationale]
194
- - **Project North Star**: Holds as-is | Amended this session (see Map History)
194
+ - **Project North Star**: Holds as-is | Amended this session
195
195
  ```
196
196
 
197
197
  This lets downstream skills know what's new without reading the parent brief.
@@ -297,7 +297,7 @@ After confirm and posture, write `{context_path}/discovery_brief.md`. The Why se
297
297
  - **Parent**: [trunk or branch name]
298
298
  - **Inherited dimensions**: [list dimensions unchanged from parent]
299
299
  - **Changed dimensions**: [list what changed and why]
300
- - **Project North Star**: Holds as-is | Amended this session (see Map History)
300
+ - **Project North Star**: Holds as-is | Amended this session
301
301
 
302
302
  ## Who — Stakeholders
303
303
  [Stakeholders and their relationship to the project]
@@ -342,18 +342,14 @@ Keep every section terse. Bullets over prose. No redundancy between sections. Th
342
342
 
343
343
  After writing `discovery_brief.md`, propagate the goal statement into `docs/project_notes/project_map.md`. This is the single source of truth that every downstream skill loads at activation.
344
344
 
345
- Read the current `docs/project_notes/project_map.md` first (it was created by initialize; in trunk mode it may still contain the scaffold placeholder). Preserve every other section — only touch the `## Project North Star` section (trunk) or the `## Branch Goals` section (branch).
345
+ Read the current `docs/project_notes/project_map.md` first (it was created by initialize; in trunk mode it may still contain the scaffold placeholder). Preserve every other section — only touch the `## Project North Star` section (trunk) or the `## Branch Goals` section (branch), plus the truth-window line.
346
+
347
+ **Truth-window line:** update the `_Reflects: …_` line directly under the `# Project Map` title to `_Reflects: discovery ([today ISO date]) · Reconciled with code: [keep existing value]_`. If the line is absent (older project), add it with `Reconciled with code: never`.
346
348
 
347
349
  ### Trunk Mode
348
350
 
349
351
  Replace the `## Project North Star` section body with the verbatim content from the brief's `## Why — Project North Star` section. Remove any scaffold placeholder text in that section. Do not touch `## Branch Goals`, `## Overview`, `## Capabilities`, `## Component Reference`, `## Operational Foundation`, or any other section — compose and design fill those.
350
352
 
351
- Append a row to `docs/project_notes/map_history.md` (see Backfill below if the file doesn't exist yet):
352
-
353
- | Date | Phase | Branch | Change | Reason |
354
- |------|-------|--------|--------|--------|
355
- | [today ISO date] | Discovery | trunk | Authored Project North Star | Trunk discovery complete |
356
-
357
353
  ### Branch Mode
358
354
 
359
355
  Under the `## Branch Goals` section, add a subsection for this branch (or update if one already exists):
@@ -365,17 +361,11 @@ Under the `## Branch Goals` section, add a subsection for this branch (or update
365
361
 
366
362
  Place branch subsections in creation order. Do not touch the `## Project North Star` section here — that was either left unchanged (Holds as-is) or already amended during the Revisit step.
367
363
 
368
- Append a row to `docs/project_notes/map_history.md`:
369
-
370
- | Date | Phase | Branch | Change | Reason |
371
- |------|-------|--------|--------|--------|
372
- | [today ISO date] | Discovery (branch) | [active_context] | Authored Branch Goal | Branch discovery complete |
373
-
374
364
  ### Backfill (Existing Projects)
375
365
 
376
366
  If `project_map.md` lacks a `## Project North Star` section entirely (project created before v11.6.0), insert one immediately after the `# Project Map` title. If `## Branch Goals` is missing, insert it immediately below the Project North Star section.
377
367
 
378
- If `docs/project_notes/map_history.md` does not exist (project created before v11.7.0), create it from `references/project_map_history_template.md`. If `project_map.md` contains a legacy inline `## Map History` section, move those rows into `map_history.md` preserving order, then delete the section from `project_map.md`. Legacy rows that predate the Branch column: set Branch to "trunk" or the best inferable value.
368
+ If `project_map.md` contains a legacy inline `## Map History` section (pre-v11.7), delete it map history is no longer tracked (v11.10). The truth-window line replaces it.
379
369
 
380
370
  This backfill runs silently — no user notification needed; the map now conforms.
381
371
 
@@ -96,7 +96,7 @@ Read these files:
96
96
 
97
97
  Validate: every task in `tasks.json` has a `technical_approach` field (indicating design enrichment). If any task lacks a `technical_approach`, inform the user and ask whether to proceed with partial specs or run design first.
98
98
 
99
- Also read `track` from the active context (missing = `"full"`). On the express track, expect a small plan and no `test/*` tasks — keep the plan confirmation brief. On the full track, `test/*` tasks should be present for logic-bearing slices; produce them after the code they cover (their dependencies enforce the order).
99
+ Also read `track` from the active context (missing or null = `"full"`). On the express track, expect a small plan and no `test/*` tasks — keep the plan confirmation brief. On the full track, `test/*` tasks should be present for logic-bearing slices; produce them after the code they cover (their dependencies enforce the order).
100
100
 
101
101
  From each task object, extract:
102
102
  - `task.technical_approach` and `task.files`
@@ -299,11 +299,7 @@ Non-code deliverables (documents, spreadsheets, etc.) skip security review.
299
299
 
300
300
  If implementation revealed anything not in the map — new components, changed dependencies, refined connections — update the relevant `## Capabilities` slice or add to `## Component Reference`. Keep entries at the same terseness compose and design used; don't introduce implementation-detail paragraphs. **Do not touch `## Project North Star` or `## Branch Goals`.**
301
301
 
302
- Append a row to `docs/project_notes/map_history.md` for the execute phase. Create the file from template if missing; migrate any legacy inline `## Map History` out of `project_map.md` if present.
303
-
304
- | Date | Phase | Branch | Change | Reason |
305
- |------|-------|--------|--------|--------|
306
- | [today ISO date] | Execute | [active_context] | [summary of what was built] | [one sentence] |
302
+ If you wrote to the map, update the truth-window line directly under the `# Project Map` title to `_Reflects: execute ([today ISO date]) · Reconciled with code: [keep existing value]_` (add the line with `Reconciled with code: never` if absent).
307
303
 
308
304
  ### Display Summary
309
305
 
@@ -313,9 +309,23 @@ Present a concise summary to the user: task count, pass/fail, files produced, an
313
309
 
314
310
  **Alignment Check.** Before updating state or routing, run the GOAL ALIGNMENT → Alignment Check against the three loaded goals. If any check fails, re-delegate, escalate, or flag. Do not ship misaligned output.
315
311
 
316
- **Update state.** Read `.project-memory-state.json`. Target active context. Set: `status` → `"verify"`, `workflow.execute.completed` → `true`, `workflow.execute.completed_at` → current ISO timestamp, `workflow.verify.started` → `true`. Set on root: `last_handoff` → current ISO timestamp, `last_handoff_transition` → `"execute_to_verify"`. Write back.
312
+ **Update state and route** branch on what was produced:
313
+
314
+ **If any deliverable is code, configuration, or scripts** (anything that runs): Read `.project-memory-state.json`. Target active context. Set: `status` → `"verify"`, `workflow.execute.completed` → `true`, `workflow.execute.completed_at` → current ISO timestamp, `workflow.verify.started` → `true`. Set on root: `last_handoff` → current ISO timestamp, `last_handoff_transition` → `"execute_to_verify"`. Write back. Route to `/intuition-enuncia-verify`.
315
+
316
+ **If only non-code deliverables** (documents, spreadsheets, presentations, data files): there is no live system to verify, and verify must not be left dangling in state. Ask via AskUserQuestion:
317
+
318
+ ```
319
+ Question: "All deliverables are [types] — there's no live system for the verify phase to test. Mark the workflow complete?"
320
+ Header: "Wrap Up"
321
+ Options:
322
+ - "Complete — the deliverables are what I needed"
323
+ - "Not yet — something's missing"
324
+ ```
325
+
326
+ On "Complete": set on target: `status` → `"complete"`, `workflow.execute.completed` → `true`, `workflow.execute.completed_at` → now, `workflow.verify.completed` → `true`, `workflow.verify.completed_at` → now. Set on root: `last_handoff` → now, `last_handoff_transition` → `"execute_to_complete"`. Write back. Tell the user the workflow is complete.
317
327
 
318
- **Route.** Tell the user the next step. If code was produced, route to `/intuition-enuncia-verify`. If only non-code deliverables, workflow may be complete ask the user.
328
+ On "Not yet": leave state untouched — `workflow.execute.completed` stays `false` so `start` routes back to execute, and RESUME LOGIC picks up the task board. Work out with the user what's missing: re-delegation of a deliverable, or a gap that needs a new branch.
319
329
 
320
330
  ## BRANCH MODE
321
331
 
@@ -49,7 +49,7 @@ If the user hasn't provided branch details, collect via AskUserQuestion:
49
49
  "created_at": "ISO timestamp",
50
50
  "purpose": "User-provided purpose",
51
51
  "status": "none",
52
- "track": "full",
52
+ "track": null,
53
53
  "workflow": {
54
54
  "discovery": { "started": false, "completed": false, "completed_at": null },
55
55
  "compose": { "started": false, "completed": false, "completed_at": null },
@@ -72,7 +72,7 @@ Branch "[display_name]" created.
72
72
  Run /clear then /intuition-enuncia-discovery
73
73
  ```
74
74
 
75
- Discovery, when it runs on this branch, will revisit the Project North Star from the project map (confirming or proposing amendment) and author a Branch Goal at the same altitude. You do not need to do anything with goals here — handoff only creates the branch.
75
+ Discovery, when it runs on this branch, will triage the work's track (`track` starts as null — "nobody asked yet"), revisit the Project North Star from the project map (confirming or proposing amendment), and author a Branch Goal at the same altitude. You do not need to do anything with goals or track here — handoff only creates the branch.
76
76
 
77
77
  ## VOICE
78
78
 
@@ -94,7 +94,6 @@ docs/
94
94
  ├── trunk/
95
95
  ├── branches/
96
96
  ├── project_map.md
97
- ├── map_history.md
98
97
  ├── bugs.md
99
98
  ├── decisions.md
100
99
  ├── key_facts.md
@@ -113,7 +112,6 @@ For each file, use the Read tool to read the template, then use Write to create
113
112
  | `references/key_facts_template.md` | `docs/project_notes/key_facts.md` |
114
113
  | `references/issues_template.md` | `docs/project_notes/issues.md` |
115
114
  | `references/project_map_template.md` | `docs/project_notes/project_map.md` |
116
- | `references/project_map_history_template.md` | `docs/project_notes/map_history.md` |
117
115
 
118
116
  The project map template is a scaffold — compose and design fill it with real content during the workflow.
119
117
 
@@ -133,7 +131,7 @@ The state file uses the Enuncia v11 schema:
133
131
  "active_context": "trunk",
134
132
  "trunk": {
135
133
  "status": "none",
136
- "track": "full",
134
+ "track": null,
137
135
  "workflow": {
138
136
  "discovery": {
139
137
  "started": false,
@@ -240,7 +238,7 @@ or /intuition-enuncia-start to check project status.
240
238
  These template files are in the `references/` directory. Use Read tool to access them:
241
239
 
242
240
  **Memory file templates** (Step 2):
243
- - `bugs_template.md`, `decisions_template.md`, `key_facts_template.md`, `issues_template.md`, `project_map_template.md`, `project_map_history_template.md`
241
+ - `bugs_template.md`, `decisions_template.md`, `key_facts_template.md`, `issues_template.md`, `project_map_template.md`
244
242
 
245
243
  **State template** (Step 3):
246
244
  - `state_template.json` — Enuncia v11 workflow state
@@ -39,6 +39,10 @@ Project memory is maintained in `docs/project_notes/` for consistency across ses
39
39
  - Verify the proposed approach doesn't conflict with past choices
40
40
  - If it does conflict, acknowledge the existing decision and explain why a change is warranted
41
41
 
42
+ **To recall past decisions, bugs, or facts — including from other branches or archived work:**
43
+ - Run `/intuition-recall <question>` — it searches all of project memory (trunk, every branch, and `archive/`) and returns a cited answer, or says so honestly when nothing is found.
44
+ - This reaches context that manually reading the active context's files would miss.
45
+
42
46
  **When encountering errors or bugs:**
43
47
  - Search `docs/project_notes/bugs.md` for similar issues
44
48
  - Apply known solutions if found
@@ -1,5 +1,9 @@
1
1
  # Project Map
2
2
 
3
+ _Reflects: scaffold · Reconciled with code: never_
4
+
5
+ <!-- Truth-window line. Every pipeline skill that writes this map updates the "Reflects" half with its phase name and today's date. Verify's Map Integrity Pass sets "Reflects: verified" and stamps "Reconciled with code". Until reconciled, sections below describe the design, not necessarily the running system. -->
6
+
3
7
  ## Project North Star
4
8
  [Populated by trunk discovery. The outcome this project is held to — specific about what "good" looks like, flexible about the how. Every Enuncia skill, on every branch, loads this at activation and checks its output against it before presenting.
5
9
 
@@ -44,4 +48,3 @@ Altitude rules for this section:
44
48
  - Decisions → `docs/project_notes/decisions.md`
45
49
  - Config, credentials, URLs → `docs/project_notes/key_facts.md`
46
50
  - Work log → `docs/project_notes/issues.md`
47
- - Map evolution by phase → `docs/project_notes/map_history.md`
@@ -5,7 +5,7 @@
5
5
  "active_context": "trunk",
6
6
  "trunk": {
7
7
  "status": "none",
8
- "track": "full",
8
+ "track": null,
9
9
  "workflow": {
10
10
  "discovery": {
11
11
  "started": false,
@@ -74,7 +74,7 @@ Default state schema:
74
74
  "active_context": "trunk",
75
75
  "trunk": {
76
76
  "status": "none",
77
- "track": "full",
77
+ "track": null,
78
78
  "workflow": {
79
79
  "discovery": { "started": false, "completed": false, "completed_at": null },
80
80
  "compose": { "started": false, "completed": false, "completed_at": null },
@@ -163,6 +163,8 @@ Track: [express | full] Where you are: [phase status line]
163
163
 
164
164
  Keep it to ~4 lines. Pull only from the map's `## Project North Star`, `## Overview`, and `## Capabilities` headings — never dump the full map. If the map is still the blank scaffold (first_time / pre-compose), skip the summary and give only the status line.
165
165
 
166
+ Check the map's truth-window line (the `_Reflects: … · Reconciled with code: …_` line under the title). If "Reconciled with code" is "never" or older than the "Reflects" date, append one caveat line to the summary: `(map reflects [phase] — not yet verified against code)`. If the line is absent (older project), say nothing.
167
+
166
168
  ## STEP 5: ROUTING TABLE
167
169
 
168
170
  | Phase | Status Line | Route |
@@ -188,13 +190,13 @@ Project Status:
188
190
  ```
189
191
 
190
192
  Use AskUserQuestion:
191
- - Question: "All current work is complete. What's next?"
193
+ - Question: "All current work is complete. New work happens on a branch — want to start one?"
192
194
  - Header: "Next Step"
193
- - Options: "Create a new branch" / "Start a new project on trunk"
195
+ - Options: "Create a new branch" / "Nothing for now"
194
196
 
195
197
  **If "Create a new branch":** Collect branch name, purpose, and parent via AskUserQuestion. Then route: "Run `/intuition-enuncia-handoff` to register the branch. Pass along: branch name, purpose, parent."
196
198
 
197
- **If "Start a new project on trunk":** Route to `/intuition-enuncia-discovery`.
199
+ **If "Nothing for now":** End with the status display. Do NOT offer to restart the pipeline on trunk trunk's workflow ran once to establish the foundation; everything after completion is branch work so the Project North Star and the map stay coherent.
198
200
 
199
201
  ## EDGE CASES
200
202
 
@@ -165,7 +165,7 @@ Run the project's toolchain to verify basic code health. Execute in order:
165
165
 
166
166
  1. **Type check / lint** (if applicable): `[type check command]`, `[lint command]`
167
167
  2. **Build / compile** (if applicable): `[build command]`
168
- 3. **Test suite (if one exists)**: On the full track, design recorded the suite command in `## Operational Foundation` / `key_facts.md` and execute produced `test/*` deliverables — run the FULL suite to catch regressions. On the express track, or any project with no authored tests, there is no suite to run: skip this step and note in the final results that there is no automated regression net. Do NOT hand-write tests here — verify validates, it does not author tests.
168
+ 3. **Test suite (if one exists)**: On the full track, design recorded the suite command in the map's `## Operational Foundation` (its canonical home — check `key_facts.md` only on older projects) and execute produced `test/*` deliverables — run the FULL suite to catch regressions. On the express track, or any project with no authored tests, there is no suite to run: skip this step and note in the final results that there is no automated regression net. Do NOT hand-write tests here — verify validates, it does not author tests.
169
169
 
170
170
  Also run `mcp__ide__getDiagnostics` to catch IDE-visible issues.
171
171
 
@@ -335,7 +335,7 @@ Work through the interaction map methodically, using your Tier 1 browser driver
335
335
 
336
336
  #### 8a. Load the Page
337
337
 
338
- Use WebFetch to load the page. Analyze what comes back:
338
+ Load the page via your browser-control tier — Tier 1 driver navigation, or WebFetch on Tier 2. Analyze what comes back:
339
339
  - **Does the page render?** (non-error HTTP status, meaningful HTML content)
340
340
  - **Are key elements present?** (navigation, expected headings, expected content sections)
341
341
  - **Are there broken references?** (missing images, broken CSS/JS links, 404 resources)
@@ -425,16 +425,12 @@ If something drifts, flag it: "All interactions work, but [specific concern abou
425
425
 
426
426
  Correct the map in place. If reconciliation reveals real architectural drift the user should know about — a capability silently dropped, a connection that never actually worked — surface it in the final results. A quietly wrong map is worse than no map: it's the next session's starting truth.
427
427
 
428
+ After reconciling, stamp the truth-window line directly under the `# Project Map` title: `_Reflects: verified ([today ISO date]) · Reconciled with code: [today ISO date]_` (add the line if absent). This is the only phase that updates the "Reconciled with code" half — it tells the next session the map was checked against reality, not just written from plans.
429
+
428
430
  **Update `docs/project_notes/project_map.md`** if integration or testing revealed anything new — refine `## Capabilities` slices or `## Component Reference` entries. Keep the shape and terseness. **Do not touch `## Project North Star` or `## Branch Goals`.**
429
431
 
430
432
  **Run the GOAL ALIGNMENT → Alignment Check** against the three loaded goals. Any failures must be fixed or explicitly flagged in the final results.
431
433
 
432
- **Append a Verify row to `docs/project_notes/map_history.md`** (create from template if missing). On a branch, Step 11 appends the consolidation row instead — do NOT double-log; skip this append on branches. On trunk:
433
-
434
- | Date | Phase | Branch | Change | Reason |
435
- |------|-------|--------|--------|--------|
436
- | [today ISO date] | Verify | trunk | Verified live; map reconciled | [one sentence — what was verified] |
437
-
438
434
  ### STEP 11: CONSOLIDATE INTO TRUNK ARCHITECTURE (branch mode only)
439
435
 
440
436
  Skip this step on trunk — there's nothing to consolidate.
@@ -445,13 +441,9 @@ On a branch, before marking the branch complete, consolidate this branch's addit
445
441
  2. **`## Component Reference`**: Remove any branch markers (e.g., "(school-org branch)", "(new)") from component entries. Components belong to the product, not to the branch that delivered them.
446
442
  3. **`## Operational Foundation`**: Fold any branch-specific language into the main prose. If the branch added auth/deployment/tech-stack detail, it's now just the way the system works.
447
443
 
448
- Do not touch `## Project North Star`. Leave `## Branch Goals` alone — the historical record of what each branch was for stays put; it's small and explains why slices exist.
449
-
450
- Append a row to `docs/project_notes/map_history.md` (create from template if missing; migrate any legacy inline `## Map History` out of `project_map.md` if present):
444
+ 4. **Coherence pass (map gardening)**: branches add and modify slices one delivery at a time, which fragments `## Capabilities` over the project's life. Check whether this branch's slices substantially overlap an existing capability if so, merge or rename so the section describes the product's current shape, not its delivery history. Update `## Component Reference` entries and each slice's Components list to match the merged structure. Keep the three-field slice shape and stakeholder-facing phrasing; presence in the map still means in use.
451
445
 
452
- | Date | Phase | Branch | Change | Reason |
453
- |------|-------|--------|--------|--------|
454
- | [today ISO date] | Verify | [active_context] | Consolidated into trunk | [one sentence — what this branch delivered] |
446
+ Do not touch `## Project North Star`. Leave `## Branch Goals` alone the historical record of what each branch was for stays put; it's small and explains why slices exist.
455
447
 
456
448
  ### STEP 12: EXIT
457
449
 
@@ -0,0 +1,54 @@
1
+ ---
2
+ name: intuition-recall
3
+ description: Recall past decisions, rationale, bugs, facts, or context from project memory — across trunk, all branches, and archived contexts. Returns a cited answer and says so honestly when nothing is found. A read-anytime utility, not a pipeline phase.
4
+ model: sonnet
5
+ tools: Read, Glob, Grep, Task, AskUserQuestion, Bash
6
+ allowed-tools: Read, Glob, Grep, Task, Bash
7
+ ---
8
+
9
+ # Recall Protocol
10
+
11
+ ## SKILL GOAL
12
+
13
+ Answer "what did we decide / hit / establish, and why" from the project's own memory — including decisions and context buried in other branches or archived work that manual file-reading would never surface. Return a synthesized answer with sources, and be honest when memory doesn't hold the answer. You retrieve and report; you do not re-decide anything.
14
+
15
+ This is a utility, callable at any time from any phase. It is **not** a workflow phase: it reads no workflow state, writes nothing, transitions nothing, and routes nowhere.
16
+
17
+ ## HOW IT WORKS
18
+
19
+ ### 1. Get the question
20
+
21
+ - If the skill was invoked with a question after the command (e.g. `/intuition-recall what did we decide about auth?`), use that text verbatim as the query.
22
+ - If no question was provided, ask for one in plain text: "What would you like me to recall from project memory?" Wait for the answer. (Do not use AskUserQuestion for this — it's an open question, not a pick-list.)
23
+
24
+ ### 2. Spawn the retriever
25
+
26
+ Launch ONE `intuition-memory-retriever` agent via the Task tool. Pass:
27
+
28
+ ```
29
+ QUERY: <the user's question, verbatim>
30
+ SCOPE: all
31
+ CALLER: user-recall
32
+ INTENT: <decision-rationale | bug-history | architecture | general — your best read of the question; omit if unsure>
33
+ ```
34
+
35
+ The retriever owns enumeration and search. Do not pre-read memory files yourself or hand it a file list — that's its job, and it searches places (every branch, `archive/`) you won't think to.
36
+
37
+ ### 3. Relay the answer
38
+
39
+ The retriever returns fixed sections (`## ANSWER`, `## FINDINGS`, `## CONFLICTS`, `## SEARCH PERFORMED`, `## CONFIDENCE`). Present them to the user as a clean, conversational answer:
40
+
41
+ - Lead with the **ANSWER**.
42
+ - Render each supporting citation as a clickable `path:line` (or `path § heading`) so the user can jump to the source.
43
+ - If there are **CONFLICTS**, surface them prominently — which entry won, why, and whether it's "unresolved — needs director."
44
+ - If the answer is **Not found** or **CONFIDENCE is low**, say so plainly and show the *terms the retriever searched* (from SEARCH PERFORMED). Invite the user to re-phrase with different words — a miss is often a vocabulary mismatch, not a true absence. Never paper over a miss with a guess of your own.
45
+
46
+ ### 4. Offer a next step
47
+
48
+ Briefly offer to open a cited file, dig into a specific finding, or re-run with different wording. Then return control to the user. No routing, no `/clear`.
49
+
50
+ ## VOICE
51
+
52
+ - **Faithful to the source.** Report what memory says, with citations. If you add interpretation, mark it as yours, not memory's.
53
+ - **Honest about gaps.** "Not found" is a valid, useful answer. A confident wrong recall is worse than none.
54
+ - **Brief.** Lead with the answer; keep the apparatus (search terms, full findings list) available but secondary unless the result was a miss.
@@ -1,8 +0,0 @@
1
- # Project Map History
2
-
3
- Phase-by-phase log of how the project architecture evolved. Split from `project_map.md` so the map stays oriented on current architecture — this file is the time-series log that grows forever.
4
-
5
- Append one row per phase completion (discovery, compose, design, execute, verify, or a branch consolidation). Do NOT rewrite existing rows.
6
-
7
- | Date | Phase | Branch | Change | Reason |
8
- |------|-------|--------|--------|--------|