@north-light/crouter 0.3.228 → 0.3.230

package/dist/builtin-memory/design/guide.md

@@ -1,57 +0,0 @@
----
-kind: knowledge
-when-and-why-to-read: When writing an architecture or interface design, this knowledge should be read so the design closes the consequential structure from grounded evidence without dictating cheap implementation detail.
-short-form: Use when producing a design — grounding, decision depth, the artifact core, conditional detail, and evidence probes.
-rationale: >-
-  Carries the shared design method and artifact shape used by design-kind nodes and the optional /dev:design front door. Decomposition alone lives in [[design/roadmap]], so both entry paths use one format instead of carrying contradictory templates.
----
-
-# Designing a change
-
-Ground the design in every applicable requirement, specification, and current code path. When the blast radius is unclear — what the change touches, who depends on it, or what constrains its shape — use `explore` scouts to map it before writing, and draw the constraints from evidence rather than an assumption.
-
-Scale depth with reversal cost, the number of owners, and operational burden. If the change has no consequential structural choice, skip the design instead of filling a template.
-
-Resolve every consequential, expensive-to-reverse choice; never hand one to the implementer. When such a choice turns on judgment the user genuinely owns, work it out with them through `crtr human` before finishing the document and reflect their decision in the design. Leave cheap local choices to implementation.
-
-A question that only runtime evidence can answer is not a paper choice. Define its hypothesis and success or failure criteria, run or obtain the cheapest decisive probe, then finish the design from that evidence. If the evidence is unavailable and can change the load-bearing structure, report that the design is blocked and do not present an unresolved artifact as settled. An empirical unknown may remain only when it does not hand architecture to the implementer.
-
-Write the design to `$CRTR_CONTEXT_DIR/design-<subject>.md`. Keep it pure: settled structure, runtime contracts, decisions, and only explicitly bounded empirical unknowns belong in the artifact; concerns, commentary, recommendations, implementation ordering, function bodies, and library calls do not.
-
-## Required core
-
-### Context and decision frame
-
-Name the governing inputs, relevant current state, problem, goals, plausible non-goals, and non-negotiable constraints. Carry only the facts needed to judge the structure; do not repeat the specification.
-
-### Proposed design
-
-Orient the reader to the chosen structure, then name component or subsystem ownership, responsibilities, boundaries, and sources of truth. Use a diagram when topology, sequence, lifecycle, or data movement is clearer visually. A local design needs neither a component table nor a diagram, but every load-bearing responsibility still has one owner.
-
-### Contracts and runtime behavior
-
-Include the seams independent implementers must preserve: interface meaning and compatibility, invariants, state transitions, data movement, ordering, idempotency, retention and deletion, and success, partial-success, failure, degraded, and recovery behavior. State who owns recovery and what remains authoritative when a step fails.
-
-Use prose, diagrams, or compact examples according to the ambiguity. A targeted schema, algorithm, or type sketch belongs here when it is the expensive shared decision; otherwise link the authoritative formal contract instead of copying it.
-
-### Decisions and alternatives
-
-For each consequential choice, state the chosen option, the forces that made it consequential, credible alternatives, why the choice won, and what it closes off. Omit obvious and cheap choices.
-
-## Conditional detail
-
-Add a section only when its trigger applies:
-
-- **Persistent or shared state:** entities, relationships, ownership, lifecycle, consistency, retention, and deletion.
-- **Migration or shared compatibility:** compatibility states, authority at each state, transition criteria, partial-failure recovery, stop or rollback conditions, and the destructive-cleanup boundary.
-- **Security, privacy, or trust:** trust boundaries, authorization, secrets, exposure, deletion, and audit behavior.
-- **Capacity, performance, or cost:** the required envelope and the structural choices it forces.
-- **Operations:** detection, observability, on-call ownership, degraded modes, and recovery when they affect architecture.
-- **Empirical unknown:** the hypothesis, probe, criteria, and why the unknown does not block the settled structure.
-- **Cross-team or durable review:** status, decision owner, affected owners, approvers, and child-design links.
-
-## Design direction
-
-Use **top-down, interface-first** design when integration seams are the hard or expensive part. Fix the contracts, then place responsibilities behind them. Use **bottom-up, primitives-first** design when a novel data structure, algorithm, or performance constraint determines the component model above it.
-
-For a design large enough to split across nodes, read [[design/roadmap]].

