Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .agents/skills/ln-build/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Implement **one** scope card. Beck's red-green-refactor, one cycle, no scope cre

A scope file under `memory/cards/`, an inline scope card from `ln-scope`, or a trivial direct-fix request: $ARGUMENTS

Extract: target behavior / objective, acceptance criteria, verification approach, and (when present) expected touched paths.
Extract: target behavior / objective, acceptance criteria, verification approach, cold-start reads, and (when present) expected touched paths.

Treat the scope card as the next implementation slice inside its containing `memory/PLAN.md` frontier item (or, for dev/tooling/docs work, the named category prefix). The frontier item is the plan-level work item and Linear/branch unit; the scope-card slice is just the current execution step inside it. Unless `ln-plan` has already split the frontier into separate items, do **not** infer a new Linear issue or Graphite branch from scope-card granularity; multiple consecutive slices may land on the same branch — including slices that live in separate scope files but share a frontier.

Expand Down Expand Up @@ -41,6 +41,8 @@ If this is a fresh thread or an unfamiliar area, reload:
3. `HANDOFF.md` if present
4. `docs/archive/PLAN_HISTORY.md` only if the frontier or touched area is still unclear

Let the card's **Cold-start reads** block scope this reload — resolve the specific decision/invariant ids and frontier it names. The numbered list above is the fallback when the card omits Cold-start reads or you need broader orientation. If the card's Cold-start reads turn out to be incomplete or stale (an id it names no longer exists, or you needed a doc it did not list), that is a scope defect — note it and route back through `ln-scope` rather than silently working around it.

Write a 2-4 bullet orientation note naming the containing seam, the frontier item (or dev/tooling concern), any manual verification debt, and the main open risk.
Also name any frontier-level cross-cutting obligations the slice inherits (for example shared mutation-authority rules, side-task/event-substrate semantics, or verification-layer commitments).

Expand Down
29 changes: 28 additions & 1 deletion .agents/skills/ln-scope/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,9 @@ Created: YYYY-MM-DD

### Why one file per concern, not one file for everything

The `memory/cards/` directory is a scoping inbox where multiple agents can deposit independent scope files in parallel without colliding on a single shared file. Each file is the unit of execution context that one `ln-build` invocation consumes.
The `memory/cards/` directory is a scoping inbox where multiple agents can deposit independent scope files in parallel without colliding on a single shared file. Each file is the unit of work one `ln-build` invocation consumes.

