@north-light/crouter 0.3.228 → 0.3.229

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.