package/dist/builtin-memory/design/roadmap.md

@@ -1,21 +0,0 @@
----
-kind: knowledge
-when-and-why-to-read: When a design is large enough that independent surfaces could be designed in parallel, this knowledge should be read so sub-designs compose across written contracts instead of inventing incompatible assumptions.
-short-form: Use when deciding whether a design splits into sub-designs, and how to contract and integrate them.
-gate: {kind: design}
-rationale: >-
-  Carries decomposition and integration only. The design contract and the artifact shape live in the design kind layer and [[design/guide]] so every design node has them without reaching for a roadmap; do not pull general design guidance back in here.
-surfaces:
-  - on: boot
-    at: preview
----
-
-# Decomposing a design for parallel work
-
-Decompose only when settled contracts expose genuinely independent surfaces with non-overlapping responsibility and ownership, and the design is large enough that parallel work materially improves intelligence, productivity, or elapsed time after synthesis cost. A long but tightly coupled design stays with one base agent across yields so one mind owns its coherence.
-
-Before delegating, write the shared interface contracts in `$CRTR_CONTEXT_DIR/design-contracts.md`. Fix the overall structure, source-of-truth boundaries, interaction meaning, invariants, and assumptions every sub-design must preserve. Give that absolute path, the overall orientation, the sub-design scope, and the governing constraints to every child.
-
-Each child owns one component, subsystem, or interaction surface end to end. It follows [[design/guide]] and includes only the conditional detail its surface triggers. It writes `design-<component>.md` in its context directory and reports the absolute path.
-
-After the sub-designs land, synthesize one design at `$CRTR_CONTEXT_DIR/design-<subject>.md`; do not concatenate them. Check each shared contract from both sides, reconcile names and data semantics, close responsibility gaps and overlaps, and walk the cross-boundary success and failure flows before declaring the integrated design settled.

package/dist/builtin-memory/development.md

