FE-540: Design mode: commitment and exploration

HANDOFF.md

@@ -0,0 +1,129 @@
+# Handoff
+
+> Generated by `ln-handoff` at 2026-04-09T19:39Z. Read this file to resume work.
+
+## Goal
+
+Finish hardening the Phase 5 design-mode / shared phase-close seam, keep project memory current, and resume the next high-signal planning or review step without re-discovering the just-landed refactor state.
+
+## Session State
+
+- **Last completed skill**: `ln-sync` — refreshed `memory/SPEC.md` and `memory/PLAN.md`, pruned temporary refactor assumptions, removed the resolved `memory/REFACTOR.md`, and cleaned stale spike artifacts.
+- **Current skill**: `ln-handoff`
+- **Flow position**: `grill → spec → plan → [design] → [oracles] → scope → [spike] → build → review → [refactor] → [sync]`
+- **Handoff trigger**: user requested wrap-up after the completed phase-close refactor, repo cleanup, and sync pass.
+
+## In-flight work
+
+> CRITICAL: These artifacts exist only in the prior conversation, not on disk.
+> Reproduce them here with full fidelity.
+
+### Artifact 1/2 — Sync report
+
+## Sync Report
+
+### Graduations
+- No new assumption-to-decision promotions were needed during sync.
+- The recent phase-close refactor truths were already captured in persisted decisions/invariants (`D75`, `D76`, `I85`, `I86`) before sync began.
+
+### Pruned
+- `A42` removed from `memory/SPEC.md` as **embedded** — it was a temporary cutover assumption for deleting transcript-driven closure-basis recovery, and its truth now lives in `D75` + `I85`.
+- `A43` removed from `memory/SPEC.md` as **embedded** — it was a temporary transport-cutover assumption for the discriminated phase-close command union, and its truth now lives in `D73` + `I83`.
+- `memory/REFACTOR.md` removed — all six commit steps were complete, so keeping the file would preserve an already-resolved transition artifact.
+
+### Stale items
+- `memory/PLAN.md` slice 8 observed-state paragraph still referenced `memory/REFACTOR.md` by path after the refactor completed. This was updated to describe the completed phase-close refactor directly instead of pointing at a file slated for deletion.
+
+### Drift
+- No material code ↔ memory drift remained after cleanup.
+- `slice 8` is still correctly `in-progress`; downstream slices remain `9`, `10`, `11a`, `12`, `13` as documented.
+
+### Actions taken
+- Updated `memory/SPEC.md` prune comment to record the removal of `A42` and `A43`.
+- Removed `A42` and `A43` from the assumptions table.
+- Updated `memory/PLAN.md` slice 8 observed-state prose to remove the `memory/REFACTOR.md` path reference and describe the completed refactor as durable project state.
+- Deleted `memory/REFACTOR.md`.
+
+### Artifact 2/2 — Repo hygiene verdict for `spike/`
+
+- `spike/filesystem-tools.ts` was **kept**.
+  - Reason: `memory/SPEC.md` assumption `A29` still cites it explicitly as the evidence artifact for the validated core-tools spike.
+- `spike/observer-fidelity.ts` was **deleted**.
+  - Reason: unreferenced in repo; relies on the old `@anthropic-ai/claude-agent-sdk` spike path and the pre-canonical ontology; looked like a stale investigative relic rather than a current evidence artifact.
+- `spike/raw-sdk-tool-use.ts` was **deleted**.
+  - Reason: unreferenced in repo; documents a superseded raw Anthropic SDK exploration from before the current AI SDK direction.
+
+## Review findings
+
+> ALL findings from ln-review, not just the one being acted on.
+
+| # | Finding | Status | Implications |
+| --- | ------- | ------ | ------------ |
+| 1 | No `ln-review` was run in this session after the phase-close refactor sequence | `deferred` | The next thread should strongly consider `ln-review` before widening into slice 9 or 11a |
+
+## Diagnostic evidence
+
+> Concrete proof points that informed diagnoses or shifted direction.
+> Without these, a new thread inherits conclusions but not reasoning.
+
+- `rg -n "spike/filesystem-tools|spike/" .` found exactly one live canonical reference to `spike/filesystem-tools.ts`, in `memory/SPEC.md` assumption `A29`: this justified keeping that file.
+- `rg` found no live repo references to `spike/observer-fidelity.ts` or `spike/raw-sdk-tool-use.ts`: this justified deleting them as relics.
+- `find spike -maxdepth 3 -print` originally showed three files: `filesystem-tools.ts`, `observer-fidelity.ts`, `raw-sdk-tool-use.ts`; after cleanup it showed only `spike/filesystem-tools.ts`.
+- `rg -n "memory/REFACTOR\.md" .` after cleanup found only one remaining reference in `docs/design/ln-skills-review-after-alignment.md`; no canonical `memory/*` doc still depended on the file.
+- Last full verification before this cleanup was green on commit `d2189fd` via `npm run verify` (184 tests passed, build green). The subsequent cleanup touched only memory docs and deleted unreferenced spike artifacts.
+
+## Decisions and assumptions
+
+| Item | Type | Status | Source |
+| ---- | ---- | ------ | ------ |
+| D75 | `decision` | `persisted` | `memory/SPEC.md` §Decisions |
+| D76 | `decision` | `persisted` | `memory/SPEC.md` §Decisions |
+| A15 | `assumption` | `persisted` | `memory/SPEC.md` §Assumptions |
+| A40 | `assumption` | `persisted` | `memory/SPEC.md` §Assumptions |
+| A29 evidence file should remain `spike/filesystem-tools.ts` | `decision` | `volatile` | conversation + sync reasoning |
+
+## Repo state
+
+- **Branch**: `ln/fe-540-design-mode-commitment-exploration`
+- **Recent commits**:
+  - `d2189fd feat: deepen the shared phase-close module`
+  - `eb117ce feat: ship explicit phase-close command union`
+  - `4f1c3eb feat: cut workflow projection over to durable closure basis`
+  - `f49e884 feat: persist phase-outcome closure basis`
+  - `fb2854e feat: project shared force-close availability`
+- **Dirty files**:
+  - `M memory/PLAN.md`
+  - `M memory/SPEC.md`
+  - `D memory/REFACTOR.md`
+  - `D spike/observer-fidelity.ts`
+  - `D spike/raw-sdk-tool-use.ts`
+  - `?? HANDOFF.md`
+- **Test status**: last known full gate `npm run verify` passed on commit `d2189fd` before the docs/spike cleanup; no code-bearing runtime paths changed afterward.
+
+## Artifact status
+
+| Artifact | Exists | Current vs conversation |
+| ---------- | ------ | ----------------------- |
+| memory/SPEC.md | yes | current |
+| memory/PLAN.md | yes | current |
+| memory/REFACTOR.md | no | n/a |
+
+## Next steps
+
+1. Run `ln-review` on the phase-close / design-mode seam now that the full refactor sequence is complete.
+2. If review is clean, use `ln-scope` to pick the next planned slice — most likely `9` (requirements-review mode), unless priority shifts toward `11a` (dashboard workflow state).
+3. Commit the current doc/spike cleanup if the user wants this hygiene pass preserved as its own checkpoint.
+
+## Open questions
+
+- Should the historical note in `docs/design/ln-skills-review-after-alignment.md` that mentions `memory/REFACTOR.md` be updated, or is it acceptable as archival design commentary?
+- Is the next best move `ln-review` first, or should the team jump directly to scoping slice `9`?
+- Does the team want to keep `spike/filesystem-tools.ts` indefinitely as evidence for `A29`, or should that evidence eventually migrate into a more durable docs location?
+
+## Resume prompt
+
+Paste this into a new session:
+
+> Read `HANDOFF.md` in the workspace root for this work area. It contains the full state of in-progress work.
+> The immediate next step is: run `ln-review` on the phase-close / design-mode seam.
+> Start by reviewing the sync report and repo hygiene verdict in the In-flight section, then inspect the dirty files before deciding whether to commit the cleanup or continue into review.

