wingfoil 0.2.1

package/dist/core/memory-transition.d.ts

@@ -0,0 +1,111 @@
+import type { DocumentScope, MemoryYaml, TransitionOp } from '../memory';
+import { type CoreResult } from './types';
+/** A document located and cleared for one transition — everything the verb needs to finish it. */
+export interface PreparedMemoryTransition {
+    /**
+     * The `memory.yaml` this transition was resolved against — **the one committed at `HEAD`**, never
+     * the working tree's (task-091, `bug-081`). It rides the result rather than being re-loaded by the
+     * verb so that a single command cannot decide its transition from one copy and its follow-up facts
+     * (`memory submit`'s `template.frontmatter.required`) from another.
+     */
+    readonly memoryYaml: MemoryYaml;
+    readonly id: string;
+    /** The document's declared frontmatter `type` (a registered `memory.yaml` type). */
+    readonly type: string;
+    /** Root-relative POSIX path of the document. */
+    readonly path: string;
+    /** The document's parsed frontmatter as read (not schema-validated). */
+    readonly frontmatter: Readonly<Record<string, unknown>>;
+    /** The full current file content, the base for the verb's edit. */
+    readonly content: string;
+    readonly from: string;
+    readonly to: string;
+}
+/**
+ * Locate document `id` and resolve verb `op` on it, **against the `memory.yaml` committed at
+ * `HEAD`** (`loadMemoryYamlAtHead`).
+ *
+ * The baseline is the point (task-091, `bug-081`, `dl-080` option (B)). This function takes no
+ * `MemoryYaml`: a caller cannot hand it a working-tree machine even by accident, which is what makes
+ * the committed baseline a property of the read itself rather than of a precondition someone must
+ * remember to run. An uncommitted edit to a type's `sequence` used to decide both the transition a
+ * verb performed and the `status` it committed — through `memory submit`, which requires no
+ * authority — and stranded the element in a state the committed machine rejects.
+ *
+ * Refusals, all returned (never thrown) and all exit `1`:
+ *
+ * - `HEAD` holds no `memory.yaml` → `VALIDATION`, fail-closed: with no committed machine there is no
+ *   `from → to` to record, and the only fail-open available is the working tree, which is the defect.
+ *   `wingfoil init` commits the scaffold, so no legitimate flow reaches this;
+ * - the committed `memory.yaml` does not parse or validate → `VALIDATION`, same reasoning;
+ * - no document carries that frontmatter `id` → `NOT_FOUND` `document not found: <id>` (P1.6 sc.3);
+ * - its `type` is not registered → `NOT_FOUND` with `memory add`'s unknown-type message;
+ * - its `status` is not a state of the type → `VALIDATION` `invalid state '<s>' for type '<t>'`
+ *   (task-036's `validateFrontmatterState`);
+ * - the verb is illegal from that state → `INVALID_TRANSITION` with the `dl-032` contract message
+ *   (`resolveTypeTransition`), the engine's explanation in `details.issues[0].detail`.
+ *
+ * The last four keep their pinned messages verbatim as the first sentence;
+ * {@link uncommittedMachineNote} may append a second one.
+ */
+export declare function prepareMemoryTransition(root: string, id: string, op: TransitionOp): CoreResult<PreparedMemoryTransition>;
+/**
+ * Verify what the new commit **contains**, by diffing it against its own parent (task-088, AC3).
+ *
+ * This is the half that makes the guard above checkable rather than hopeful. Reading the file on disk
+ * answers "does the document now say `approved`?" — true no matter what else rode along; `HEAD~1..HEAD`
+ * is not. Same shape as `task-080`'s lockfile guard: assert the diff, not the end state. The parent is
+ * `<sha>^`, or git's empty tree for a root commit, so the check is total rather than conditional.
+ *
+ * It is an **alarm, not a rollback**: it can only run once the commit exists, and rewriting history
+ * behind the user's back is a worse failure than reporting one (`dl-035` points the same way). With
+ * {@link requireUnmodifiedDocument} in place it should be unreachable, which is the point.
+ */
+export declare function verifyCommittedScope(root: string, sha: string, path: string, expected: Readonly<Record<string, string | undefined>>, scope: DocumentScope): string[];
+/**
+ * Write `content` over the prepared document and commit exactly that one path with `message`,
+ * returning the new commit's sha (`commitPaths`, task-018; scoped to that path even when other changes
+ * are staged, bug-027). Callers must have run the git-identity pre-flight (REQ-SEC-01) and every refusal
+ * check first; this step is the only write.
+ *
+ * Four checks bound what reaches the repository, in this order — they are not redundant, they catch
+ * different defects:
+ *
+ * 1. **The document is the project's to write** ({@link requireConfinedWriteTarget}, REQ-SEC-06) —
+ *    catches a wrong *place*, in the two shapes a write can meet it. A type directory that is a
+ *    symlink out of the project puts the document outside the root (`bug-117`), where `writeDocument`
+ *    rewrites a file the repository does not own and `git add` then fails with its own text; and a
+ *    **document** that is itself a symlink does the same with no symlinked directory anywhere,
+ *    because `writeFileSync` follows the link that `unlinkSync` would merely remove (`bug-120` D2,
+ *    measured on all four verbs). `bug-117` reports the first for `memory add`, whose target is
+ *    resolved by `resolveConfinedMemoryPath`; these four verbs never ask that resolver anything —
+ *    they locate an existing document — so both questions are asked here, about the path they are
+ *    about to write. It runs **first**, and for every `scope`: the question "is this file ours at
+ *    all" precedes every question about its content, and check 2 cannot stand in for it (`git status
+ *    --porcelain` reports a path beyond a symbolic link as clean, which is `bug-118`).
+ * 2. **The working tree is unmodified** ({@link requireUnmodifiedDocument}, `declared-fields-only`
+ *    only) — catches a wrong *baseline*: content that was already on disk before the verb ran
+ *    (`bug-076`).
+ * 3. **The rendering is in scope** ({@link verifyDocumentEdit} against the prepared document) —
+ *    catches a defect in the *editor*: `status` must be the prepared target, every field in `expected`
+ *    must have its value (`undefined` = absent), and no other field and no byte of the body may have
+ *    moved (the `bug-041` class). Runs under `declared-fields-only` for **every** verb, `submit`
+ *    included: `renderSubmitDocument` owns `status` and `rejection_reason` alone, and the content
+ *    `submit` carries is already in the prepared document it is compared against.
+ * 4. **The commit contains only the declared change** ({@link verifyCommittedScope} against
+ *    `HEAD~1`) — the post-condition proper, and the only one that measures the artefact of record.
+ *
+ * Checks 1–3 report a `VALIDATION` error (exit 1) with nothing written or committed. Check 4 can
+ * only report; see {@link verifyCommittedScope}.
+ *
+ * Check 1 resolves on the **working tree**, not at `HEAD`, which departs from `command-baseline`'s
+ * rule for a gating read. The argument is `task-102`'s, recorded in
+ * `dl-086-a-guard-over-a-filesystem-effect-resolves-on-the-filesystem` (`in-discussion`) and cited
+ * rather than re-made: it predicts where `writeDocument` will land, and that follows the symlinks on
+ * disk rather than the ones a commit records.
+ *
+ * @param scope - How much of the document this operation owns; defaults to the strict
+ *   `declared-fields-only`, so a new verb is guarded unless it opts out deliberately.
+ */
+export declare function commitMemoryTransition(root: string, prepared: PreparedMemoryTransition, content: string, message: string, expected?: Readonly<Record<string, string | undefined>>, scope?: DocumentScope): CoreResult<string>;
+//# sourceMappingURL=memory-transition.d.ts.map