@@ -1,113 +0,0 @@
----
-kind: knowledge
-when-and-why-to-read: When shaping or reshaping a build roadmap — choosing a development style, selecting a phase skeleton, or setting exit criteria for a software goal — this knowledge should be read so each phase matches the goal's risk and clears an objective done-bar before downstream work compounds an upstream mistake.
-short-form: Use when shaping or reshaping a build roadmap — choosing a development style, selecting a phase skeleton, or setting exit criteria for a software goal.
-gate: {kind: developer}
-surfaces:
-  - on: boot
-    at: preview
----
-
-# Development Playbook
-
-## Development Styles
-
-Pick one style as your primary frame before you write phases. Each fits a different risk/knowledge profile.
-
-**Vertical slice.** Start with the thinnest path end-to-end — one real request touching every layer — before thickening any of them. Use when the integration seams are the riskiest unknowns and a working skeleton keeps the team aligned on "done". Fits new features where you know what to build but not how the layers will talk.
-
-**Spike-then-harden.** Build a throwaway prototype of the one thing you don't understand, validate the approach, then discard it and build it properly. Use when there is a genuine technical unknown (unfamiliar API, unclear performance profile, novel algorithm) that blocks everything else. The spike is not the deliverable — the hardened version is.
-
-**Strangler-fig.** Introduce a new implementation path alongside the old one, route traffic to it incrementally, and delete the old path when migration is complete. Use for migrations and rewrites where you cannot replace atomically and must maintain a working system throughout.
-
-**Bottom-up.** Build foundational primitives first; compose them into higher-order behaviour last. Use when building a library or shared infrastructure where the interface must be right before consumers are written. Risky if the top-level requirements aren't settled — you may build the wrong primitives.
-
-**Decision rule:** if the riskiest unknown is technical feasibility, spike first. If it is integration correctness, vertical slice. If it is a live-system migration, strangler-fig. If it is a foundational library with settled requirements, bottom-up. Default to vertical slice for ambiguous new feature work.
-
----
-
-## Roadmap Shapes by Scenario
-
-These are concrete phase skeletons. Adapt names and granularity; don't add phases that serve no exit criterion.
-
-### New feature
-1. **Explore** — map the affected subsystems, identify entry points and constraints, and report the absolute path to the exploration artifact.
-2. **Spec** — define the interface, behavior, and acceptance criteria, then report the absolute path to the spec.
-3. **Plan** — decompose the spec into file-level tasks with dependency order, then report the absolute path to the plan.
-4. **Vertical slice** — implement the thinnest end-to-end path; validate it works before widening.
-5. **Harden** — fill out the remaining logic, edge cases, error paths.
-6. **Review** — non-implementer critique pass on the whole surface.
-7. **Fix** — action review findings.
-8. **Validate** — end-to-end confirmation against spec's acceptance criteria.
-
-### Refactor
-1. **Characterise** — pin current behaviour with evidence that holds before and after: whatever proof the repo's testing stance calls for, else a recorded runtime probe.
-2. **Plan safe steps** — decompose into the smallest semantics-preserving transformations; each step independently reviewable.
-3. **Transform** — apply each step, re-checking the characterisation evidence after each one.
-4. **Verify equivalence** — confirm no observable behaviour changed; review for unintended scope drift.
-
-### Bug-fix campaign
-1. **Reproduce** — produce a reliable reproduction case for each bug; nothing proceeds without one.
-2. **Root cause** — trace the defect to its source; group bugs sharing a root cause.
-3. **Fix** — implement the minimal correct change; no opportunistic cleanups in the same commit.
-4. **Prove the fix** — as the repo's testing stance calls for: a regression test where it keeps them, otherwise the reproduction case run against the fix.
-5. **Validate** — confirm the reproduction case no longer triggers.
-
-### Greenfield
-1. **Explore/research** — understand the problem domain, constraints, and comparable systems.
-2. **Spec** — define the interface and top-level behaviour in enough detail to plan.
-3. **Architecture decision** — commit to the structural shape and report the absolute path to the architecture artifact.
-4. **Spike** (if technical unknowns exist) — validate the risky piece before building around it.
-5. **Bottom-up build** — primitives first, then composition; validate each layer before building on it.
-6. **Integration** — assemble layers; validate end-to-end.
-7. **Review + fix** — critique full surface; action findings.
-
-### Migration / upgrade
-1. **Inventory** — enumerate every call site, every affected API, every integration point.
-2. **Compatibility plan** — decide the strangler-fig boundary; define the coexistence period.
-3. **New path** — implement the replacement without removing the old.
-4. **Route incrementally** — shift traffic or call sites in small batches; validate after each batch.
-5. **Delete old path** — only after full migration is confirmed.
-6. **Validate** — confirm nothing regressed; run the full integration surface.
-
-### Performance work
-1. **Baseline** — measure and record current performance numbers; define the target.
-2. **Profile** — identify the actual bottleneck; do not optimise before you know where the heat is.
-3. **Fix the bottleneck** — targeted change only; no speculative optimisation.
-4. **Measure again** — confirm the target is met against the same baseline method.
-5. **Review** — check that the fix doesn't introduce correctness or maintainability regressions.
-
----
-
-## Setting Exit Criteria per Phase
-
-Every phase needs a concrete, evaluable condition that tells you it is genuinely done — not "looks good" or "mostly working". Write exit criteria when you write the phase, not after.
-
-- **Explore:** a context doc exists that accurately describes the relevant subsystem; a reviewer or subsequent spec agent should not need to re-explore to write the spec.
-- **Spec:** acceptance criteria are concrete enough that an implementer can derive test cases from them without ambiguity.
-- **Plan:** every task maps to identified files; no task says "figure out how"; dependencies are explicit.
-- **Implementation:** the code compiles, existing tests still pass, and the acceptance criteria from the spec are provably met — by a validation agent's check, or by tests where the repo's testing stance calls for them.
-
-How much of that proof is new test coverage is the repo's call, never this playbook's: follow its `testing-stance` memory, and read [[testing]] when it has none.
-- **Review:** a non-implementer has read the diff once and produced a report; every Critical, Major, or acceptance-violating finding is fixed, always. A Minor or cosmetic finding that doesn't affect acceptance is fixed when the fix is net-neutral-or-simpler, or else closed with a one-line reason. The gate is met by that one pass — never by re-reviewing until the reviewer reports nothing, which is an asymptote, not a bar.
-- **Validation:** end-to-end confirmation against the spec's acceptance criteria passes in the real runtime, not just in isolation.
-
-If you cannot write a concrete exit criterion for a phase, the phase is underspecified — split it or spec it further before adding it to the roadmap.
-
----
-
-## The Build-Cycle Discipline
-
-This is the delegation pipeline from spec to shipped, with the coupling that makes it rigorous.
-
-**Spec → Plan.** The plan agent receives the spec as input; it does not re-derive requirements. If the spec is ambiguous, the plan agent reports the ambiguity — the orchestrator resolves it and re-delegates, not the plan agent by guessing.
-
-**Plan → Implement (parallel where safe).** Tasks with disjoint file sets run concurrently. Before spawning parallel implementers, verify file-level independence; if two tasks touch the same file, serialize them. Every implementation agent receives: the goal in one sentence, its specific task and done condition, the relevant context files by path, and the e2e validation recipe.
-
-**Implement → Review (non-implementer).** The reviewer receives the full diff and the relevant context docs. It produces a report sorted by severity — Critical, Major, Minor — and does not propose fixes inline. One review pass per implementation batch; do not re-review after fixes, validate instead.
-
-**Review → Fix.** The orchestrator triages the report: false positives are dismissed, Critical/Major and acceptance-violating findings get fix agents, and cosmetic or out-of-scope findings are closed with a one-line reason instead of fixed or left open. Fix agents read the findings, understand the code, and implement the correct fix — they are not given line-by-line instructions. Do not spawn a second reviewer after fixes land.
-
-**Fix → Validate.** Validation confirms the thing works end-to-end in the real runtime by executing acceptance criteria, targeted tests, or a real behavior probe. It produces evidence rather than another opinion on the artifact. If validation fails, spawn fix agents against the observed failure and repeat that check; do not advance until it passes.
-
-**When review or validation exposes a phase gap** — a wrong assumption in the spec, a plan that missed a dependency, an implementation that reveals the design is wrong — re-delegate the affected phase rather than patching forward. A corrected spec or plan paid for in one extra wake costs less than an implementation built on a bad foundation.

