wingfoil 0.2.1

package/dist/memory/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/memory/schema.ts"],"names":[],"mappings":"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"}

package/dist/memory/state-machine.d.ts

@@ -0,0 +1,166 @@
+import type { MemoryYaml, StateMachine } from './schema';
+/** The reserved implicit-wildcard target state (spec-001) — never declared explicitly anywhere. */
+export declare const DEPRECATED_STATE = "deprecated";
+/**
+ * The terminal state of the `adr` and `tech-spec` machines (`memory.yaml`): reached along the forward
+ * `sequence` by `approve`, never by `memory deprecate`. A superseded decision is archived content — a
+ * later element explicitly replaced it — which is why `dl-028-archived-states-excluded-from-context`
+ * puts it in {@link ARCHIVED_STATUSES} alongside {@link DEPRECATED_STATE}.
+ */
+export declare const SUPERSEDED_STATE = "superseded";
+/**
+ * The canonical **archived** status set, ratified by `dl-028-archived-states-excluded-from-context`:
+ * exactly `{deprecated, superseded}`, in this fixed order (REQ-SYS-07 — no unordered iteration in any
+ * output-affecting path).
+ *
+ * REQ-STATE-06's Rationale ("distinguish active from archived decisions") always named the archived
+ * set, but its Description and Fit Criterion named only `deprecated`; dl-028 closes that gap and the
+ * SARD entry now names both. The previously-specified `rejected` is **not** here: `spec-001-memory-yaml-schema`
+ * removed that status from every type's machine (a `reject` transition lands back on `draft`), so it
+ * can never appear in a document's frontmatter.
+ */
+export declare const ARCHIVED_STATUSES: readonly string[];
+/**
+ * True when a document's frontmatter `status` is an archived state ({@link ARCHIVED_STATUSES}).
+ *
+ * This is the **single shared predicate** dl-028 mandates: both the default-search path
+ * (`searchMemoryDocuments`, REQ-STATE-06) and the agent-context path (`src/core/relevance.ts`'s
+ * relevance filter, spec-012 §6) consume it, so "archived" has exactly one definition. It supersedes
+ * `task-038`'s `isDeprecatedStatus`.
+ *
+ * It takes the **already-parsed status string**, not the raw frontmatter record: every call site
+ * projects `status` out of frontmatter anyway (for its own result shape), and a frontmatter-shaped
+ * predicate forced those callers either to re-parse or to hand back a record they had already
+ * destructured — the composition problem `task-038`'s reviewer flagged. Non-string / absent `status`
+ * values are normalised to `undefined` by the caller's own frontmatter projection and are never
+ * archived.
+ *
+ * Note the deliberate asymmetry with the *context* filter: `src/core/relevance.ts` excludes
+ * `draft` **in addition to** this archived set (spec-012 §6 — only "stable, decided and still-current"
+ * content enters an execution context), while default `memory search` keeps drafts visible.
+ * `draft` is therefore NOT part of the archived set.
+ */
+export declare function isArchivedStatus(status: string | undefined): boolean;
+/** `E_INVALID_<X>` field-level code (spec-009 §3) for an illegal state transition. */
+export declare const E_INVALID_TRANSITION = "E_INVALID_TRANSITION";
+/**
+ * `E_INVALID_<X>` field-level code (spec-009 §3, spec-010-memory-frontmatter-schema "Validation
+ * rules") for a document frontmatter `status` value that is not a legal state for its declared type
+ * at all — as opposed to {@link E_INVALID_TRANSITION}, which flags an illegal *transition attempt*
+ * (verb + current state), not the current state's bare legality. See {@link validateFrontmatterState}.
+ */
+export declare const E_INVALID_STATE = "E_INVALID_STATE";
+/** The four CLI verbs a transition can be requested for (`memory.add` assigns `sequence[0]` directly, no verb). */
+export type TransitionOp = 'submit' | 'approve' | 'reject' | 'deprecate';
+/**
+ * REQ-STATE-08's default machine, owned by the **engine** rather than by any config file
+ * (`bug-030-init-memory-yaml-has-no-state-machine`, task-071). It is the last arm of
+ * {@link resolveStateMachine}'s resolution: it governs every registered type that declares no `states`
+ * block in a `memory.yaml` that declares no `defaults.states` either.
+ *
+ * **Why the engine owns it.** REQ-STATE-08 states the rule over the *type* — "A Memory type that does
+ * not declare its own `states` uses the default machine" — with no mention of a `defaults` block, and
+ * its Rationale is "reduce config friction for simple types". `spec-001-memory-yaml-schema` makes
+ * `defaults` optional (`defaults: z.object({ states: StateMachine }).optional()`). A `memory.yaml`
+ * that omits `defaults` and registers a type without `states` is therefore a legal file whose types
+ * REQ-STATE-08 still gives a machine — which can only hold if the default exists without being
+ * declared. Before task-071 that combination threw instead, so every project `wingfoil init` created
+ * refused every transition verb (bug-030). BDD `p1-memory/P1.13-memory-element-schema.feature`
+ * scenario 2 is read the same way: its `Given` only puts a type in the file "without a `states`
+ * block", and its `Then` names the machine by value — so its title ("uses the defaults block")
+ * describes the common case rather than a precondition.
+ *
+ * **Why this value.** It is `spec-001`'s own worked `defaults` example, verbatim — not REQ-STATE-08's
+ * literal `draft → pending → approved/rejected → deprecated` wording, which `spec-001` §Consequences
+ * deliberately superseded: the default machine "loses its `rejected` state" ("no document ever records
+ * `status: rejected` again" — a `reject` from the `pending` gate lands straight back on `draft`), and
+ * `deprecated` is the reserved implicit wildcard reachable from any state, never declared in a
+ * `sequence` (the `StateMachine` schema's own `.superRefine()` forbids declaring it). The resulting
+ * legal set is exactly REQ-STATE-08's fit criterion under that encoding: `submit` draft→pending,
+ * `approve` pending→approved, `reject` pending→draft, `deprecate` →`deprecated` from anywhere, and
+ * nothing else.
+ *
+ * Frozen: it is shared by every type that falls back to it, so no consumer may mutate the machine
+ * other types are resolving (a shared constant, built once, with no per-call construction and no
+ * ordering dependence — REQ-SYS-07).
+ */
+export declare const DEFAULT_STATE_MACHINE: StateMachine;
+/**
+ * Resolve the state machine that governs `typeName`, per REQ-STATE-08. Three arms, in precedence
+ * order — the first that exists wins:
+ *
+ * 1. the type's own `states` block (`types.<name>.states`);
+ * 2. the file's `defaults.states`, when it declares one — a per-project override of the built-in;
+ * 3. {@link DEFAULT_STATE_MACHINE}, the engine's built-in default (task-071 / bug-030).
+ *
+ * Because arm 3 always applies, **no registered type can fail to resolve a machine**: the previous
+ * "neither the type nor `defaults` declares a machine" throw is gone, and with it the failure that
+ * made every transition verb refuse in a freshly-`wingfoil init`-ed project.
+ *
+ * The one remaining throw is for a type that is **not registered at all**. It is a plain `Error`, not
+ * a `ValidationError`, because it is a caller-programming-error condition rather than a
+ * document-transition failure — and it is not reachable from any CLI or MCP call: every transition
+ * verb goes through `prepareMemoryTransition` (`src/core/memory-transition.ts`), which returns the
+ * `NOT_FOUND` result `unknown memory type '<t>' (not defined in memory.yaml)` (exit `1`) for an
+ * unregistered type *before* calling this function. Only a direct library call naming a type the file
+ * does not register can reach it.
+ */
+export declare function resolveStateMachine(memoryYaml: MemoryYaml, typeName: string): StateMachine;
+/**
+ * Compute the legal target state for `op` applied to `currentState` under `machine`. Returns the
+ * target state on success; throws `ValidationError` (never returns a target) when the transition is
+ * illegal, per REQ-STATE-01 — a caller must never write a document's `status` unless this function
+ * returns normally. `filePath` is only used to enrich the thrown error's `file` field (optional —
+ * defaults to `''` when no document is on hand, e.g. in pure unit tests).
+ */
+export declare function resolveTransitionTarget(machine: StateMachine, currentState: string, op: TransitionOp, filePath?: string): string;
+/**
+ * Resolve the legal target of verb `op` for a document of type `typeName` currently in `currentState`
+ * — the entry point every Memory transition verb (`submit`, and `approve`/`reject`/`deprecate` after
+ * it) uses. It resolves the type's machine ({@link resolveStateMachine}, REQ-STATE-08) and delegates
+ * legality to {@link resolveTransitionTarget}, adding only the user-facing contract:
+ *
+ * An illegal transition is rethrown as the `E_INVALID_TRANSITION` issue ratified by
+ * `dl-032-illegal-transition-message-contract` (option (c)) — `message` is the pinned
+ * `` illegal transition <from> -> <to> for type '<type>' `` (REQ-STATE-01 Fit Criterion; BDD `P1.6`
+ * sc.2, `P5.2.3` sc.2), `detail` carries the engine's explanation of *why* the edge is illegal, and the
+ * exit code is `1`. `<to>` is computed by {@link contractTarget}.
+ *
+ * @throws {@link ../validation.ValidationError} `E_INVALID_TRANSITION` (exit `1`) as above.
+ * @throws `Error` when `typeName` is not registered (see {@link resolveStateMachine}). A registered type
+ *   can no longer fail to resolve a machine: REQ-STATE-08's built-in default is the last fallback.
+ */
+export declare function resolveTypeTransition(memoryYaml: MemoryYaml, typeName: string, currentState: string, op: TransitionOp, filePath?: string): string;
+/**
+ * Assert that `status` — a value read straight off a document's frontmatter — is a legal state for
+ * `typeName` under `machine` (REQ-STATE-01: state is derived from frontmatter; spec-010's "Validation
+ * rules": *"`status` must be a value in the type's `states.values`"*). The legal set is exactly
+ * {@link isDeclaredState}'s: `sequence` ∪ every `gates.<state>.reject` target ∪ `deprecated`.
+ *
+ * This is a distinct check from {@link resolveTransitionTarget}: that function asks "is verb `op`
+ * legal FROM `currentState`", assuming `currentState` is already known-legal; this function asks
+ * whether an arbitrary `status` string is itself a legal state for the type at all — independent of
+ * any transition attempt, e.g. when validating a document's frontmatter as read (BDD
+ * `P4.11-deliverables.feature` scenario 3, `P4.13-state-deduction.feature` scenario 3). The two must
+ * agree: any state `resolveTransitionTarget` can return must validate here, or the tool would refuse
+ * a document it wrote itself.
+ *
+ * @throws {@link ../validation.ValidationError} `E_INVALID_STATE` with the message
+ *   `` invalid state '<status>' for type '<typeName>' `` when `status` is not a legal state for
+ *   `typeName`. **Exit code `1`**, per spec-009-validation-strategy §3 as rewritten under
+ *   `dl-032-illegal-transition-message-contract`: the code keys on the *nature* of the failure, not
+ *   the pass that detected it — `2` is reserved for parse and system-integrity failures, while "every
+ *   other validation failure ... including business-rule failures detected in Pass 2" exits `1`. An
+ *   unrecognised `status` is understood input that a rule refused, so it is a `1`; that is why this
+ *   throws the `ValidationError` constructor directly rather than `ValidationError.semantic(...)`,
+ *   which hard-codes `2` for the genuine integrity checks (`loaders`, `id`, `query`). No BDD scenario
+ *   pins an exit code for this message — `P4.11` sc.3 and `P4.13` sc.3 pin the text only — so the spec
+ *   rule governs unopposed. (The separate `E_INVALID_TRANSITION` message/exit-code realignment that
+ *   `dl-032` ratified lives in {@link resolveTypeTransition}, added by `task-045-memory-submit`.)
+ *
+ *   `filePath` is only used to enrich the thrown error's `file` field (optional — defaults to `''`
+ *   when no document is on hand, e.g. in pure unit tests), mirroring {@link resolveTransitionTarget}'s
+ *   own `filePath` parameter.
+ */
+export declare function validateFrontmatterState(machine: StateMachine, typeName: string, status: string, filePath?: string): void;
+//# sourceMappingURL=state-machine.d.ts.map