package/dist/core/memory-transition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-transition.d.ts","sourceRoot":"","sources":["../../src/core/memory-transition.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAgB,YAAY,EAAE,MAAM,WAAW,CAAC;AAMvF,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAG3D,kGAAkG;AAClG,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAyBD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,GAAG,UAAU,CAAC,wBAAwB,CAAC,CA2DxH;AAyCD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,EACtD,KAAK,EAAE,aAAa,GACnB,MAAM,EAAE,CAQV;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,wBAAwB,EAClC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAM,EAC3D,KAAK,GAAE,aAAsC,GAC5C,UAAU,CAAC,MAAM,CAAC,CA2BpB"}

package/dist/core/memory-transition.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareMemoryTransition = prepareMemoryTransition;
+exports.verifyCommittedScope = verifyCommittedScope;
+exports.commitMemoryTransition = commitMemoryTransition;
+/**
+ * The shared skeleton of every Memory state-transition verb (task-045-memory-submit; reused by
+ * `memory approve`/`reject`/`deprecate`, task-046/047/048).
+ *
+ * A transition verb always does the same two things around its own verb-specific rules:
+ *
+ * 1. {@link prepareMemoryTransition} — find the document by its bare id (spec-008-cli-grammar §7), read
+ *    its declared `type` and current `status`, and resolve the legal target for the verb **against the
+ *    `memory.yaml` committed at `HEAD`** (task-091, `bug-081`, `dl-080` (B)). Every expected
+ *    refusal is returned as a `CoreResult.error` (exit `1`), **before anything is written**, so "the
+ *    state is unchanged" (P1.6 sc.2, REQ-STATE-01) holds by construction.
+ * 2. {@link commitMemoryTransition} — write the new bytes and turn them into exactly one commit scoped
+ *    to that one document.
+ *
+ * What happens in between (required-field checks, which fields change, the commit message) is the
+ * verb's own business; see `memorySubmitFn` in `./index.ts`.
+ */
+const path_1 = require("path");
+const memory_1 = require("../memory");
+const storage_1 = require("../storage");
+const validation_1 = require("../validation");
+const confinement_1 = require("./confinement");
+const loaders_1 = require("./loaders");
+const types_1 = require("./types");
+const write_guard_1 = require("./write-guard");
+/**
+ * A second sentence for a refusal, appended **only** when the working tree's `memory.yaml` and the
+ * committed one actually differ — the diagnostic half of `task-090`'s `workingTreeWouldGrant`, on
+ * this surface.
+ *
+ * Under a committed baseline a refusal can contradict the file open in the user's editor, and
+ * `memory.yaml` is precisely the file an author edits while designing a new type or machine
+ * (`bug-081`'s Notes: "a half-finished edit is an ordinary state to be in"). So when the two copies
+ * disagree, say which one decided. It is computed *after* the decision and is empty on any failure
+ * to ask git, so no branch of it can change an outcome.
+ */
+function uncommittedMachineNote(root) {
+    try {
+        if ((0, storage_1.pathPorcelainStatus)(root, loaders_1.MEMORY_YAML_PATH) === '')
+            return '';
+    }
+    catch {
+        return '';
+    }
+    return (` — note that '${loaders_1.MEMORY_YAML_PATH}' carries uncommitted modifications and the state machine is read from the ` +
+        `committed copy (dl-080); commit '${loaders_1.MEMORY_YAML_PATH}' first if this transition depends on that change`);
+}
+/**
+ * Locate document `id` and resolve verb `op` on it, **against the `memory.yaml` committed at
+ * `HEAD`** (`loadMemoryYamlAtHead`).
+ *
+ * The baseline is the point (task-091, `bug-081`, `dl-080` option (B)). This function takes no
+ * `MemoryYaml`: a caller cannot hand it a working-tree machine even by accident, which is what makes
+ * the committed baseline a property of the read itself rather than of a precondition someone must
+ * remember to run. An uncommitted edit to a type's `sequence` used to decide both the transition a
+ * verb performed and the `status` it committed — through `memory submit`, which requires no
+ * authority — and stranded the element in a state the committed machine rejects.
+ *
+ * Refusals, all returned (never thrown) and all exit `1`:
+ *
+ * - `HEAD` holds no `memory.yaml` → `VALIDATION`, fail-closed: with no committed machine there is no
+ *   `from → to` to record, and the only fail-open available is the working tree, which is the defect.
+ *   `wingfoil init` commits the scaffold, so no legitimate flow reaches this;
+ * - the committed `memory.yaml` does not parse or validate → `VALIDATION`, same reasoning;
+ * - no document carries that frontmatter `id` → `NOT_FOUND` `document not found: <id>` (P1.6 sc.3);
+ * - its `type` is not registered → `NOT_FOUND` with `memory add`'s unknown-type message;
+ * - its `status` is not a state of the type → `VALIDATION` `invalid state '<s>' for type '<t>'`
+ *   (task-036's `validateFrontmatterState`);
+ * - the verb is illegal from that state → `INVALID_TRANSITION` with the `dl-032` contract message
+ *   (`resolveTypeTransition`), the engine's explanation in `details.issues[0].detail`.
+ *
+ * The last four keep their pinned messages verbatim as the first sentence;
+ * {@link uncommittedMachineNote} may append a second one.
+ */
+function prepareMemoryTransition(root, id, op) {
+    let memoryYaml;
+    try {
+        memoryYaml = (0, loaders_1.loadMemoryYamlAtHead)(root);
+    }
+    catch (error) {
+        if (!(error instanceof validation_1.ValidationError))
+            throw error;
+        return (0, types_1.coreErr)({
+            code: 'VALIDATION',
+            message: `cannot resolve the state machine: the committed '${loaders_1.MEMORY_YAML_PATH}' (at HEAD) is not readable as a Memory ` +
+                `configuration: ${error.message}. A transition is decided by the machine the repository records (dl-080), so ` +
+                'the committed file must be valid; fix it and commit the fix, then retry.',
+            details: { issues: error.issues },
+        });
+    }
+    if (memoryYaml === null) {
+        return (0, types_1.coreErr)({
+            code: 'VALIDATION',
+            message: `cannot resolve the state machine: '${loaders_1.MEMORY_YAML_PATH}' is not committed at HEAD. A transition is decided by ` +
+                `the machine the repository records, not by a working tree (dl-080); commit '${loaders_1.MEMORY_YAML_PATH}' first, then retry.`,
+        });
+    }
+    const found = (0, memory_1.findMemoryDocumentById)(root, memoryYaml, id);
+    if (!found) {
+        return (0, types_1.coreErr)({ code: 'NOT_FOUND', message: `document not found: ${id}${uncommittedMachineNote(root)}` });
+    }
+    const type = found.frontmatter.type;
+    if (typeof type !== 'string' || memoryYaml.types[type] === undefined) {
+        return (0, types_1.coreErr)({
+            code: 'NOT_FOUND',
+            message: `unknown memory type '${String(type)}' (not defined in memory.yaml)${uncommittedMachineNote(root)}`,
+        });
+    }
+    // Always resolves: the type is registered (checked immediately above), and since task-071
+    // (`bug-030-init-memory-yaml-has-no-state-machine`) a registered type with no `states` and no
+    // `defaults.states` falls back to the engine's built-in `DEFAULT_STATE_MACHINE` (REQ-STATE-08)
+    // instead of throwing. The `VALIDATION` refusal that used to guard this call is therefore gone with
+    // the condition it reported — the only throw left in `resolveStateMachine` is for an UNregistered
+    // type, which the `NOT_FOUND` above has already returned for.
+    const machine = (0, memory_1.resolveStateMachine)(memoryYaml, type);
+    const status = found.frontmatter.status;
+    // A missing or non-string `status` is reported as an invalid state, never as the text 'undefined'.
+    const from = typeof status === 'string' ? status : String(status ?? '');
+    try {
+        (0, memory_1.validateFrontmatterState)(machine, type, from, found.path);
+        const to = (0, memory_1.resolveTypeTransition)(memoryYaml, type, from, op, found.path);
+        const content = (0, storage_1.readDocument)((0, path_1.join)(root, found.path));
+        return (0, types_1.coreOk)({ memoryYaml, id, type, path: found.path, frontmatter: found.frontmatter, content, from, to });
+    }
+    catch (error) {
+        if (!(error instanceof validation_1.ValidationError))
+            throw error;
+        const code = error.issues.some((issue) => issue.code === memory_1.E_INVALID_TRANSITION) ? 'INVALID_TRANSITION' : 'VALIDATION';
+        const message = error.issues.map((issue) => issue.message).join('; ') + uncommittedMachineNote(root);
+        return (0, types_1.coreErr)({ code, message, details: { issues: error.issues } });
+    }
+}
+/**
+ * Refuse, before anything is written, a document that already carries modifications this transition
+ * does not own (task-088, `bug-076`; AC2 option (b)).
+ *
+ * `commitPaths` bounds a commit by **pathspec**, not by content: `git add -- <path>` stages the whole
+ * file, so an uncommitted body paragraph or an unowned frontmatter field rode into an approval under a
+ * subject declaring only a state change — and the old post-condition could not see it, because it
+ * compared the rendering against the same dirty file. Every recorded fact in such a commit is true
+ * (`P1.7`'s approver, timestamp and reason are all present and all correct); the commit is simply
+ * larger than what it claims.
+ *
+ * **Why refusing rather than committing only the status hunk.** Partial staging is undefined here
+ * before it is difficult: there are two candidate baselines on disk (the index and the working tree)
+ * and they can disagree, so "only the status hunk" does not say onto which text. Worse, the verb reads
+ * `status` itself from the working tree, so a hand-edited-but-uncommitted `status` would have the
+ * commit record `draft → approved` under a subject declaring `pending → approved` — the audit trail
+ * asserting something that did not happen, which is the defect, not a fix for it. And the edits a
+ * partial commit left behind would be invisible, deferred, and swept into whatever commits next. A
+ * refusal costs the user two commands, now, on a document this function has provably not touched.
+ *
+ * Runs only under `declared-fields-only`; `memory submit` is entitled to carry content and is
+ * therefore not guarded (see {@link DocumentScope}). The verb's own writes — `reject`'s
+ * `rejection_reason`, every verb's `status` — happen *after* this check, on text it has just certified
+ * equal to `HEAD`, so no verb is caught by its own guard.
+ *
+ * Since `task-092` the gate itself lives in {@link requireUnmodifiedTarget} (`./write-guard.ts`),
+ * shared with the six non-transition write verbs `dl-080` reaches through `bug-078`; only the wording
+ * below is this call site's own, so the two families cannot drift apart on what "modified" means.
+ */
+const TRANSITION_CONTRACT = {
+    noun: 'document',
+    owner: 'transition',
+    records: 'A state-transition commit records the status change and nothing else',
+};
+function requireUnmodifiedDocument(root, prepared) {
+    return (0, write_guard_1.requireUnmodifiedTarget)(root, prepared.path, TRANSITION_CONTRACT, prepared.content);
+}
+/**
+ * Verify what the new commit **contains**, by diffing it against its own parent (task-088, AC3).
+ *
+ * This is the half that makes the guard above checkable rather than hopeful. Reading the file on disk
+ * answers "does the document now say `approved`?" — true no matter what else rode along; `HEAD~1..HEAD`
+ * is not. Same shape as `task-080`'s lockfile guard: assert the diff, not the end state. The parent is
+ * `<sha>^`, or git's empty tree for a root commit, so the check is total rather than conditional.
+ *
+ * It is an **alarm, not a rollback**: it can only run once the commit exists, and rewriting history
+ * behind the user's back is a worse failure than reporting one (`dl-035` points the same way). With
+ * {@link requireUnmodifiedDocument} in place it should be unreachable, which is the point.
+ */
+function verifyCommittedScope(root, sha, path, expected, scope) {
+    // The "did anything else ride in" half is shared with `verifyCommittedPaths` (task-092), so the
+    // Memory and configuration post-conditions cannot disagree about what a commit's scope is.
+    const { parent, problems } = (0, write_guard_1.undeclaredCommittedPaths)(root, sha, [path]);
+    const after = (0, storage_1.readPathAtRev)(root, sha, path);
+    if (after === null)
+        return [...problems, `it does not contain '${path}'`];
+    return [...problems, ...(0, memory_1.verifyDocumentEdit)((0, storage_1.readPathAtRev)(root, parent, path) ?? '', after, expected, scope)];
+}
+/**
+ * Write `content` over the prepared document and commit exactly that one path with `message`,
+ * returning the new commit's sha (`commitPaths`, task-018; scoped to that path even when other changes
+ * are staged, bug-027). Callers must have run the git-identity pre-flight (REQ-SEC-01) and every refusal
+ * check first; this step is the only write.
+ *
+ * Four checks bound what reaches the repository, in this order — they are not redundant, they catch
+ * different defects:
+ *
+ * 1. **The document is the project's to write** ({@link requireConfinedWriteTarget}, REQ-SEC-06) —
+ *    catches a wrong *place*, in the two shapes a write can meet it. A type directory that is a
+ *    symlink out of the project puts the document outside the root (`bug-117`), where `writeDocument`
+ *    rewrites a file the repository does not own and `git add` then fails with its own text; and a
+ *    **document** that is itself a symlink does the same with no symlinked directory anywhere,
+ *    because `writeFileSync` follows the link that `unlinkSync` would merely remove (`bug-120` D2,
+ *    measured on all four verbs). `bug-117` reports the first for `memory add`, whose target is
+ *    resolved by `resolveConfinedMemoryPath`; these four verbs never ask that resolver anything —
+ *    they locate an existing document — so both questions are asked here, about the path they are
+ *    about to write. It runs **first**, and for every `scope`: the question "is this file ours at
+ *    all" precedes every question about its content, and check 2 cannot stand in for it (`git status
+ *    --porcelain` reports a path beyond a symbolic link as clean, which is `bug-118`).
+ * 2. **The working tree is unmodified** ({@link requireUnmodifiedDocument}, `declared-fields-only`
+ *    only) — catches a wrong *baseline*: content that was already on disk before the verb ran
+ *    (`bug-076`).
+ * 3. **The rendering is in scope** ({@link verifyDocumentEdit} against the prepared document) —
+ *    catches a defect in the *editor*: `status` must be the prepared target, every field in `expected`
+ *    must have its value (`undefined` = absent), and no other field and no byte of the body may have
+ *    moved (the `bug-041` class). Runs under `declared-fields-only` for **every** verb, `submit`
+ *    included: `renderSubmitDocument` owns `status` and `rejection_reason` alone, and the content
+ *    `submit` carries is already in the prepared document it is compared against.
+ * 4. **The commit contains only the declared change** ({@link verifyCommittedScope} against
+ *    `HEAD~1`) — the post-condition proper, and the only one that measures the artefact of record.
+ *
+ * Checks 1–3 report a `VALIDATION` error (exit 1) with nothing written or committed. Check 4 can
+ * only report; see {@link verifyCommittedScope}.
+ *
+ * Check 1 resolves on the **working tree**, not at `HEAD`, which departs from `command-baseline`'s
+ * rule for a gating read. The argument is `task-102`'s, recorded in
+ * `dl-086-a-guard-over-a-filesystem-effect-resolves-on-the-filesystem` (`in-discussion`) and cited
+ * rather than re-made: it predicts where `writeDocument` will land, and that follows the symlinks on
+ * disk rather than the ones a commit records.
+ *
+ * @param scope - How much of the document this operation owns; defaults to the strict
+ *   `declared-fields-only`, so a new verb is guarded unless it opts out deliberately.
+ */
+function commitMemoryTransition(root, prepared, content, message, expected = {}, scope = 'declared-fields-only') {
+    const owned = { status: prepared.to, ...expected };
+    const confined = (0, confinement_1.requireConfinedWriteTarget)(root, prepared.path, 'write');
+    if (!confined.ok)
+        return confined;
+    if (scope === 'declared-fields-only') {
+        const unmodified = requireUnmodifiedDocument(root, prepared);
+        if (!unmodified.ok)
+            return unmodified;
+    }
+    const problems = (0, memory_1.verifyDocumentEdit)(prepared.content, content, owned, 'declared-fields-only');
+    if (problems.length > 0) {
+        return (0, types_1.coreErr)({
+            code: 'VALIDATION',
+            message: `refusing to write ${prepared.path}: the rendered document failed its post-condition: ${problems.join('; ')}`,
+        });
+    }
+    (0, storage_1.writeDocument)((0, path_1.join)(root, prepared.path), content);
+    const sha = (0, storage_1.commitPaths)(root, [prepared.path], message);
+    const leaked = verifyCommittedScope(root, sha, prepared.path, owned, scope);
+    if (leaked.length > 0) {
+        return (0, types_1.coreErr)({
+            code: 'VALIDATION',
+            message: `commit ${sha} carries more than the change it declares: ${leaked.join('; ')}`,
+        });
+    }
+    return (0, types_1.coreOk)(sha);
+}
+//# sourceMappingURL=memory-transition.js.map