package/dist/builtin-memory/plan/guide.md

@@ -1,53 +0,0 @@
----
-kind: knowledge
-when-and-why-to-read: When writing an implementation plan from approved requirements or design, this knowledge should be read so a fresh implementer can locate each change, respect its dependencies, and prove the requested behavior without reconstructing the repository.
-short-form: Use when producing an implementation plan — grounded units, dependency order, conditional transitions, and acceptance proof.
-rationale: >-
-  Carries the shared planning method and artifact shape used by plan-kind nodes and the optional /dev:plan front door. The old entry paths repeated broad affected-area and verification categories while leaving files, dependencies, and proof ambiguous.
----
-
-# Planning a change
-
-Ground the plan in the current repository and every applicable approved requirement, specification, and design. When the blast radius is unclear — what the change touches, who depends on it, or what breaks — use `explore` scouts to map it before writing, and draw the implementation surfaces from evidence rather than an assumption.
-
-Treat the approved inputs as fixed. Resolve cheap local implementation detail when the plan needs it. When repository evidence contradicts the design or exposes an expensive-to-reverse choice, return that gap to design instead of silently deciding it in the plan.
-
-Hold scope to the approved outcome and the implementation work it necessarily requires. Speculative features, future extensibility, adjacent cleanup, and other merely plausible additions stay out. Ask the user only when an approved input is genuinely ambiguous or the requested outcome cannot be completed without a scope decision.
-
-Write the plan to `$CRTR_CONTEXT_DIR/plan-<subject>.md`. Keep it pure: approved inputs, implementation units, dependencies, and acceptance proof belong in the plan; concerns, commentary, recommendations, decision history, and live progress do not. Keep live execution state in a separate record when the work needs one.
-
-## Inputs and implementation approach
-
-Link every applicable approved input, state the implementation strategy in one paragraph, and point to the existing repository patterns the work follows. If no design exists because the structure is local and cheap to reverse, state that in one clause rather than manufacturing one. Repeat a scope boundary only when the linked inputs leave it easy to misread.
-
-## Ordered implementation units
-
-Each unit states:
-
-- **Outcome:** the independently meaningful result.
-- **Change:** what must become true, without pseudocode or pasted source.
-- **Surfaces:** exact current files, symbols, callers, tests, migrations, generated artifacts, or operational assets.
-- **Dependencies:** prerequisite units and edit-surface ownership constraints.
-- **Proof:** the narrowest deterministic or runtime evidence that establishes the outcome.
-
-Group units into phases only when a phase has one coherent outcome and proof gate. Derive parallel lanes from dependency and edit ownership, not labels such as frontend and backend. Start with a thin central end-to-end slice when it can exercise the real integration path. Put an implementation unknown before routine polish when a working probe can retire it.
-
-## Acceptance proof
-
-Map every acceptance criterion to the unit or final runtime check that proves it. Include integration and manual runtime evidence when static checks cannot establish the behavior. A phase gate is a safe stopping point; dependent work does not proceed through a failed gate.
-
-## Conditional units
-
-Add units only when their trigger applies:
-
-- **Migration:** source of truth, compatible reader and writer states, backfill, reconciliation, cutover, observation, reversal, and old-path deletion.
-- **Rollout:** staged exposure, deployment order, stop criteria, monitoring, rollback, and adoption proof.
-- **Operational adoption:** docs or runbooks, alerts, support or on-call handoff, prevention of new legacy use, and decommissioning.
-- **Bulk transformation:** one common mechanism and proof gate plus an explicit queue for judgment-heavy exceptions.
-- **Long or concurrent execution:** a separate live record with the current phase, remaining unknown or blocker, last passed proof, and commit, PR, or deploy evidence. Do not mutate the approved plan into a progress log.
-
-## Plan depth
-
-Scale detail with cross-cutting impact, dependency complexity, interruption risk, and proof difficulty. A familiar one-file change needs no plan. Keep units small enough to review, reject, or reverse, but do not fragment a coherent outcome into line-edit chores.
-
-For work that genuinely needs independent part-plans, read [[plan/roadmap]].