docs/design/DESIGN_SCRATCH.md

@@ -1,21 +1,34 @@
 ### slice and scope mis-matches VS saipo report
 
-- Phase closure/hand-off "force"
-- Assistant exploring existing codebase as context
-- Some way of getting output from the tool to throw at a coding assistant (e.g. files or whatever)
-	- ^^ that gets us to the point where it can be experimented with as a way of working.
-- Then make it look like the designs (ralph loop?)
+- [ ] Exploring existing codebase as kickoff/framing input
+- [x] Phase closure/hand-off "force"
+- [ ] Output in a format that is ready for a coding assistant (e.g. files or whatever)
+	- (need to get to the point where it can be experimented with as a way of working.)
+- [ ] Make it look like the designs (ralph loop?)
 	- maybe this is something you could kick off overnight one day, pointing Claude to some Figma screens?
+- [ ] Stats/dashboard views for results
+	- when generated, when last editited; title; version?
+	- "completeness
+	- verification coverage: how many of the requirements are covered by acceptance criteria w verifications
+- [ ] "Scope" of such a spec must ultimately be more flexible -- we naively assume single project scope, and total/ultimate completion scope
+
+## some early design sketches of the main flow (terminology and data model out of date; but UI style and layout relevant)
 
+- the very beginning of a new project. The first image is the standard starting UI; below it is an alternate ideation, for the use-case where the kickoff is done by analyzing and harvesting from an existing codebase
+
+  ![](assets/kickoff-screen.png)
+- the first question of the first phase. a compact nav on left (alternate: across the top) indicates the phases; the wide sidebar on the right shows the (approximately) phase-based collection containers for the data we expect (the labels and terminology are wrong here). NOTE also that the question model is still wrong in these earlier designs, where the options provided are exclusive, and there is no free-text option. There is also the chance to "skip question" which I am dubious about, I would prefer the user explicitly why they are skipping (e.g. "i'm not sure enough about this yet"), as part of the free-text
 