package/dist/memory/state-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../../src/memory/state-machine.ts"],"names":[],"mappings":"AAuEA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEzD,mGAAmG;AACnG,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAAwD,CAAC;AAExG;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEpE;AAED,sFAAsF;AACtF,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAEjD,mHAAmH;AACnH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,qBAAqB,EAAE,YAahC,CAAC;AAEL;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAM1F;AAmBD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,YAAY,EACrB,YAAY,EAAE,MAAM,EACpB,EAAE,EAAE,YAAY,EAChB,QAAQ,SAAK,GACZ,MAAM,CA8DR;AAsCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,EAAE,EAAE,YAAY,EAChB,QAAQ,SAAK,GACZ,MAAM,CAiBR;AAuCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,QAAQ,SAAK,GACZ,IAAI,CAYN"}

package/dist/memory/state-machine.js

@@ -0,0 +1,431 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STATE_MACHINE = exports.E_INVALID_STATE = exports.E_INVALID_TRANSITION = exports.ARCHIVED_STATUSES = exports.SUPERSEDED_STATE = exports.DEPRECATED_STATE = void 0;
+exports.isArchivedStatus = isArchivedStatus;
+exports.resolveStateMachine = resolveStateMachine;
+exports.resolveTransitionTarget = resolveTransitionTarget;
+exports.resolveTypeTransition = resolveTypeTransition;
+exports.validateFrontmatterState = validateFrontmatterState;
+/**
+ * State-machine transition-legality engine (REQ-SYS-04, task-005-per-type-state-machines).
+ *
+ * task-004-decoupled-pillars already shipped the *structural* `StateMachine` Zod schema in
+ * `./schema.ts` — the `sequence`/`gates`/`waiting` shape plus a `.superRefine()` enforcing
+ * spec-001-memory-yaml-schema's "Semantic validation (post-parse)" rules (gates/waiting keys must be
+ * members of `sequence`, `"deprecated"` is reserved, etc.). This module does NOT re-validate any of
+ * that — it takes an already-parsed, already-structurally-valid `StateMachine` and answers a
+ * different question: **given a document's current `status` and a requested CLI verb
+ * (`submit`/`approve`/`reject`/`deprecate`), what is the legal target state, if any?**
+ *
+ * This is spec-009-validation-strategy §1's Pass 2 (semantic / cross-file): the transition rule
+ * needs the type's registered machine (loaded from `memory.yaml`) plus the document's own `status`
+ * field — neither is decidable from the document's frontmatter schema alone, matching spec-009's own
+ * worked example ("`wingfoil.status` must be a member of that type's `states.values`"). An illegal
+ * transition throws the shared `ValidationError` (exit code `1` — a business-rule failure, not an
+ * integrity one, per spec-009 §3 as rewritten under `dl-032-illegal-transition-message-contract`)
+ * and — critically — throws *before* returning any target, so a caller can never reach
+ * the frontmatter-write step on an illegal transition (REQ-STATE-01: rejected before any file write).
+ * This module never touches a document or the filesystem itself; it is a pure function of
+ * (`machine`, `currentState`, `op`) → target-or-throw, and it is the caller's job to gate any actual
+ * write on this function returning normally.
+ *
+ * Rules implemented below (spec-001-memory-yaml-schema, "Sub-schema: StateMachine" +
+ * "Which verb drives each forward edge — fully determined by the schema" + "`deprecated` is
+ * implicit"):
+ *
+ * - `submit`: legal only from a state that is in `sequence`, is NOT a `gates` key, and is NOT in
+ *   `waiting`, and that has a next state in `sequence`. Target: the next state in `sequence`.
+ * - `approve`: legal only from a state that IS a `gates` key and is NOT also in `waiting` (a state
+ *   that is both is spec-001's explicit "verb-less" case: "its forward edge is verb-less (picked up
+ *   automatically)" — the manual `approve` verb does not apply, only the manual `reject` does).
+ *   Target: the next state in `sequence`.
+ * - `reject`: legal only from a state that IS a `gates` key (regardless of `waiting` membership —
+ *   spec-001: a gate+waiting state "still exposes a manual `reject`/decline path"). Target:
+ *   `gates[<state>].reject`, always taken verbatim (it need not be a `sequence` member).
+ * - `deprecate`: the implicit wildcard edge — always legal from any current state, target is the
+ *   reserved `"deprecated"` state. Never declared in `sequence`/`gates`/`waiting` (enforced
+ *   structurally by task-004's `.superRefine()`; this engine does not need to re-check it).
+ * - Anything else (state not a member of `sequence` at all, wrong verb for the state's category, or
+ *   a `sequence`-terminal state with no next entry) is illegal.
+ *
+ * task-036-frontmatter-lifecycle-validation adds {@link validateFrontmatterState} — a distinct check
+ * from the transition engine above: REQ-STATE-01's "document state derived from frontmatter" half,
+ * independent of any transition attempt. `resolveTransitionTarget` only answers "is verb `op` legal
+ * FROM `currentState`"; it never asserts that an arbitrary `status` string read off a document's
+ * frontmatter is itself a member of the type's declared state set at all — the check
+ * spec-010-memory-frontmatter-schema's "Validation rules" table names ("`status` must be a value in
+ * the type's `states.values`" → failure "invalid state for type") and BDD
+ * `P4.11-deliverables.feature`/`P4.13-state-deduction.feature` both exercise (`"invalid state
+ * 'shipped' for type 'task'"`). A state is legal for a type iff it belongs to that machine's full
+ * reachable set — `sequence` ∪ every `gates.<state>.reject` target (spec-001 permits those to be
+ * off-chain, and `resolveTransitionTarget` returns them verbatim) ∪ the reserved implicit
+ * `"deprecated"` state (never declared in `sequence` itself, per the `StateMachine` schema's own
+ * `.superRefine()`, but always a legal transition target via `memory.deprecate` — see
+ * `resolveTransitionTarget`'s `deprecate` case above).
+ *
+ * **Type resolution (REQ-STATE-08):** `resolveStateMachine` resolves a type's machine as
+ * `types.<name>.states ?? defaults.states ?? `{@link DEFAULT_STATE_MACHINE}. task-005's own tests
+ * exercise only the real types registered in `docs/self/.wingfoil/memory.yaml`, every one of which
+ * declares its own `states` block — so the `?? defaults.states` arm was left uncovered by that task,
+ * and `task-010-default-state-machine-fallback` closed that gap with a throwaway fixture type
+ * (declared with no `states:` key) in `test/memory/state-machine.test.ts`. The **third** arm is
+ * task-071's (`bug-030-init-memory-yaml-has-no-state-machine`): task-010's fixture still *declared* a
+ * `defaults` block, so a file with no machine anywhere — the shape `wingfoil init` scaffolded — was
+ * never resolved by anything, and it threw. See {@link DEFAULT_STATE_MACHINE} for why the engine, not
+ * the config file, owns that default.
+ */
+const validation_1 = require("../validation");
+const schema_1 = require("./schema");
+/** The reserved implicit-wildcard target state (spec-001) — never declared explicitly anywhere. */
+exports.DEPRECATED_STATE = 'deprecated';
+/**
+ * The terminal state of the `adr` and `tech-spec` machines (`memory.yaml`): reached along the forward
+ * `sequence` by `approve`, never by `memory deprecate`. A superseded decision is archived content — a
+ * later element explicitly replaced it — which is why `dl-028-archived-states-excluded-from-context`
+ * puts it in {@link ARCHIVED_STATUSES} alongside {@link DEPRECATED_STATE}.
+ */
+exports.SUPERSEDED_STATE = 'superseded';
+/**
+ * The canonical **archived** status set, ratified by `dl-028-archived-states-excluded-from-context`:
+ * exactly `{deprecated, superseded}`, in this fixed order (REQ-SYS-07 — no unordered iteration in any
+ * output-affecting path).
+ *
+ * REQ-STATE-06's Rationale ("distinguish active from archived decisions") always named the archived
+ * set, but its Description and Fit Criterion named only `deprecated`; dl-028 closes that gap and the
+ * SARD entry now names both. The previously-specified `rejected` is **not** here: `spec-001-memory-yaml-schema`
+ * removed that status from every type's machine (a `reject` transition lands back on `draft`), so it
+ * can never appear in a document's frontmatter.
+ */
+exports.ARCHIVED_STATUSES = Object.freeze([exports.DEPRECATED_STATE, exports.SUPERSEDED_STATE]);
+/**
+ * True when a document's frontmatter `status` is an archived state ({@link ARCHIVED_STATUSES}).
+ *
+ * This is the **single shared predicate** dl-028 mandates: both the default-search path
+ * (`searchMemoryDocuments`, REQ-STATE-06) and the agent-context path (`src/core/relevance.ts`'s
+ * relevance filter, spec-012 §6) consume it, so "archived" has exactly one definition. It supersedes
+ * `task-038`'s `isDeprecatedStatus`.
+ *
+ * It takes the **already-parsed status string**, not the raw frontmatter record: every call site
+ * projects `status` out of frontmatter anyway (for its own result shape), and a frontmatter-shaped
+ * predicate forced those callers either to re-parse or to hand back a record they had already
+ * destructured — the composition problem `task-038`'s reviewer flagged. Non-string / absent `status`
+ * values are normalised to `undefined` by the caller's own frontmatter projection and are never
+ * archived.
+ *
+ * Note the deliberate asymmetry with the *context* filter: `src/core/relevance.ts` excludes
+ * `draft` **in addition to** this archived set (spec-012 §6 — only "stable, decided and still-current"
+ * content enters an execution context), while default `memory search` keeps drafts visible.
+ * `draft` is therefore NOT part of the archived set.
+ */
+function isArchivedStatus(status) {
+    return status !== undefined && exports.ARCHIVED_STATUSES.includes(status);
+}
+/** `E_INVALID_<X>` field-level code (spec-009 §3) for an illegal state transition. */
+exports.E_INVALID_TRANSITION = 'E_INVALID_TRANSITION';
+/**
+ * `E_INVALID_<X>` field-level code (spec-009 §3, spec-010-memory-frontmatter-schema "Validation
+ * rules") for a document frontmatter `status` value that is not a legal state for its declared type
+ * at all — as opposed to {@link E_INVALID_TRANSITION}, which flags an illegal *transition attempt*
+ * (verb + current state), not the current state's bare legality. See {@link validateFrontmatterState}.
+ */
+exports.E_INVALID_STATE = 'E_INVALID_STATE';
+/**
+ * REQ-STATE-08's default machine, owned by the **engine** rather than by any config file
+ * (`bug-030-init-memory-yaml-has-no-state-machine`, task-071). It is the last arm of
+ * {@link resolveStateMachine}'s resolution: it governs every registered type that declares no `states`
+ * block in a `memory.yaml` that declares no `defaults.states` either.
+ *
+ * **Why the engine owns it.** REQ-STATE-08 states the rule over the *type* — "A Memory type that does
+ * not declare its own `states` uses the default machine" — with no mention of a `defaults` block, and
+ * its Rationale is "reduce config friction for simple types". `spec-001-memory-yaml-schema` makes
+ * `defaults` optional (`defaults: z.object({ states: StateMachine }).optional()`). A `memory.yaml`
+ * that omits `defaults` and registers a type without `states` is therefore a legal file whose types
+ * REQ-STATE-08 still gives a machine — which can only hold if the default exists without being
+ * declared. Before task-071 that combination threw instead, so every project `wingfoil init` created
+ * refused every transition verb (bug-030). BDD `p1-memory/P1.13-memory-element-schema.feature`
+ * scenario 2 is read the same way: its `Given` only puts a type in the file "without a `states`
+ * block", and its `Then` names the machine by value — so its title ("uses the defaults block")
+ * describes the common case rather than a precondition.
+ *
+ * **Why this value.** It is `spec-001`'s own worked `defaults` example, verbatim — not REQ-STATE-08's
+ * literal `draft → pending → approved/rejected → deprecated` wording, which `spec-001` §Consequences
+ * deliberately superseded: the default machine "loses its `rejected` state" ("no document ever records
+ * `status: rejected` again" — a `reject` from the `pending` gate lands straight back on `draft`), and
+ * `deprecated` is the reserved implicit wildcard reachable from any state, never declared in a
+ * `sequence` (the `StateMachine` schema's own `.superRefine()` forbids declaring it). The resulting
+ * legal set is exactly REQ-STATE-08's fit criterion under that encoding: `submit` draft→pending,
+ * `approve` pending→approved, `reject` pending→draft, `deprecate` →`deprecated` from anywhere, and
+ * nothing else.
+ *
+ * Frozen: it is shared by every type that falls back to it, so no consumer may mutate the machine
+ * other types are resolving (a shared constant, built once, with no per-call construction and no
+ * ordering dependence — REQ-SYS-07).
+ */
+exports.DEFAULT_STATE_MACHINE = (() => {
+    // Built through the real `StateMachine` schema, so the built-in is held to exactly the structural
+    // rules (`gates` keys ⊆ `sequence`, `"deprecated"` never declared) every hand-written machine is —
+    // a malformed default would otherwise be the one machine nothing validates. Frozen through, so a
+    // consumer cannot mutate what every falling-back type resolves.
+    const machine = schema_1.StateMachine.parse({
+        sequence: ['draft', 'pending', 'approved'],
+        gates: { pending: { reject: 'draft' } },
+    });
+    Object.freeze(machine.sequence);
+    Object.freeze(machine.gates['pending']);
+    Object.freeze(machine.gates);
+    return Object.freeze(machine);
+})();
+/**
+ * Resolve the state machine that governs `typeName`, per REQ-STATE-08. Three arms, in precedence
+ * order — the first that exists wins:
+ *
+ * 1. the type's own `states` block (`types.<name>.states`);
+ * 2. the file's `defaults.states`, when it declares one — a per-project override of the built-in;
+ * 3. {@link DEFAULT_STATE_MACHINE}, the engine's built-in default (task-071 / bug-030).
+ *
+ * Because arm 3 always applies, **no registered type can fail to resolve a machine**: the previous
+ * "neither the type nor `defaults` declares a machine" throw is gone, and with it the failure that
+ * made every transition verb refuse in a freshly-`wingfoil init`-ed project.
+ *
+ * The one remaining throw is for a type that is **not registered at all**. It is a plain `Error`, not
+ * a `ValidationError`, because it is a caller-programming-error condition rather than a
+ * document-transition failure — and it is not reachable from any CLI or MCP call: every transition
+ * verb goes through `prepareMemoryTransition` (`src/core/memory-transition.ts`), which returns the
+ * `NOT_FOUND` result `unknown memory type '<t>' (not defined in memory.yaml)` (exit `1`) for an
+ * unregistered type *before* calling this function. Only a direct library call naming a type the file
+ * does not register can reach it.
+ */
+function resolveStateMachine(memoryYaml, typeName) {
+    const typeEntry = memoryYaml.types[typeName];
+    if (!typeEntry) {
+        throw new Error(`memory.yaml has no type "${typeName}" registered`);
+    }
+    return typeEntry.states ?? memoryYaml.defaults?.states ?? exports.DEFAULT_STATE_MACHINE;
+}
+/**
+ * Build one `E_INVALID_TRANSITION` `ValidationError` and throw it. Exits `1`: an illegal transition is
+ * understood input that a rule refused, not a parse/integrity failure (spec-009 §3, `dl-032`) — so the
+ * plain constructor, not `ValidationError.semantic(...)`. The message here is the type-agnostic
+ * diagnostic; {@link resolveTypeTransition} turns it into the pinned contract message.
+ */
+function illegal(currentState, op, message, filePath) {
+    throw new validation_1.ValidationError([
+        {
+            code: exports.E_INVALID_TRANSITION,
+            path: 'status',
+            file: filePath,
+            message: `illegal \`${op}\` from "${currentState}": ${message}`,
+        },
+    ]);
+}
+/**
+ * Compute the legal target state for `op` applied to `currentState` under `machine`. Returns the
+ * target state on success; throws `ValidationError` (never returns a target) when the transition is
+ * illegal, per REQ-STATE-01 — a caller must never write a document's `status` unless this function
+ * returns normally. `filePath` is only used to enrich the thrown error's `file` field (optional —
+ * defaults to `''` when no document is on hand, e.g. in pure unit tests).
+ */
+function resolveTransitionTarget(machine, currentState, op, filePath = '') {
+    if (op === 'deprecate') {
+        // Implicit wildcard edge from any state (spec-001) — always legal, never declared explicitly.
+        return exports.DEPRECATED_STATE;
+    }
+    const index = machine.sequence.indexOf(currentState);
+    const gate = (machine.gates ?? {})[currentState];
+    const isWaiting = (machine.waiting ?? []).includes(currentState);
+    switch (op) {
+        case 'submit': {
+            if (index === -1) {
+                return illegal(currentState, op, "not a member of this type's `sequence`", filePath);
+            }
+            if (gate) {
+                return illegal(currentState, op, 'a `gates` state — its forward edge requires `approve`, not `submit`', filePath);
+            }
+            if (isWaiting) {
+                return illegal(currentState, op, 'a `waiting` state — its forward edge fires only via a Workflow action, not `submit`', filePath);
+            }
+            const next = machine.sequence[index + 1];
+            if (next === undefined) {
+                return illegal(currentState, op, 'the last state in `sequence` — there is no forward edge', filePath);
+            }
+            return next;
+        }
+        case 'approve': {
+            if (!gate) {
+                return illegal(currentState, op, 'not a `gates` state — `approve` is only legal from a gate', filePath);
+            }
+            if (isWaiting) {
+                return illegal(currentState, op, 'both a `gates` and `waiting` state — its forward edge is verb-less (fires only via a Workflow action), not `approve`', filePath);
+            }
+            const next = machine.sequence[index + 1];
+            if (next === undefined) {
+                return illegal(currentState, op, 'a `gates` state with no next `sequence` entry to approve into', filePath);
+            }
+            return next;
+        }
+        case 'reject': {
+            if (!gate) {
+                return illegal(currentState, op, 'not a `gates` state — `reject` is only legal from a gate', filePath);
+            }
+            // `reject` target is taken verbatim — need not be a `sequence` member (spec-001).
+            return gate.reject;
+        }
+        default: {
+            const exhaustive = op;
+            return illegal(currentState, exhaustive, 'unknown operation', filePath);
+        }
+    }
+}
+/** What the contract message prints for `<to>` when a verb has no legal edge anywhere in the machine. */
+const NO_TARGET = '(none)';
+/**
+ * The `<to>` of the illegal-transition contract message: the verb's **canonical edge** for this type —
+ * the target `op` reaches from the first state, in `sequence` order, from which `op` is legal (for
+ * `submit` on `task` or on the default machine: `pending`; on `release`: `planning`). A verb names no
+ * target of its own, so the message needs a rule; this one reproduces the string BDD `P1.6` sc.2 and
+ * `P5.2.3` sc.2 pin (`approved -> pending` for `task`) on both the default machine and the real `task`
+ * machine, where the literal forward edge out of `approved` is `done`.
+ *
+ * What happens when that canonical target IS `currentState` — printing it would be a self-loop — is
+ * ratified by `dl-053-illegal-transition-target-for-verbless-edges` (option 1): **keep walking
+ * `sequence` for the next legal edge of the SAME verb**, and render {@link NO_TARGET} when the verb
+ * has no other target. It must never name the next state in `sequence` regardless of verb — the
+ * earlier fallback did, printing `draft -> pending` for a `reject` (a rejection shown as a forward
+ * move) and `backlog -> in-progress` for an `approve` (a `waiting` edge no verb drives), misinforming
+ * exactly the user who has just made an illegal call. Every `<to>` printed here is therefore a real
+ * target of the verb the user typed, on this type's own machine.
+ *
+ * A pure function of `(machine, currentState, op)` walked in `sequence` order (REQ-SYS-07).
+ */
+function contractTarget(machine, currentState, op) {
+    for (const state of machine.sequence) {
+        let target;
+        try {
+            target = resolveTransitionTarget(machine, state, op);
+        }
+        catch {
+            continue; // `op` is not legal from this state — keep walking the chain
+        }
+        // dl-053: a self-loop is not a transition; keep looking for a different target of this same verb.
+        if (target !== currentState)
+            return target;
+    }
+    return NO_TARGET;
+}
+/**
+ * Resolve the legal target of verb `op` for a document of type `typeName` currently in `currentState`
+ * — the entry point every Memory transition verb (`submit`, and `approve`/`reject`/`deprecate` after
+ * it) uses. It resolves the type's machine ({@link resolveStateMachine}, REQ-STATE-08) and delegates
+ * legality to {@link resolveTransitionTarget}, adding only the user-facing contract:
+ *
+ * An illegal transition is rethrown as the `E_INVALID_TRANSITION` issue ratified by
+ * `dl-032-illegal-transition-message-contract` (option (c)) — `message` is the pinned
+ * `` illegal transition <from> -> <to> for type '<type>' `` (REQ-STATE-01 Fit Criterion; BDD `P1.6`
+ * sc.2, `P5.2.3` sc.2), `detail` carries the engine's explanation of *why* the edge is illegal, and the
+ * exit code is `1`. `<to>` is computed by {@link contractTarget}.
+ *
+ * @throws {@link ../validation.ValidationError} `E_INVALID_TRANSITION` (exit `1`) as above.
+ * @throws `Error` when `typeName` is not registered (see {@link resolveStateMachine}). A registered type
+ *   can no longer fail to resolve a machine: REQ-STATE-08's built-in default is the last fallback.
+ */
+function resolveTypeTransition(memoryYaml, typeName, currentState, op, filePath = '') {
+    const machine = resolveStateMachine(memoryYaml, typeName);
+    try {
+        return resolveTransitionTarget(machine, currentState, op, filePath);
+    }
+    catch (error) {
+        if (!(error instanceof validation_1.ValidationError))
+            throw error;
+        const detail = error.issues.map((issue) => issue.message).join('; ');
+        throw new validation_1.ValidationError([
+            {
+                code: exports.E_INVALID_TRANSITION,
+                path: 'status',
+                file: filePath,
+                message: `illegal transition ${currentState} -> ${contractTarget(machine, currentState, op)} for type '${typeName}'`,
+                detail,
+            },
+        ]);
+    }
+}
+/**
+ * True when `status` is a state a document of this type may legitimately carry — the **full**
+ * reachable state set of `machine`, which is the union of three sources:
+ *
+ * 1. **`machine.sequence`** — every state on the forward chain.
+ * 2. **Every `machine.gates.<state>.reject` target** — `resolveTransitionTarget` returns these
+ *    *verbatim* and spec-001-memory-yaml-schema's "Semantic validation (post-parse)" is explicit that
+ *    such a target "need **not** be a member of `sequence`: it may revert into the chain (e.g.
+ *    `pending: { reject: draft }`) or name an **off-chain decline state reached by no forward edge**".
+ *    Only the gate *keys* (and `waiting` entries) are constrained to `sequence`; the reject targets
+ *    are not. Omitting this arm is what task-036's first pass got wrong: the `reject` verb would write
+ *    a status that this very function then declared invalid, leaving the document unmovable —
+ *    a REQ-SYS-04 violation for a config shape spec-001 names by example. No type registered in
+ *    `docs/self/.wingfoil/memory.yaml` currently exercises it (all three of its reject targets —
+ *    `draft`, `closed`, `in-progress` — happen to be `sequence` members), so it is covered by a
+ *    synthetic fixture machine in `test/memory/state-machine.test.ts`.
+ * 3. **{@link DEPRECATED_STATE}** — the reserved implicit wildcard target every type reaches via
+ *    `memory.deprecate` (see {@link resolveTransitionTarget}'s `deprecate` case), never declared in
+ *    any `sequence` (the `StateMachine` schema's own `.superRefine()` forbids declaring it).
+ *
+ * `machine.waiting` contributes nothing: every `waiting` entry is required to be a `sequence` member
+ * already, so it is covered by (1).
+ *
+ * Iteration over `gates` is sorted (REQ-SYS-07 — no unordered iteration in any output-affecting path);
+ * the predicate's boolean result is order-independent, but keeping the traversal deterministic keeps
+ * it so under any future change that reports *which* source matched.
+ */
+function isDeclaredState(machine, status) {
+    if (status === exports.DEPRECATED_STATE || machine.sequence.includes(status)) {
+        return true;
+    }
+    const gates = machine.gates ?? {};
+    return Object.keys(gates)
+        .sort()
+        .some((gateState) => gates[gateState]?.reject === status);
+}
+/**
+ * Assert that `status` — a value read straight off a document's frontmatter — is a legal state for
+ * `typeName` under `machine` (REQ-STATE-01: state is derived from frontmatter; spec-010's "Validation
+ * rules": *"`status` must be a value in the type's `states.values`"*). The legal set is exactly
+ * {@link isDeclaredState}'s: `sequence` ∪ every `gates.<state>.reject` target ∪ `deprecated`.
+ *
+ * This is a distinct check from {@link resolveTransitionTarget}: that function asks "is verb `op`
+ * legal FROM `currentState`", assuming `currentState` is already known-legal; this function asks
+ * whether an arbitrary `status` string is itself a legal state for the type at all — independent of
+ * any transition attempt, e.g. when validating a document's frontmatter as read (BDD
+ * `P4.11-deliverables.feature` scenario 3, `P4.13-state-deduction.feature` scenario 3). The two must
+ * agree: any state `resolveTransitionTarget` can return must validate here, or the tool would refuse
+ * a document it wrote itself.
+ *
+ * @throws {@link ../validation.ValidationError} `E_INVALID_STATE` with the message
+ *   `` invalid state '<status>' for type '<typeName>' `` when `status` is not a legal state for
+ *   `typeName`. **Exit code `1`**, per spec-009-validation-strategy §3 as rewritten under
+ *   `dl-032-illegal-transition-message-contract`: the code keys on the *nature* of the failure, not
+ *   the pass that detected it — `2` is reserved for parse and system-integrity failures, while "every
+ *   other validation failure ... including business-rule failures detected in Pass 2" exits `1`. An
+ *   unrecognised `status` is understood input that a rule refused, so it is a `1`; that is why this
+ *   throws the `ValidationError` constructor directly rather than `ValidationError.semantic(...)`,
+ *   which hard-codes `2` for the genuine integrity checks (`loaders`, `id`, `query`). No BDD scenario
+ *   pins an exit code for this message — `P4.11` sc.3 and `P4.13` sc.3 pin the text only — so the spec
+ *   rule governs unopposed. (The separate `E_INVALID_TRANSITION` message/exit-code realignment that
+ *   `dl-032` ratified lives in {@link resolveTypeTransition}, added by `task-045-memory-submit`.)
+ *
+ *   `filePath` is only used to enrich the thrown error's `file` field (optional — defaults to `''`
+ *   when no document is on hand, e.g. in pure unit tests), mirroring {@link resolveTransitionTarget}'s
+ *   own `filePath` parameter.
+ */
+function validateFrontmatterState(machine, typeName, status, filePath = '') {
+    if (isDeclaredState(machine, status)) {
+        return;
+    }
+    throw new validation_1.ValidationError([
+        {
+            code: exports.E_INVALID_STATE,
+            path: 'status',
+            file: filePath,
+            message: `invalid state '${status}' for type '${typeName}'`,
+        },
+    ]);
+}
+//# sourceMappingURL=state-machine.js.map

package/dist/memory/state-machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.js","sourceRoot":"","sources":["../../src/memory/state-machine.ts"],"names":[],"mappings":"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"}

package/dist/memory/submit.d.ts

@@ -0,0 +1,11 @@
+/** The frontmatter key `memory.reject` sets and `memory.submit` removes (spec-010). */
+export declare const REJECTION_REASON_FIELD = "rejection_reason";
+/**
+ * The fields that must be filled before a submit but are not: `title` first (spec-010 requires it of
+ * every type), then each of `required` in its declared order, without duplicates. `[]` means the
+ * document may be submitted.
+ */
+export declare function missingRequiredFields(frontmatter: Readonly<Record<string, unknown>>, required: readonly string[]): string[];
+/** The submitted document: `status` set to `target` and `rejection_reason` removed; nothing else changes. */
+export declare function renderSubmitDocument(content: string, target: string): string;
+//# sourceMappingURL=submit.d.ts.map