package/dist/builtin-memory/plan/roadmap.md

@@ -1,27 +0,0 @@
----
-kind: knowledge
-when-and-why-to-read: When choosing between a flat plan and a decomposed one, or synthesizing part-plans into an index, this knowledge should be read so a planning effort splits only where independent execution repays the synthesis it costs.
-short-form: Use when deciding whether a planning effort splits into part-plans, and how to synthesize them into one index.
-gate: {kind: plan}
-rationale: >-
-  Carries plan shape and decomposition only. The implementation-unit contract lives in [[plan/guide]] so every planner can use it whether or not the effort ever needs a roadmap; do not pull generic planning guidance back in here.
-surfaces:
-  - on: boot
-    at: preview
----
-
-# Plan shapes and the decomposition decision
-
-Every planning effort produces either one flat plan or an index with part-plans. Choose decomposition for worthwhile parallel planning, not raw size: a flat plan can span many yields, while part-plans add delegation and synthesis cost that independent slices must repay.
-
-## Choosing a shape
-
-Use a **flat plan** when one coherent owner can map the work at consistent unit granularity. It follows [[plan/guide]] in one file.
-
-Use a **decomposed plan** when settled dependency edges expose slices that can be planned independently, their edit ownership does not overlap, and the effort is large enough that parallel work materially improves intelligence, productivity, or elapsed time. A frontend/backend distinction alone is not a decomposition trigger when both sides still share an unsettled seam or edit surface.
-
-Produce a navigable index and delegate each slice to a `plan`-kind child with the approved spec and design, explicit scope, dependencies, and ownership boundary. A slice goes to a `plan` sub-orchestrator only when it independently passes the same parallelism threshold; a long sequential slice stays with a base child across yields.
-
-Each part-plan follows [[plan/guide]]. The index links every part-plan and carries a lane table with each plan, its outcome, dependencies, ownership boundary, and proof gate. It also maps every acceptance criterion to the responsible part-plan or a final cross-lane runtime gate. Unit detail stays in the part-plans.
-
-After the part-plans land, synthesize the index before declaring done. Resolve file and symbol ownership conflicts, align names and phase gates, fill integration gaps, confirm the dependency graph permits every claimed parallel lane, and prove that part-plan and cross-lane gates cover the full approved outcome. Do not duplicate part-plan units in the index.

package/dist/builtin-memory/spec/guide.md