-- This is pretty close to your existing layout (albeit your left-hand is a chat + inline questions rather than just questions)
-- This plus adjacent demonstrate a left-hand sidebar where the phase/focus navigation could be
-- This could be used as the ‘initial empty state’ for the chat window
-- We’ll want to think about shifting from a ‘chat-first’ UI mode to a ‘browse spec, with chat on the side to discuss amendments’ mode once a user has created the initial spec – this kind of thing. The idea here being that user could browse requirements/assumptions etc in the main view, and clicking on them would automatically add them as context to the chat
-- Then probably the whole idea of linkages between requirements, assumptions etc?
+  ![](assets/first-question.png)
+- what the main interview roughly looks like, as it develops. the right sidebar is being filled in, so we are further along at thit point.
 
-Welcome any thoughts
-- we naively assume single project scope, and total/ultimate completion scope
+  ![](assets/main-interview.png)
+- a "review" style step, such as we've been imagining for the requirements and the (acceptance) criteria.  each of these might want to be expandable to show in more detail what the requirement is really about
+
+  ![](assets/reqs-minimal.png)
+- a sketch for what the final spec overview might look like
+
+  ![](assets/spec-overview.png)
 
 ### "kickoff" (scope) phase needs two path variants
 

docs/design/image-notes.md

@@ -0,0 +1,10 @@
+## other examples
+
+- an example of a bottom bar with a button: this bottom bar is a good ui pattern for the phase status and "force closure" workflow
+
+  ![](assets/bottom-bar-example.png)
+- ![](assets/knowledge-graph.png)
+- ![](assets/secondary-chat.png)
+  ![](assets/reqs-detailed.png)
+  ![](assets/requirements-approval.png)
+  ![](assets/reqs-overview.png)

drizzle/0006_phase_outcome_closure_basis.sql

@@ -0,0 +1 @@
+ALTER TABLE `phase_outcome` ADD `closure_basis` text;

drizzle/meta/_journal.json

@@ -43,6 +43,13 @@
       "when": 1775710000000,
       "tag": "0005_generic_commitment_graph",
       "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "7",
+      "when": 1775715000000,
+      "tag": "0006_phase_outcome_closure_basis",
+      "breakpoints": true
     }
   ]
 }

memory/PLAN.md

@@ -41,7 +41,7 @@
 4c. **UI foundation: shadcn/ui + Tailwind 4 + AI Elements** `FE-558` `done`
 5. **Observer agent + entity persistence** `FE-537` `done` — I20, I21, I22
 6. **Entity sidebar (read-only)** `FE-538` `done` — I23
-6b. **AI SDK-native chat pivot** `FE-559` `done` — I21↑, I22↑, I23↑; core tools spike proven (A29)
+6b. **AI SDK-native chat pivot** `FE-559` `done` — I21↑, I22↑, I23↑; core tools spike proven
 6b1. **Workspace seam characterization oracle** `done` — I24, I25
     - Purpose: add a client integration harness around the interview workspace before the state-ownership refactor
     - Coverage: initial hydration from persisted turns, same-project refresh stability, observer-result sidebar reactivity, option-selection follow-through
@@ -149,7 +149,7 @@
 
 7b. **Canonical knowledge model foundation + cutover seam** — Introduce canonical `goal` / `term` / `context` kinds, unify durable knowledge storage and cross-kind edges behind the generic seam, and preserve slice 7 coherence through the smallest necessary compatibility projection rather than migration-hardening legacy scratch data. `done`
    - Requirements: → SPEC.md §Requirements #5, #6, #7, #11, #12, #13
-   - Assumptions: → SPEC.md §Assumptions A14, A40, A41
+   - Assumptions: → SPEC.md §Assumptions A14, A40
    - Decisions: → SPEC.md §Decisions D5, D17, D49, D51, D52, D53, D54, D59, D61, D62, D63, D67, D68, D69
    - Candidate invariant goals: canonical knowledge writes/readiness coexist with scope closure during cutover; no new Phase 5/6 slice depends on durable `framing`
    - Invariants to respect: → SPEC.md §Invariants I20, I21, I23, I68, I72