The card does **not** inline canonical context — it points to it via [§Cold-start reads](#cold-start-reads). The full execution context is the card *plus* the canonical docs its Cold-start reads enumerate, which `ln-build` reloads on a fresh thread. A card therefore need not be self-contained to be cold-buildable; it must make its required reads explicit. "Free-standing enough for a separate builder thread" means *its Cold-start reads are complete*, not *its content is duplicated* — inlining SPEC/PLAN text into the card duplicates canonical truth and invites drift.

Multiple scope files per frontier are permitted — they represent independent concerns that happen to land on the same branch. They do **not** imply multiple Linear issues or multiple Graphite branches; the frontier item remains the tracker/branch boundary.

Expand Down Expand Up @@ -181,6 +183,19 @@ If you cannot name the containing seam, the governing decision, or the live inva

What is true when this slice is done? Single declarative sentence — observable, testable, no conjunctions.

### Cold-start reads

The canonical context a fresh builder thread must resolve **before** building this card. Pointers, not copies — name the exact ids/paths to load; never restate their content here (that duplicates canonical truth and invites drift).

```
- memory/SPEC.md — decisions / invariants / assumptions: <ids> (e.g. D53-L, A4-L)
- memory/PLAN.md — frontier: <frontier-id>
- HANDOFF.md — <live state this card depends on> (omit if none)
- <topology README / other canonical doc> — <what to read there> (omit if none)
```

This block is the answer to "could a separate builder thread work this card cold?" If you cannot enumerate the reads that make the card resolvable, the card is under-scoped — not the reader under-briefed.

### Boundary Crossings

Every boundary the slice passes through, entry to exit:
Expand Down Expand Up @@ -282,6 +297,18 @@ src/legacy/observer.ts ?

Single sentence: what this work changes for the user, operator, or codebase.

### Cold-start reads

The canonical pointers a fresh builder must resolve before building — ids/paths, not copies.

```
- memory/SPEC.md — <decision / invariant ids> (or None)
- memory/PLAN.md — frontier: <frontier-id> | category concern
- HANDOFF.md — <live state> (if any)
```

If you cannot name what makes this card resolvable cold, it is not settled enough for light mode.

### Acceptance Criteria

```
Expand Down
23 changes: 23 additions & 0 deletions memory/PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,7 @@ The near-term spine has two tracks. The **context-pipeline coverage trio** remai
- `topology-readmes-and-boundaries` — small doc/test hardening when a frontier moves files or exposes a boundary; should remain attached to the frontier when possible rather than becoming an abstract cleanup project.
- `dev-seed-fixtures` — rich, real seed data for local dev / manual / observer testing: the consolidated seed contract, the `npm run seed` loader, and growing/enhancing fixture sets (Bilal-port + legacy). Its semantic curation mutation slice is folded into / blocked by `role-safe-graph-mutations`; ongoing seed-data maintenance remains low-conflict.
- `dx-introspection-live` — DX follow-on to `dx-feedback-loops`: harden the four-role `.fixtures/` topology + `--cwd` launch (D70-L), unify dev gating under `BRUNCH_DEV` and wire the dormant introspection extension into the real TUI (D71-L), and make introspection conversational (A26-L). Three sequenced slices; ready for a scoping thread. Low-conflict with the product trio; touches `.fixtures/`, `src/app/`, `src/dev/`, `src/.pi/extensions/introspection/`.
- `web-design-system-port` — **bounded feature; `Certainty: earned`; done 2026-06-09.** Ported the prior trunk's restrained design system (tokens + card primitives) into `src/web` and re-skinned the three existing read-only views, retiring the agent-invented "warm brunch" aesthetic (D72-L). Read-only presentation only; independent of the POC delivery spine and the context-pipeline trio. Execution record: `memory/cards/web-design-system-port--restyle.md`.

### Horizon

Expand Down Expand Up @@ -508,6 +509,27 @@ The near-term spine has two tracks. The **context-pipeline coverage trio** remai
- **Traceability:** D4-L, D16-L, D19-L, D20-L, D52-L, D61-L, D62-L, D63-L / I1-L / A4-L, A14-L.
- **Design docs:** `.fixtures/seeds/bilal-port/README.md`; `docs/design/GRAPH_MODEL.md`; `docs/praxis/manual-testing.md`.

### web-design-system-port

- **Name:** Web client visual design-system port
- **Linear:** unassigned
- **Kind:** bounded feature (web presentation)
- **Certainty:** earned — the target design exists and works in `../brunch/src/client`; the closure is *materialize the port + delete the invented aesthetic*, not retire an unknown. (Project default is `proving`; this frontier overrides because the design is known.)
- **Status:** done (all three cards landed 2026-06-09; `memory/cards/web-design-system-port--restyle.md`)
- **Objective:** Replace the agent-invented "warm brunch" web aesthetic with the prior trunk's restrained design language (D72-L). Two materializations and one deletion: (a) **tokens** — port the token system into `src/web/styles.css` (Inter + Geist Mono; `ink/sub/hint/rule/wash/tint` ramp + link/plane accents; 11–16px type scale; `--shadow-card` family); (b) **primitives** — copy `DrawerCard`, `KindBadge`, `CountBadge`, `RefBadge` into a new `src/web/components/`, adapted from the old `KnowledgeKind` knowledge-card pattern to this trunk's `NodeKind`/`NodePlane` with a plane-organized accent map; (c) **re-skin** the three existing views (`WorkspaceChrome`, `GraphOverviewPanel`, `SessionPanel`) as a *style + component-pattern port of the views we have* (scope correction, user 2026-06-09) — preserving behavior except invented dead scaffolding — and delete the warm gradients, `backdrop-blur`, oversized radii/shadows, translucent surfaces, and wide-tracked uppercase labels. The non-functional "Focus node" placeholder (never called `graph.nodeNeighborhood`) was removed; the "Edge categories" summary was kept (restyled, user finds it useful).
- **Why now / unlocks:** The current web UI's visual language was invented wholesale by the agent that built it and does not match the product's established look. Realigning now keeps the read-only observer surface presentable for manual/observer testing and stops the invented aesthetic from being copied forward into future web views. Independent of the delivery spine — touches no data, RPC, query, subscription, or routing code.
- **Acceptance:**
- `src/web/styles.css` carries the ported token system; no warm-palette tokens, body gradients, or `backdrop-blur` remain.
- `src/web/components/` holds the ported primitives; the accent map is exhaustive over `NodePlane`, with a compile-time `satisfies Record<NodePlane, PlaneAccent>` guard, while reference-code labels stay canonical via `NODE_KIND_METADATA` + `kindOrdinal` (I43-L).
- The three views render in the ported language: quiet metadata-row chrome, `plane / kind`-grouped node cards with canonical reference codes (`NODE_KIND_METADATA` labels + `kindOrdinal`) and plane-accented `KindBadge`/`CountBadge`, plain session card. The "Edge categories" summary is kept (restyled as `RefBadge` chips); the non-functional "Focus node" placeholder is removed.
- Read-only contract preserved: no change to queries, RPC client, subscriptions, routes, or projection inputs.
- Existing web tests preserved; only the two Focus-node assertions removed; `npm run verify` is green (28 web tests, oxlint type-aware clean, build clean).
Comment on lines +520 to +526
- **Verification:** Inner — `npm run verify` (oxlint type-aware + oxfmt + vitest + build); update `src/web/app.test.tsx` and any view tests that assert retired class names / `aria-label`s. Outer — manual browser check of `/` and `/spec/$specId` against a seeded spec (`npm run seed` then launch web mode) to confirm the chrome, kind-grouped graph cards, and session panel match the prior trunk's look.
- **Topology materialization:** Stays inside `src/web` per D52-L (`web/` is a standalone build target; must not read SQLite/Pi RPC/JSONL directly). New `src/web/components/` owns ported primitives; only `src/web` imports from it. Component/style patterns are copied (not shared) from `../brunch`. Exception to `sourcing: strip-or-build`: the webfont packages `@fontsource-variable/inter` + `@fontsource-variable/geist-mono` were added with user approval (2026-06-09) — the fonts are the most visible design token; the "no new packages" line was not a hard rule.
- **Cross-cutting obligations:** Pre-release posture (`migration: free-rewrite`) — discard the invented design freely; do not preserve it for compatibility. Read-only invariant (D33-L one-writer/many-observer): this frontier adds no web write paths. Node reference codes must use the canonical `NODE_KIND_METADATA` projection (D62-L), not a web-local relabeling.
- **Traceability:** D10-L, D52-L, D62-L, D72-L / I43-L, I39-L.
- **Design docs:** `../brunch/src/client/index.css`, `../brunch/src/client/components/drawer-card.tsx`, `../brunch/src/client/components/knowledge-card.tsx` (reference source — separate checkout, not imported).

## Recently Completed
- 2026-06-09 `role-safe-graph-mutations` — Done: retired the remaining public `commitGraph` residue, extracted the shared mutation planner/writer out of `CommandExecutor`, and completed the last boundary migration so dev curation now exposes `dev.graph.mutateGraph` with role-named create-edge ops plus projected node-code / selected-spec edge-id resolution. Follow-up closure on the same frontier: reconciled the remaining product probes and current docs to the canonical `mutateGraph` / `mutate_graph` grammar, explicitly marked the checked-in 2026-06-05 fixture-curation artifact as historical pre-migration `commit_graph` evidence, and added role-named edge schema coverage across the Pi tool and dev RPC boundaries. Verified: `npx vitest run src/rpc/handlers.test.ts src/app/brunch.test.ts src/probes/fixture-curation-loop.test.ts src/probes/propose-graph-commit-proof.test.ts src/graph/mutate-graph-edge-schema.test.ts` and `npm run verify`.

Expand Down Expand Up @@ -549,6 +571,7 @@ nodes:
probes-and-transcripts-evolution [parallel] continuous evidence substrate
topology-readmes-and-boundaries [parallel] attach-to-frontier topology hardening
dev-seed-fixtures [parallel] rich seed data substrate for dev/observer testing
web-design-system-port [done · earned] ported prior-trunk tokens + card primitives into src/web; retired invented warm aesthetic; read-only, no spine deps

edges:
graph-tool-resilience -[hard]-> capture-response-to-graph
Expand Down
Loading
Loading