@@ -1,53 +0,0 @@
----
-kind: knowledge
-when-and-why-to-read: When exploring, eliciting, or writing a specification, this knowledge should be read because the outcome has to be developed with the user before it is pinned down, and downstream design and planning then need it settled without avoidable questions or ceremony.
-short-form: Explore openly with the user, converge on what they chose, then write a right-sized behavioral contract a downstream reader can use without guessing.
-rationale: >-
-  Specification quality and elicitation guidance lived inside an always-loaded spec persona while the lightweight /spec command had almost none, leaving agents to choose between a vague one-shot and a fixed discovery workflow. Spec writers also promoted plausible nice-to-haves into requirements without asking, silently expanding the requested work. Every remaining lever then pointed at convergence — one interpretation reflected back, questions minimized, elicitation stopped as soon as no answer would change the contract — so the agent transcribed the request instead of developing it. The exploration is about the solution — challenging the user's premise is available when something genuinely does not fit, never a required move.
----
-
-# Writing a specification
-
-A specification settles **what outcome and behavior are required**. It is not an architecture document or an implementation plan. Its depth follows the stakes and unresolved intent: a small reversible change may need a few paragraphs; a consequential product surface may need collaborative discovery and separate design.
-
-## Explore before you converge
-
-Take the request at face value and put the openness into what it could be. Understand what the user is trying to achieve and why now, then develop the possibilities with them: a specification is the output of a finished exploration, and the first shape anyone thinks of is rarely the best one available.
-
-Develop a few genuinely different directions rather than enumerating shallow variants, and push each one several steps — what changes, what that makes possible next, what it looks like once it exists. Moves that open a direction: remove a constraint everyone assumed; change who or what is served; do materially less than asked and see what survives; ask what happens if nothing changes at all. Where the surrounding system or prior art would feed the thinking, read for it while you think, not as a validation pass afterward.
-
-Bring these to the user as live options, in plain language, with what each buys and closes off. Do not open with objections, feasibility verdicts, or a recommendation, and do not pre-reject an unusual but coherent direction — nothing is committed until the user picks, so divergence is free. If something in the request genuinely does not fit what they are trying to achieve, say so once; questioning their premise is not the job.
-
-Converge when the user has chosen among live options and what remains is detail.
-
-## Elicit without interrogating
-
-Investigate before asking. Read the request, relevant code and documents, and already-settled decisions first. A fact available from the project is not a question for the user; intent never is such a fact.
-
-Reflect a concrete interpretation back so the user can confirm or correct it. Resolve the uncertainty whose answer could most change behavior, scope, or acceptance. When a decision really belongs to the user, give them a focused question with a proposed default or concrete options; use one decision or one small coherent set rather than a questionnaire.
-
-Spend attention where judgment is load-bearing, not where detail is merely available. Keep settled points moving and fold each answer into the specification as current truth. Once converged, stop eliciting when another answer would not materially change the behavioral contract. Explicit approval is warranted when the user is co-authoring the document or the remaining decision is consequential; ordinary reversible work does not need a ritual approval loop.
-
-## Commit only what the user chose
-
-Exploration is unbounded; the document is not. What you explored and the user did not choose stays out — speculative features, future extensibility, adjacent cleanup, and other merely plausible additions are not requirements just because they came up. The bar is not smallness for its own sake: nothing enters the specification without the user's assent.
-
-When something seems likely desirable but is not explicitly or implicitly required by the request, ask the user whether to include it through `crtr human` before finishing the specification (`crtr human send -h`), wait for their answer, and make the resulting boundary explicit. Do not hide the addition in an assumption, recommendation, or optional requirement.
-
-## The finished specification
-
-A downstream reader should be able to understand the required outcome and produce a design or plan without inventing intent. Include the dimensions that matter for this request rather than forcing a section template:
-
-- the user, caller, or system being served and the intended outcome;
-- observable behavior and experience;
-- scope and non-goals;
-- consequential constraints and settled decisions;
-- relevant interfaces, states, and transitions;
-- failure behavior, boundary conditions, and edge cases;
-- acceptance scenarios that make success observable.
-
-Implementation detail belongs only where it constrains the outcome. A finished specification has no unresolved question that would force downstream work to guess; intentionally deferred, non-blocking questions are named as such.
-
-Before handing it off, read it once as a stranger: remove placeholders and contradictions, resolve wording with two plausible interpretations, confirm the scope is coherent enough to plan, and ensure every acceptance signal can be observed. Split independent outcomes rather than hiding them in one oversized document. Fix the artifact in place rather than creating a review log.
-
-For a specification effort that genuinely needs separate discovery, design, and requirements work across nodes, read [[spec/roadmap]]. For the qualities of individual requirements and the complete requirements artifact, read [[spec/requirements]].

package/dist/builtin-memory/spec/requirements.md