@@ -161,14 +161,20 @@
      - `7b.1` Canonical scope kinds through the generic seam. `done`
      - `7b.2` Generic edge/storage cutover + scope-readiness compatibility projection beyond legacy decision/assumption tables. `done`
 
-8. **Design mode (commitment / exploration)** — Implement the second workflow mode on the new turn and canonical knowledge model after 7b lands, while generalizing the current scope-only proposal/confirmation seam into a shared phase-closing model with deterministic closeability, coarse readiness bands, and explicit closure basis. The interviewer walks design forks; the observer captures decisions, assumptions, new constraints, and emerging requirements against the unified knowledge seam. `not-started`
+8. **Design mode (commitment / exploration)** — Implement the second workflow mode on the new turn and canonical knowledge model after 7b lands, while generalizing the current scope-only proposal/confirmation seam into a shared phase-closing model with deterministic closeability, coarse readiness bands, and explicit closure basis. The interviewer walks design forks; the observer captures decisions, assumptions, new constraints, and emerging requirements against the unified knowledge seam. `in-progress`
    - Requirements: → SPEC.md §Requirements #2, #3, #5, #6, #7, #8
    - Assumptions: → SPEC.md §Assumptions A14, A15, A28, A40
-   - Decisions: → SPEC.md §Decisions D2, D5, D6, D61, D62, D65, D66, D67, D68, D70
+   - Decisions: → SPEC.md §Decisions D2, D5, D6, D61, D62, D65, D66, D67, D68, D70, D71, D72, D73, D74, D75
    - Candidate invariant goals: mode transition preserves interview continuity; design-mode turns produce coherent decision/assumption graph growth on the canonical knowledge seam; phase-closing state separates status, closeability, readiness, and closure basis instead of hidden interviewer authority
    - Invariants to respect: → SPEC.md §Invariants I18, I19, I21, I22, I72, I73
+   - Invariants established: → SPEC.md §Invariants I79, I80, I81, I82, I83, I84, I85, I86
    - Acceptance: after scope closes and slice 7b lands, the interview enters design mode; design turns yield coherent commitments and assumptions on the canonical knowledge layer; the UI projects design status/closeability/readiness; and once the minimum bar is met the user can either accept an interviewer-recommended close or force-close design with persisted closure basis/readiness snapshot
+   - **Observed current state (2026-04-09, tracer bullets 8.1–8.3 + completed phase-close refactor):** confirmed scope closure now projects through a shared workflow state carrying `status`, `closeability`, `readiness`, `closureBasis`, and pending-proposal visibility instead of the old scope-only `open/proposed/confirmed` seam. The next prepared turn after confirmed scope closure now enters `design` automatically, the observer runs against that design turn phase, and the workspace header renders shared workflow summaries for closed scope plus the newly active design phase rather than hardcoding scope-only status copy. Design now also uses the same typed `data-phase-summary` closure seam as scope: the design interviewer can recommend closure, the workflow projects a pending design summary through the shared phase state, confirmation persists design closure, and the next prepared turn enters `requirements`. That same typed confirmation seam now also carries a user-forced design close with visible `closureBasis: user_forced`, so forced-close debt survives refresh/resume and still hands the next prepared turn into `requirements`. The completed phase-close refactor also hardened the seam end to end: close intent moved into explicit shared phase-close commands, force-close availability now projects from one shared workflow-policy seam consumed by both UI and server validation, confirmed `phase_outcome` rows persist durable `closure_basis`, read-side workflow projection trusts that durable phase-outcome field instead of reconstructing provenance from confirmation-turn payloads, `data-confirmation` is now an explicit discriminated command union consumed consistently by the workspace controller and `/chat` request handling, and the remaining user-visible close-command labels, rejection copy, and forced-close summary text now also project from the shared phase-close module instead of being rebuilt inline across layers.
    - **Verification approach**: inner — mode-transition/controller/workflow-state projection tests. Outer — manual design walkthrough covering interviewer-recommended close, user-forced close, and visible carried-debt caveats.
+   - Tracer bullets:
+     - `8.1` Design-mode entry + shared workflow-state projection. `done`
+     - `8.2` Design-phase closure proposal + requirements handoff. `done`
+     - `8.3` User-forced design close + carried-debt projection. `done`
 
 9. **Requirements-review mode** — Synthesize the requirement set from the full canonical knowledge layer, then let the user approve, edit, merge, reject, and add requirements through review turns using the shared phase-closing seam rather than a requirements-only completion bit. This slice assumes the redesigned ontology/graph from 7a + 7b, not the current transitional `framing` seam. `not-started`
    - Requirements: → SPEC.md §Requirements #6, #7, #8, #11, #13