package/dist/core/memory-transition.js.map

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

package/dist/core/registry.d.ts

@@ -0,0 +1,189 @@
+/**
+ * The `CoreModule` registry shape (spec-006-core-domain-api §2, §4 — task-006). `src/cli` and
+ * `src/mcp` both import the same `CoreModule[]` array (`./index.ts`'s `CORE_MODULES`) and register
+ * every operation they find — neither surface is permitted a hardcoded allow/deny list of operation
+ * names (§4.2). This module owns: the registry types themselves, the one mechanical
+ * name-derivation function both adapters use to turn an operation's camelCase name into its CLI
+ * verb / MCP Tool-and-Resource verb segment (so neither adapter hand-maintains a second name
+ * mapping — spec-006 §5), a deterministic (REQ-SYS-07) enumerator, and the generic parity-diff
+ * primitive the REQ-SYS-05 fit criterion's "0 unmatched operations" assertion is built on.
+ */
+import type { CoreResult } from './types';
+/**
+ * The signature every core operation implements (spec-006 §2): an async function from typed params
+ * `P` to a `CoreResult<R>` — never a thrown error for an expected domain failure (see {@link CoreResult}).
+ */
+export type CoreFn<P, R> = (params: P) => Promise<CoreResult<R>>;
+/**
+ * One value-bearing CLI option an operation accepts (task-020-implement-memory-add) — e.g.
+ * `--type <value>`, `--title <value>`, `--tags <value>` for `memory add`. Distinct from
+ * {@link CoreOperation.flags}, which are BOOLEAN presence flags (`--list`): an option carries a
+ * string VALUE (`.option('--<name> <value>')`). `required` is declarative metadata: the operation's
+ * own `CoreFn` enforces it (throwing a `UsageError` → exit 2, consistent with `dna set`'s in-fn arg
+ * validation, task-025); it is surfaced here so `src/cli/program.ts` (and, later, the MCP Tool
+ * input schema) can describe the option without duplicating that knowledge. task-021's
+ * `memory submit`/etc. reuse this exact mechanism — the ONE value-option seam, not a parallel one.
+ */
+export interface CoreOption {
+    readonly name: string;
+    readonly required?: boolean;
+    /**
+     * What `--help` says about this option. Optional and additive: an option that declares none keeps
+     * the generic `"{name} value"` text `src/cli/program.ts` has always rendered. It exists because a
+     * convention a grammar cannot show must be *stated* somewhere a user reads — `dna add|remove|update
+     * --value` means the new entry's identity at a collection and the new value at a leaf
+     * (`dl-081-dna-mutation-surface-shape`, task-093), which is exactly the kind of thing that otherwise
+     * gets discovered rather than documented.
+     */
+    readonly description?: string;
+}
+/**
+ * One domain operation both surfaces derive from (spec-006 §2): its camelCase `name`, whether it
+ * `mutates` (Tool vs Resource / write vs read), its `fn`, and its optional declarative CLI `flags`
+ * and value-bearing `options`. The single source of truth `src/cli` and `src/mcp` register from.
+ */
+export interface CoreOperation<P = unknown, R = unknown> {
+    /** camelCase, `{module}{Verb}` (spec-006 §5) — e.g. `memoryApprove`, `dnaShow`. */
+    readonly name: string;
+    /** `true` => MCP Tool only; `false` => MCP Resource only. CLI exposes both regardless (§2). */
+    readonly mutates: boolean;
+    readonly fn: CoreFn<P, R>;
+    /**
+     * Boolean CLI flag names this operation accepts beyond the global flags (spec-008-cli-grammar §2)
+     * — e.g. `['list']` for `paths`'s `--list` drill-down flag (task-028-implement-paths-category,
+     * P2.5). Additive and optional: an operation that declares none keeps exactly the bare-`{ root }`
+     * (+ generic `positional`) shape task-026 established. The bare positional argument itself is NOT
+     * declared here — it stays the single generic `[positional]` `src/cli/program.ts` registers on
+     * every command (task-026's seam, {@link ParamsContext.positional}); only extra `--{name}` flags
+     * are per-operation, since Commander rejects an unknown option so each must be registered
+     * explicitly. `src/cli/program.ts` registers one `--{name}` option per entry and threads the
+     * parsed boolean into {@link ParamsContext.flags}.
+     */
+    readonly flags?: readonly string[];
+    /**
+     * Value-bearing CLI options this operation accepts beyond the global options
+     * (task-020-implement-memory-add — e.g. `[{name:'type',required:true}, {name:'title',required:true},
+     * {name:'tags'}]` for `memory add`). Additive alongside {@link flags}: an operation declaring none
+     * keeps exactly the bare shape it had before. `src/cli/program.ts` registers one
+     * `--{name} <value>` Commander option per entry and threads the parsed values into
+     * {@link ParamsContext.options}; the MCP surface never populates them (task-030 wires the Tool input
+     * schema). See {@link CoreOption}.
+     */
+    readonly options?: readonly CoreOption[];
+}
+/** One pillar's operation group (spec-006 §2) — a `name` (the `wingfoil <noun>` segment) and its operations. */
+export interface CoreModule {
+    /** e.g. `"memory"`, `"dna"`, `"workflow"`, `"directives"` — the `wingfoil <noun>` segment. */
+    readonly name: string;
+    /** This module's operations, keyed by camelCase operation name (see {@link CoreOperation}). */
+    readonly operations: Readonly<Record<string, CoreOperation>>;
+}
+/** One operation, paired with the module that declares it — the flat shape both adapters iterate. */
+export interface EnumeratedOperation {
+    readonly module: CoreModule;
+    readonly operation: CoreOperation;
+}
+/**
+ * Flatten `modules` into every declared operation, sorted deterministically by `(module.name,
+ * operation.name)` (REQ-SYS-07 — no unordered `Object.values`/iteration in a context-building
+ * path). Both `src/cli` and `src/mcp` register from this single enumerator, never from their own
+ * ad hoc traversal of `modules`/`Object.keys`.
+ */
+export declare function enumerateOperations(modules: readonly CoreModule[]): EnumeratedOperation[];
+/**
+ * Derive an operation's CLI verb / MCP verb segment from its camelCase `{module}{Verb}` name
+ * (spec-006 §5), mechanically — this plus `mutates` is "the one place surface-routing logic
+ * lives" (§2): given `moduleName = "memory"` and `operationName = "memoryApprove"`, returns
+ * `"approve"`; a multi-word verb (`"workflowSetTeam"`) becomes kebab-case (`"set-team"`) so it
+ * renders as a single CLI token / Tool-name segment. Falls back to the full operation name,
+ * kebab-cased, when it does not start with the module's name — a config mistake the caller should
+ * catch earlier, but this function degrades rather than throwing, so a single bad registration
+ * cannot crash an adapter's entire registration pass.
+ */
+export declare function deriveVerb(moduleName: string, operationName: string): string;
+/**
+ * What a surface adapter (`src/cli`, `src/mcp`) knows about the call it is about to make — enough
+ * for a caller-supplied {@link ParamsBuilder} to construct that operation's actual typed params.
+ * Neither adapter hardcodes per-operation argv/Tool-input parsing here (that is each future
+ * operation's own CLI-command / Tool-input-schema spec, per spec-005's own scope note) — every
+ * operation registered through task-006/task-027 took a bare `{ root }`; task-028-implement-paths-category
+ * is the first to need more, and does so exactly the way this interface's doc comment always
+ * anticipated: a richer `buildParams`, not a registrar change. `positional` is registered
+ * generically as a single `[positional]` on every derived CLI command (`src/cli/program.ts`) and
+ * threaded through `command.run` into `ctx.positional`; `flags` is populated from the matching
+ * operation's `CoreOperation.flags` declaration (`./registry.ts`). The MCP adapter's own mechanical,
+ * zero-argument Resource/Tool registration (`src/mcp/registrar.ts`) never populates either — a
+ * `buildParams` that ignores both (every `ParamsBuilder` before this task) keeps working unchanged.
+ */
+export interface ParamsContext {
+    readonly moduleName: string;
+    readonly operationName: string;
+    readonly root: string;
+    /**
+     * The bare CLI positional argument following `<noun> <verb>` (or `<noun>` for a flat command),
+     * if the invocation supplied one (e.g. `wingfoil dna show tech_stack` -> `"tech_stack"`,
+     * `wingfoil paths sources` -> `"sources"`) — task-026-implement-dna-show's generic seam, kept as
+     * the single source of truth. Deliberately singular and untyped beyond `string | undefined`: any
+     * operation's `buildParams` reads it under whatever param name that operation's own `CoreFn`
+     * expects (`dnaShow`'s `section`, `paths`'s `category`), and an operation needing a *required*
+     * positional still owns that validation in its own `CoreFn` — this seam only carries the raw
+     * value from the CLI adapter through to `buildParams`. The MCP surface has no equivalent
+     * mechanical concept today (a zero-argument Resource template can't carry one — spec-004 §2.1's
+     * own `wingfoil://dna/{section}` addressing is the MCP-side answer, wired independently in
+     * `src/mcp/dna-resource.ts`), so an MCP `buildParams` simply never sets this field.
+     */
+    readonly positional?: string;
+    /**
+     * The FULL list of bare CLI positional arguments following `<noun> <verb>` (or `<noun>` for a flat
+     * command) — task-025-implement-dna-set's additive extension of the single-`positional` seam, needed
+     * by the first operation taking two data inputs (`dna set <key> <value>` -> `['<key>', '<value>']`).
+     * Since `dl-082-cli-parameter-shape` (task-093) every command reads at most ONE positional — the
+     * identity of its target — and `dna set`'s value travels in `--value`, so the list is now a
+     * uniform seam rather than one shaped by a single two-input verb; it stays variadic so an
+     * operation can refuse an extra positional with its own message.
+     * {@link positional} is exactly `positionals?.[0]` and is kept unchanged for the single-positional
+     * read ops that predate this (`dna show [section]`, `paths [category]`), so their `buildParams` and
+     * `CoreFn`s are untouched; an op that must validate its positional (`dnaSet` and the three mutation
+     * verbs, which reject an extra one) reads `positionals`
+     * instead. Same additive contract as {@link positional}/{@link flags}: the MCP surface never
+     * populates it (a zero-argument Tool/Resource template carries no positional — see {@link positional}),
+     * so an MCP `buildParams` simply never sets it.
+     */
+    readonly positionals?: readonly string[];
+    /**
+     * This operation's declared {@link CoreOperation.flags} names mapped to their parsed boolean
+     * values (task-028-implement-paths-category — e.g. `{ list: true }` for `wingfoil paths sources
+     * --list`). Additive alongside `positional`: an operation declaring no flags never has this set,
+     * and the MCP surface never populates it (same rationale as `positional`).
+     */
+    readonly flags?: Readonly<Record<string, boolean>>;
+    /**
+     * This operation's declared {@link CoreOperation.options} names mapped to their parsed string
+     * VALUES (task-020-implement-memory-add — e.g. `{ type: 'decision', title: 'Use PostgreSQL' }` for
+     * `wingfoil memory add --type decision --title 'Use PostgreSQL'`). Additive alongside `flags`: an
+     * operation declaring no value options never has this set, and the MCP surface never populates it
+     * (a zero-argument Tool template carries none — same rationale as `positional`/`flags`; task-030
+     * wires the MCP Tool input schema separately). An absent optional option is simply omitted from the
+     * record rather than present-as-`undefined`.
+     */
+    readonly options?: Readonly<Record<string, string>>;
+}
+/**
+ * A surface-supplied function that turns a {@link ParamsContext} into the typed params one operation's
+ * {@link CoreFn} expects — the single per-surface seam where CLI/MCP-specific argument shaping lives,
+ * so the registrars stay operation-agnostic (spec-006 §2).
+ */
+export type ParamsBuilder = (ctx: ParamsContext) => unknown;
+/** The result of {@link computeParityDiff}: entries present on only one side, each sorted. */
+export interface ParityDiff {
+    readonly onlyInA: readonly string[];
+    readonly onlyInB: readonly string[];
+}
+/**
+ * Set-difference both ways between two enumerations of the same kind of key (e.g. `"noun verb"`
+ * CLI commands vs. the same keys' MCP Tool names, normalized to a common form by the caller) —
+ * the REQ-SYS-05 fit-criterion primitive: "reports 0 [operations] without a matching [counterpart]"
+ * in each direction. Both output lists are sorted, independent of input order (REQ-SYS-07).
+ */
+export declare function computeParityDiff(a: readonly string[], b: readonly string[]): ParityDiff;
+//# sourceMappingURL=registry.d.ts.map

package/dist/core/registry.d.ts.map

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