@@ -1,29 +0,0 @@
----
-kind: knowledge
-when-and-why-to-read: When writing or evaluating requirements, this knowledge should be read because implementation and validation need one complete behavioral contract rather than behavior scattered across design prose or silently filled in by the planner.
-short-form: Write complete, atomic, observable, testable requirements; use formal templates only when they make a conditional behavior clearer.
-rationale: The requirements persona made EARS mandatory and omitted behavior already stated by the design, which could produce a gap list instead of the complete behavioral contract downstream work needs.
----
-
-# Writing requirements
-
-Requirements state the behavior and constraints the finished system must satisfy. The requirements artifact is the complete behavioral contract: a design may remain normative for structure, but required external behavior must not be recoverable only by inference from design prose. Requirements are not architecture choices, implementation tasks, or a list containing only what the design forgot to say.
-
-A good requirement is:
-
-- **necessary** — it protects the intended outcome or an explicit constraint;
-- **atomic** — one independently satisfiable behavior rather than several joined obligations;
-- **unambiguous** — its actors, conditions, and result have one reasonable interpretation;
-- **observable and verifiable** — a user, caller, operator, or test can determine pass or fail;
-- **bounded** — relevant triggers, states, limits, and failure conditions are explicit;
-- **traceable** — its reason or source in the specification or approved design is identifiable;
-- **feasible** — known technical or policy constraints do not make it impossible, and unresolved feasibility is explicit;
-- **implementation-neutral** — it specifies the result unless a particular mechanism is itself a constraint.
-
-Use direct declarative prose by default. EARS (`WHEN`, `WHILE`, `IF`, `WHERE` … `SHALL`) is useful when a trigger, state, or optional feature would otherwise be ambiguous; it is a clarity tool, not a required dialect. Acceptance scenarios can make representative cases concrete, but examples do not replace the general rule they illustrate. Use stable identifiers when another artifact needs to trace requirements individually.
-
-Cover the normal path and every relevant alternate state, failure, boundary, permission, and lifecycle transition. “Relevant” is a judgment about the specified outcome, not a checklist invitation to invent features.
-
-Never repair a missing product or design decision by guessing. Record the exact gap and return it to the owning specification or design artifact. A draft may expose such gaps; a finished requirements handoff has no unresolved gap that would change implementation behavior.
-
-Review the set in both directions before handoff: every required outcome has corresponding requirements, and every requirement serves a stated outcome or constraint. Split compound obligations, remove design and task detail, and rewrite anything a tester could not evaluate without asking what it means.

package/dist/builtin-memory/spec/roadmap.md

@@ -1,36 +0,0 @@
----
-kind: knowledge
-when-and-why-to-read: When a specification effort contains independent discovery, design, or requirements surfaces large enough for worthwhile parallel work, this knowledge should be read because the handoffs must preserve one settled contract without turning sequential reasoning into coordination ceremony.
-short-form: Orchestrate a specification only for worthwhile parallel work, using canonical artifacts rather than conversation context for handoffs.
-gate: {kind: spec}
-rationale: The prior roadmap required every large specification to follow exact stages, fresh-window yields, fixed delegation, and user approval gates; the resulting process treated ceremony as the quality bar instead of the clarity of the finished contract.
-surfaces:
-  - on: boot
-    at: preview
----
-
-# Orchestrating a specification
-
-Use a roadmap when settled boundaries expose independent specification work that can proceed concurrently and the effort is large enough that parallel execution materially improves intelligence, productivity, or elapsed time after synthesis cost. Multiple sequential phases, consequential user collaboration, or work that needs several context windows stay with one base spec writer across yields. When one writer can settle the request coherently, read [[spec/guide]] and produce one right-sized specification.
-
-## Choose only the phases the work needs
-
-**Shape** establishes the canonical statement of intent: who or what is served, the intended outcome, scope and non-goals, and consequential decisions. The spec owner investigates and elicits according to [[spec/guide]]. Shape is ready for handoff when a designer or requirements writer can proceed without inventing product intent.
-
-**Design** is a separate phase only when structural choices constrain the behavioral contract or downstream plan. Delegate a bounded architecture to a base `design` node; use a design orchestrator only when its own independent surfaces make parallel design worthwhile. The design artifact records approved structure and interfaces; it does not replace the specification's outcome or behavioral contract.
-
-**Requirements** turns the canonical specification and any approved design into the complete behavioral contract. For a multi-phase effort, delegate this to a fresh `spec/requirements` node and have it read [[spec/requirements]]. The requirements writer receives the canonical artifacts, not the originating conversation, so it can detect what the documents fail to say without losing behavior that was already settled.
-
-The dependency is shape → optional design → requirements. A phase exists because its output is needed by the next one, not because every specification must pass through a fixed checklist.
-
-## Resolve gaps through the owning artifact
-
-An independent reader exposes omissions; it does not decide product intent on the spec owner's behalf. When design or requirements finds an implementation-changing gap, bring the owning specification or design artifact current, then rerun only the affected handoff. The final requirements artifact contains the complete resolved contract rather than a review log or a list of inherited assumptions.
-
-## Match the user's involvement to the decision
-
-Use focused questions for consequential uncertainty and explicit document approval when the user is co-authoring or the artifact settles a high-impact product or architectural decision. Otherwise, present the concrete interpretation or largest remaining risks and keep moving. Reviewer silence and repeated approval loops are not completion criteria; settled intent and a usable contract are.
-
-## Keep the handoff explicit
-
-The roadmap names the current phase, the absolute paths of canonical artifacts, and the one blocking gate or question, if any. Detail and resolved decisions live in those artifacts rather than the roadmap. The final handoff identifies which specification, requirements, and design files are normative so planning never has to reconstruct the contract from reports or conversation history.

package/dist/builtin-memory/testing.md

@@ -1,39 +0,0 @@
----
-kind: knowledge
-when-and-why-to-read: When a repo has no recorded testing stance and you must decide whether a change carries a test, this knowledge should be read because eliciting the standard once and storing it settles every later change in that repo instead of each agent guessing differently and leaving the owner to strip out unwanted coverage.
-short-form: How to produce a repo's testing-stance memory — read what the repo already shows, draft a stance from that evidence, get the owner to confirm it, and store it.
-rationale: >-
-  Agents defaulted to a coverage-first instinct in repos that had deliberately chosen otherwise, and to the opposite absolute in repos that wanted coverage — each inventing a stance rather than taking the repo's. The missing move was procedural, not a rule: read the standard the repo already shows, and when it shows none, ask once and store the answer where the next agent inherits it.
----
-
-# Producing a repo's testing stance
-
-You are here because the repo has no `testing-stance` memory. Produce one; do not improvise a standard per change.
-
-## 1. Read the standard the repo already shows
-
-Take the first of these that settles the decision in front of you:
-
-1. **Written policy** — the repo's `CLAUDE.md` / `AGENTS.md` / contributing guide.
-2. **Runner and CI config** — which tiers exist, what CI actually gates, which time bounds are enforced.
-3. **The suite itself** — which layers carry tests, how granular they are, whether recent features arrived with tests or without.
-
-A repo whose suite is broad and current states its standard as clearly as a written policy; a repo with no tests states one too. What you find here is the draft — you are confirming a stance, not sourcing one from nothing.
-
-## 2. Draft the stance from that evidence
-
-Write the stance you would follow, as the finished document. Where the evidence is thin, start from this default and adjust:
-
-> Tests are added when the owner asks for them, or when a reported bug in something complex earns the smallest regression that proves that failure. New features and refactors are proved by direct runtime verification instead. Existing tests keep passing and are never deleted to move faster. Local runs cover only the files changed; the comprehensive suite is CI's job. Per-test time limits are a quality gate — a slow test gets split, not a longer timeout.
-
-Raise that bar where the repo warrants one on its own evidence: a published library contract, a mature fast suite already covering the surface, or a compliance requirement. Newness of the code is never a reason to draft a coverage-first stance.
-
-## 3. Confirm it with the owner
-
-Put the draft to the owner through `crtr human send`, as one question answerable with "yes" or a short edit. Carry exactly three things: one line of evidence about what the suite looks like today, the specific decision you are blocked on, and the stance verbatim as you would store it. Ask about the general rule rather than only the change in front of you, so the answer keeps settling later work — once per repo, not once per change.
-
-## 4. Store it as that repo's `testing-stance`
-
-Save the confirmed stance as a `testing-stance` preference in that repo's own project store (`crtr memory write -h`), so every agent working there inherits it and no one repeats this workflow. Keep it to what earns a test, what proves a change instead, and the local-versus-CI split with any per-test bound — the decision, never the conversation that produced it.
-
-A one-or-two-sentence stance belongs in a `{on: boot, at: content}` entry, because the decision it governs — should this change carry a test — happens before any test file is opened. Route it through a read entry instead only for conventions that matter while editing a test, matched to the repo's own test globs.