wingfoil 0.2.1

package/dist/core/index.js

@@ -0,0 +1,1331 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CORE_MODULES = exports.dnaEntryFieldOfOption = exports.dnaEntryOptionName = exports.DNA_ENTRY_OPTION_PREFIX = exports.verifyBuiltinTemplates = exports.verifyCommittedPaths = exports.undeclaredCommittedPaths = exports.requireUnmodifiedTargets = exports.requireUnmodifiedTarget = exports.requireAbsentTarget = exports.committedScopeError = exports.CONFIG_WRITE_CONTRACT = exports.resolveAddType = exports.verifyCommittedScope = exports.prepareMemoryTransition = exports.commitMemoryTransition = exports.NO_RELEVANT_MEMORY_NOTE = exports.filterRelevantMemoryDocuments = exports.DEFAULT_CONTEXT_LIMITS = exports.WINGFOIL_ALREADY_INITIALIZED = exports.initWingfoilProject = exports.initWingfoilStorage = exports.UNASSIGNED_ASSIGNMENT = exports.GLOBAL_ASSIGNMENT = exports.loadDirectiveListing = exports.buildDirectiveListing = exports.selectDirectivesById = exports.resolveRoleDirectives = exports.assembleExecutionContext = exports.loadWorkflowsYaml = exports.loadRolesYamlAtHead = exports.loadRolesYaml = exports.loadMemoryYamlAtHead = exports.loadMemoryYaml = exports.loadDnaYamlAtHead = exports.loadDnaYaml = exports.loadDirectivesAtHead = exports.loadDirectives = exports.ROLES_YAML_PATH = exports.MEMORY_YAML_PATH = exports.DNA_YAML_PATH = exports.DIRECTIVES_DIR_PATH = exports.MODULE_NAME = void 0;
+/**
+ * `core` module — shared domain logic; single behavior behind both the CLI and MCP surfaces
+ * (REQ-SYS-05). Exposes one loader per Project pillar (task-004-decoupled-pillars, REQ-SYS-02):
+ * `loadMemoryYaml`, `loadDnaYaml`, `loadWorkflowsYaml`, `loadDirectives` — each independently reads
+ * and validates only its own pillar's artifact(s), so editing one pillar's config never requires
+ * touching another's loader.
+ *
+ * task-006-dual-interface-shared-core adds the `CoreModule` registry (spec-006-core-domain-api):
+ * `CORE_MODULES` below is the single array `src/cli` and `src/mcp` both derive their surfaces
+ * from. It is intentionally small today — see the SCOPE note on `CORE_MODULES` — the full
+ * memory/dna/directives/workflow domain-operation tables in spec-006 §3 (`memoryAdd`, `dnaSet`,
+ * `directiveCreate`, ...) are feature work for task-018..030, not this task.
+ */
+const path_1 = require("path");
+const js_yaml_1 = require("js-yaml");
+const validation_1 = require("../validation");
+const schema_1 = require("../dna/schema");
+const edit_1 = require("../dna/edit");
+const mutate_1 = require("../dna/mutate");
+const path_2 = require("../dna/path");
+const set_1 = require("../dna/set");
+const create_1 = require("../directives/create");
+const roles_edit_1 = require("../directives/roles-edit");
+const storage_1 = require("../storage");
+// Not re-exported by the `../storage` barrel, imported directly per that module's own convention
+// (same as `src/memory/entry.ts`): `memory add` needs the CONFINED target path before it writes, to
+// run task-092's absence guard on it.
+const memory_path_1 = require("../storage/memory-path");
+const memory_1 = require("../memory");
+const loaders_1 = require("./loaders");
+const directives_list_1 = require("./directives-list");
+const context_1 = require("./context");
+const directive_assign_1 = require("./directive-assign");
+const git_identity_1 = require("./git-identity");
+const builtin_asset_1 = require("./builtin-asset");
+const confinement_1 = require("./confinement");
+const approval_authority_1 = require("./approval-authority");
+const require_reason_1 = require("./require-reason");
+const memory_transition_1 = require("./memory-transition");
+const memory_add_type_1 = require("./memory-add-type");
+const write_guard_1 = require("./write-guard");
+const usage_error_1 = require("./usage-error");
+const types_1 = require("./types");
+/** This module's `dna.yaml` name (`core`) — the stable identifier surfaces and tests key it by. */
+exports.MODULE_NAME = 'core';
+var loaders_2 = require("./loaders");
+Object.defineProperty(exports, "DIRECTIVES_DIR_PATH", { enumerable: true, get: function () { return loaders_2.DIRECTIVES_DIR_PATH; } });
+Object.defineProperty(exports, "DNA_YAML_PATH", { enumerable: true, get: function () { return loaders_2.DNA_YAML_PATH; } });
+Object.defineProperty(exports, "MEMORY_YAML_PATH", { enumerable: true, get: function () { return loaders_2.MEMORY_YAML_PATH; } });
+Object.defineProperty(exports, "ROLES_YAML_PATH", { enumerable: true, get: function () { return loaders_2.ROLES_YAML_PATH; } });
+Object.defineProperty(exports, "loadDirectives", { enumerable: true, get: function () { return loaders_2.loadDirectives; } });
+// The committed-baseline readers `dl-080` (B) makes the rule for any read that gates an operation.
+// task-090 kept `loadDnaYamlAtHead` private while that rule was undecided; it is decided now, and a
+// facility the ruling tells the next implementer to use has to be reachable (task-091, D3).
+Object.defineProperty(exports, "loadDirectivesAtHead", { enumerable: true, get: function () { return loaders_2.loadDirectivesAtHead; } });
+Object.defineProperty(exports, "loadDnaYaml", { enumerable: true, get: function () { return loaders_2.loadDnaYaml; } });
+Object.defineProperty(exports, "loadDnaYamlAtHead", { enumerable: true, get: function () { return loaders_2.loadDnaYamlAtHead; } });
+Object.defineProperty(exports, "loadMemoryYaml", { enumerable: true, get: function () { return loaders_2.loadMemoryYaml; } });
+Object.defineProperty(exports, "loadMemoryYamlAtHead", { enumerable: true, get: function () { return loaders_2.loadMemoryYamlAtHead; } });
+Object.defineProperty(exports, "loadRolesYaml", { enumerable: true, get: function () { return loaders_2.loadRolesYaml; } });
+Object.defineProperty(exports, "loadRolesYamlAtHead", { enumerable: true, get: function () { return loaders_2.loadRolesYamlAtHead; } });
+Object.defineProperty(exports, "loadWorkflowsYaml", { enumerable: true, get: function () { return loaders_2.loadWorkflowsYaml; } });
+var context_2 = require("./context");
+Object.defineProperty(exports, "assembleExecutionContext", { enumerable: true, get: function () { return context_2.assembleExecutionContext; } });
+Object.defineProperty(exports, "resolveRoleDirectives", { enumerable: true, get: function () { return context_2.resolveRoleDirectives; } });
+Object.defineProperty(exports, "selectDirectivesById", { enumerable: true, get: function () { return context_2.selectDirectivesById; } });
+var directives_list_2 = require("./directives-list");
+Object.defineProperty(exports, "buildDirectiveListing", { enumerable: true, get: function () { return directives_list_2.buildDirectiveListing; } });
+Object.defineProperty(exports, "loadDirectiveListing", { enumerable: true, get: function () { return directives_list_2.loadDirectiveListing; } });
+Object.defineProperty(exports, "GLOBAL_ASSIGNMENT", { enumerable: true, get: function () { return directives_list_2.GLOBAL_ASSIGNMENT; } });
+Object.defineProperty(exports, "UNASSIGNED_ASSIGNMENT", { enumerable: true, get: function () { return directives_list_2.UNASSIGNED_ASSIGNMENT; } });
+__exportStar(require("./types"), exports);
+__exportStar(require("./registry"), exports);
+__exportStar(require("./exit-code"), exports);
+__exportStar(require("./git-identity"), exports);
+__exportStar(require("./approval-authority"), exports);
+__exportStar(require("./require-reason"), exports);
+__exportStar(require("./builtin-asset"), exports);
+__exportStar(require("./confinement"), exports);
+__exportStar(require("./usage-error"), exports);
+var init_1 = require("./init");
+Object.defineProperty(exports, "initWingfoilStorage", { enumerable: true, get: function () { return init_1.initWingfoilStorage; } });
+Object.defineProperty(exports, "initWingfoilProject", { enumerable: true, get: function () { return init_1.initWingfoilProject; } });
+Object.defineProperty(exports, "WINGFOIL_ALREADY_INITIALIZED", { enumerable: true, get: function () { return init_1.WINGFOIL_ALREADY_INITIALIZED; } });
+var relevance_1 = require("./relevance");
+Object.defineProperty(exports, "DEFAULT_CONTEXT_LIMITS", { enumerable: true, get: function () { return relevance_1.DEFAULT_CONTEXT_LIMITS; } });
+Object.defineProperty(exports, "filterRelevantMemoryDocuments", { enumerable: true, get: function () { return relevance_1.filterRelevantMemoryDocuments; } });
+Object.defineProperty(exports, "NO_RELEVANT_MEMORY_NOTE", { enumerable: true, get: function () { return relevance_1.NO_RELEVANT_MEMORY_NOTE; } });
+var memory_transition_2 = require("./memory-transition");
+Object.defineProperty(exports, "commitMemoryTransition", { enumerable: true, get: function () { return memory_transition_2.commitMemoryTransition; } });
+Object.defineProperty(exports, "prepareMemoryTransition", { enumerable: true, get: function () { return memory_transition_2.prepareMemoryTransition; } });
+Object.defineProperty(exports, "verifyCommittedScope", { enumerable: true, get: function () { return memory_transition_2.verifyCommittedScope; } });
+var memory_add_type_2 = require("./memory-add-type");
+Object.defineProperty(exports, "resolveAddType", { enumerable: true, get: function () { return memory_add_type_2.resolveAddType; } });
+var write_guard_2 = require("./write-guard");
+Object.defineProperty(exports, "CONFIG_WRITE_CONTRACT", { enumerable: true, get: function () { return write_guard_2.CONFIG_WRITE_CONTRACT; } });
+Object.defineProperty(exports, "committedScopeError", { enumerable: true, get: function () { return write_guard_2.committedScopeError; } });
+Object.defineProperty(exports, "requireAbsentTarget", { enumerable: true, get: function () { return write_guard_2.requireAbsentTarget; } });
+Object.defineProperty(exports, "requireUnmodifiedTarget", { enumerable: true, get: function () { return write_guard_2.requireUnmodifiedTarget; } });
+Object.defineProperty(exports, "requireUnmodifiedTargets", { enumerable: true, get: function () { return write_guard_2.requireUnmodifiedTargets; } });
+Object.defineProperty(exports, "undeclaredCommittedPaths", { enumerable: true, get: function () { return write_guard_2.undeclaredCommittedPaths; } });
+Object.defineProperty(exports, "verifyCommittedPaths", { enumerable: true, get: function () { return write_guard_2.verifyCommittedPaths; } });
+var builtin_integrity_1 = require("./builtin-integrity");
+Object.defineProperty(exports, "verifyBuiltinTemplates", { enumerable: true, get: function () { return builtin_integrity_1.verifyBuiltinTemplates; } });
+/**
+ * Run a synchronous, throwing pillar loader (task-004's `load*` functions) and map its expected
+ * failures onto a `CoreResult` (spec-006 §2): a `ValidationError` from the shared two-pass pipeline
+ * becomes `VALIDATION`, a missing file (Node's `ENOENT`) becomes `NOT_FOUND`; anything else
+ * propagates as a genuine thrown exception (a programmer bug, not a domain failure — spec-006 §2's
+ * "no function throws for *expected* domain failures" implies unexpected ones still may). Factored
+ * out of `wrapReadOnly` so both `dnaShowFn` (task-026) and `pathsFn` (task-028) reuse the exact
+ * same mapping for their own richer, argument-aware bodies instead of duplicating it.
+ */
+function loadOrError(loader) {
+    try {
+        return (0, types_1.coreOk)(loader());
+    }
+    catch (error) {
+        if (error instanceof validation_1.ValidationError) {
+            return (0, types_1.coreErr)({ code: 'VALIDATION', message: error.message, details: { issues: error.issues } });
+        }
+        const errno = error;
+        if (errno && errno.code === 'ENOENT') {
+            return (0, types_1.coreErr)({ code: 'NOT_FOUND', message: errno.message });
+        }
+        throw error;
+    }
+}
+/** Adapt a synchronous, throwing pillar loader into a `CoreFn` taking just `{ root }` (spec-006 §2). */
+function wrapReadOnly(loader) {
+    return async (params) => {
+        const { root } = params;
+        return loadOrError(() => loader(root));
+    };
+}
+/**
+ * `paths` `CoreOperation.fn` (P2.5, spec-002-dna-yaml-schema's `Paths` node) —
+ * task-028-implement-paths-category. Loads `.wingfoil/dna.yaml` via the same `loadOrError` +
+ * `loadDnaYaml` path `dnaShowFn` uses, then narrows to one category (the bare positional):
+ *
+ * - category given and mapped (a non-empty array) -> `coreOk({category, paths})` (spec-005 §4 shape).
+ * - category given but absent/empty in `paths:` -> `coreErr(NOT_FOUND, "no paths mapped for
+ *   category '<category>'")` — the exact BDD `P2.5-paths.feature` "Error - querying an undefined
+ *   category" wording (exit `1` via `exit-code.ts`, never a throw, never exit `2` — a read-only
+ *   command, spec-005 §1; symmetric with `dnaShowFn`'s own unknown-section `NOT_FOUND`).
+ * - category omitted -> `coreOk(<whole paths node>)` (see {@link PathsParams}'s doc comment on why;
+ *   symmetric with `dna show` returning the whole DNA when no section is given).
+ *
+ * `dna.paths` is `.passthrough()` (spec-002), so an entry beyond the five named categories is still a
+ * plain object property here, not necessarily an array — `Array.isArray` guards that case rather than
+ * assuming the shape.
+ */
+const pathsFn = async (params) => {
+    const { root, positional: category } = params;
+    const loaded = loadOrError(() => (0, loaders_1.loadDnaYaml)(root));
+    if (!loaded.ok)
+        return loaded;
+    if (category === undefined)
+        return (0, types_1.coreOk)(loaded.value.paths);
+    const raw = loaded.value.paths[category];
+    const entries = Array.isArray(raw) ? raw : undefined;
+    if (!entries || entries.length === 0) {
+        return (0, types_1.coreErr)({ code: 'NOT_FOUND', message: `no paths mapped for category '${category}'` });
+    }
+    return (0, types_1.coreOk)({ category, paths: entries });
+};
+/**
+ * `dna show [section]` (P2.2-implement-dna-show, task-026): resolves `ParamsContext.positional`
+ * (`core/registry.ts` — the generic CLI-positional seam this task adds) as an optional DNA section
+ * name. No `positional` -> the whole parsed `DnaYaml` (unchanged behavior, what the MCP
+ * `wingfoil://dna/show` Resource still gets, since the MCP surface never sets this field — see
+ * `ParamsContext.positional`'s own doc comment). `tech_stack` resolves as a BDD-compatibility alias
+ * for `stacks` (spec-002-dna-yaml-schema Consequences: the schema renamed the BDD's `tech_stack`
+ * wording). An unknown section is a domain `NOT_FOUND` (`CoreResult.error`, exit `1` via
+ * `exit-code.ts` — never a thrown exception and never exit `2`, since a read-only command can only
+ * exit `0`/`1` per spec-005-cli-command-contract §1), with the exact P2.2 message
+ * `no DNA key named '<section>'`. The `tech_stack`→`stacks` alias is the shared `DNA_KEY_ALIASES`
+ * (`src/dna/set.ts`) — the single source of truth `dna set` uses too, so read and write stay symmetric.
+ */
+const dnaShowFn = async (params) => {
+    const { root, positional: section } = params;
+    const loaded = loadOrError(() => (0, loaders_1.loadDnaYaml)(root));
+    if (!loaded.ok || section === undefined)
+        return loaded;
+    const key = set_1.DNA_KEY_ALIASES[section] ?? section;
+    const dna = loaded.value;
+    if (!(key in dna)) {
+        return (0, types_1.coreErr)({ code: 'NOT_FOUND', message: `no DNA key named '${section}'` });
+    }
+    return (0, types_1.coreOk)(dna[key]);
+};
+/**
+ * The shared body of every DNA mutation (`dna set`, and `dna add|remove|update` since
+ * task-093-dna-mutation-surface-add-remove-update) — the mutating-op template `dna set` established
+ * (P2.1, task-025), now with one structure-aware traversal underneath all four verbs:
+ *
+ * 1. **`requireGitIdentity` pre-flight** (REQ-SEC-01, task-014) — refuse before any read/write when
+ *    `user.name`/`user.email` are unset, returning its `CoreResult.error` unchanged (exit 1).
+ * 2. **Argument validation** — a missing required argument, or a dotted path `splitDnaPath` cannot
+ *    parse (an empty segment, the BDD's `..language`; an unterminated quote; a `"` no delimiter can
+ *    account for), is a usage error: `throw new UsageError(...)` → exit **2**
+ *    (mapped by `exitCodeForThrow`), per spec-005-cli-command-contract §1. A path that is well-formed
+ *    but names nothing the schema declares is a different failure and exits **1** — see step 4.
+ * 3. **`requireUnmodifiedTarget` pre-flight** (`dl-080`(B) / `bug-078`, task-092) — refuse, before
+ *    anything is read or written, while `dna.yaml` carries modifications this operation does not own.
+ *    The plain "refuse a dirty target" rule applies here unaltered: all four verbs **edit an existing
+ *    file in place**, so `task-092`'s two exceptions are both inapplicable — `requireAbsentTarget` is
+ *    for a target that must be new (`memory add`), and `wingfoil init`'s exemption rests on
+ *    `detectInitState` refusing an initialized project before a guard could run, whereas these verbs
+ *    *require* an initialized project and load `dna.yaml` as their input. Placed before the load, so
+ *    no refusal and no written byte can depend on a value the dirty copy contributed — which is also
+ *    what makes `loadDnaYaml`'s working-tree read equivalent to `HEAD`'s here.
+ * 4. **Load** the current `.wingfoil/dna.yaml` through the same two-pass path `dnaShow` uses (a
+ *    missing/invalid file → `NOT_FOUND`/`VALIDATION`, exit 1).
+ * 5. **Resolve + apply** through `src/dna`'s `applyDnaMutation`, which resolves the `<path>` against
+ *    `DnaYaml` itself and **refuses a path that does not resolve rather than creating it**
+ *    (`bug-084-dna-key-alias-writes-unschemad-keys`; `dl-081`'s ratification makes this a precondition
+ *    of the surface). A refusal is a logic error (`VALIDATION` → exit 1, `spec-005` §1 as ruled on
+ *    `bug-076`), returned not thrown, and nothing is written.
+ * 6. **Produce the new bytes.** The PRIMARY path is `src/dna`'s `applyDnaEditInText`: a minimal
+ *    in-place textual edit, so every comment survives — including the inline `[SPEC]`/`[AUTHORING]`
+ *    field-provenance annotations a whole-file re-serialization deletes
+ *    (bug-004-dna-set-strips-yaml-comments, task-063). When no provably-minimal edit exists it returns
+ *    `undefined` and this FALLS BACK to `dump(dna, { lineWidth: -1 })` — correct, but comment-stripping.
+ *    Both paths are deterministic (REQ-SYS-07).
+ * 7. **Re-validate the written bytes** against `DnaYaml` (spec-002) BEFORE persisting — re-parsing the
+ *    serialized form, not the in-memory object, so the check honours YAML's own scalar coercion and
+ *    validates the exact bytes about to be written (`dna set version 2` writes `version: '2'` and
+ *    still fails `z.number()` on read-back). It is also what enforces the cross-field rules the verbs
+ *    do not duplicate: a member naming a role absent from `team.roles` fails here (REQ-SYS-08,
+ *    `Team.superRefine`), which is why `dl-081` records that referential integrity needs no new check.
+ * 8. **Persist + commit** through the single storage primitives (task-018) — `writeDocument` then
+ *    `commitPaths` on the ONE scoped path `.wingfoil/dna.yaml`; the returned sha rides
+ *    `CoreResult.commit`. Writing the bytes already on disk is an idempotent no-op: no write, no
+ *    empty commit.
+ * 9. **`committedScopeError` post-condition** (task-092) — assert the commit carries exactly the
+ *    bytes this operation wrote at that one path and nothing else. An alarm rather than a rollback:
+ *    with the step-3 guard in place no argument can reach it, but a repository-local `pre-commit`
+ *    hook that rewrites and re-stages the file still can.
+ */
+async function runDnaMutation(root, request, subject = dnaCommitSubject(request), scalarOnly = false) {
+    const identity = (0, git_identity_1.requireGitIdentity)(root);
+    if (!identity.ok)
+        return identity;
+    const unmodified = (0, write_guard_1.requireUnmodifiedTarget)(root, loaders_1.DNA_YAML_PATH);
+    if (!unmodified.ok)
+        return unmodified;
+    const loaded = loadOrError(() => (0, loaders_1.loadDnaYaml)(root));
+    if (!loaded.ok)
+        return loaded;
+    if (scalarOnly) {
+        const resolved = (0, path_2.resolveDnaPath)(loaded.value, request.field);
+        if (!resolved.ok)
+            return (0, types_1.coreErr)({ code: 'VALIDATION', message: resolved.message });
+        if (resolved.target.kind !== 'scalar') {
+            return (0, types_1.coreErr)({
+                code: 'VALIDATION',
+                message: `'${request.field}' does not hold a single value: reach it with \`dna add|remove|update ${request.field} --value <v>\` (dl-081)`,
+            });
+        }
+    }
+    const applied = (0, mutate_1.applyDnaMutation)(loaded.value, request);
+    if (!applied.ok)
+        return (0, types_1.coreErr)({ code: 'VALIDATION', message: applied.message });
+    const dnaPath = (0, path_1.join)(root, loaders_1.DNA_YAML_PATH);
+    const current = (0, storage_1.readDocument)(dnaPath);
+    const serialized = (0, edit_1.applyDnaEditInText)(current, applied.edit, applied.dna) ?? (0, js_yaml_1.dump)(applied.dna, { lineWidth: -1 });
+    const parsed = schema_1.DnaYaml.safeParse((0, validation_1.parseYaml)(serialized, dnaPath));
+    if (!parsed.success) {
+        const validationError = (0, validation_1.toValidationError)(parsed.error, dnaPath);
+        return (0, types_1.coreErr)({ code: 'VALIDATION', message: validationError.message, details: { issues: validationError.issues } });
+    }
+    const outcome = { key: request.field, value: request.value };
+    if (current === serialized)
+        return (0, types_1.coreOk)(outcome);
+    (0, storage_1.writeDocument)(dnaPath, serialized);
+    const sha = (0, storage_1.commitPaths)(root, [loaders_1.DNA_YAML_PATH], subject);
+    const leaked = (0, write_guard_1.committedScopeError)(root, sha, loaders_1.DNA_YAML_PATH, serialized);
+    if (leaked)
+        return leaked;
+    return (0, types_1.coreOk)(outcome, { sha, message: subject });
+}
+/**
+ * The one-line commit subject a DNA mutation writes: `wf(dna): {verb} {field} [{value}]`, extending
+ * `dna set`'s established `wf(dna): set {key}` (task-025) with the payload, because for `add` and
+ * `remove` the value IS which entry was touched and a subject without it reads as if the whole
+ * collection changed. Deterministic — a pure function of the request (REQ-SYS-07).
+ */
+function dnaCommitSubject(request) {
+    return `wf(dna): ${request.verb} ${request.field}${request.value === undefined ? '' : ` ${request.value}`}`;
+}
+/**
+ * The dotted path every DNA verb acts on, read from `positionals[0]` — the ONE place the four verbs
+ * agree on where their target comes from (`dl-082-cli-parameter-shape`: a positional carries the
+ * identity of the target).
+ *
+ * Three usage errors, in the order they are checked, and the order is load-bearing:
+ *
+ * 1. **Missing** — nothing to act on.
+ * 2. **Unparseable** — whatever `splitDnaPath` (`src/dna/set.ts`) refuses, reported with **its own**
+ *    message rather than a flat one, because the three cases are not the same complaint: an empty
+ *    segment (the BDD's `..language`) is malformed, an unterminated quote is a typo in the
+ *    delimiters, and a `"` no delimiter can account for means the *name* has no spelling at all
+ *    (`dl-083-dotted-entry-names-in-paths`, task-099). Checked BEFORE the extra-positional rule below
+ *    so that `dna set ..language python`, which is `P2.1-dna-set.feature`'s third scenario verbatim,
+ *    keeps reporting `invalid key path: '..language'` rather than the migration hint. A stale
+ *    invocation that is also malformed is malformed first.
+ * 3. **Extra positionals** — the old `dna set <key> <value>` spelling, and any slip of the same
+ *    shape on the three new verbs. It gets a named message rather than being ignored, because
+ *    `dl-082` is a breaking change to a shipped command and silently dropping the second word would
+ *    make `dna set project.license MIT` look like it worked (`--value` absent, the write refused for
+ *    a reason that names neither the second word nor the new grammar).
+ *
+ * All three are exit `2` (`UsageError` → `exitCodeForThrow`, `spec-005-cli-command-contract` §1).
+ */
+function dnaPathPositional(verb, positionals) {
+    const path = positionals?.[0];
+    if (path === undefined) {
+        throw new usage_error_1.UsageError(`missing required argument: wingfoil dna ${verb} <path> --value <value>`);
+    }
+    const split = (0, set_1.splitDnaPath)(path);
+    if (!split.ok) {
+        throw new usage_error_1.UsageError(split.message);
+    }
+    if ((positionals?.length ?? 0) > 1) {
+        throw new usage_error_1.UsageError(`wingfoil dna ${verb} takes one positional <path>; the value travels in --value (got ${positionals.length} positionals)`);
+    }
+    return path;
+}
+/**
+ * `dna set <path> --value <v>` `CoreOperation.fn` (P2.1) — kept, and still the scalar spelling
+ * (`spec-002`, `spec-005` §4). Since task-093 it is **`update` restricted to a single value**: the
+ * same resolver, the same write path, one spelling for the scalar case and
+ * `dna update <path> --value …` for everything structured (`dl-081` AC9 — `update` does not subsume
+ * `set`, and `set` does not grow a second mechanism).
+ *
+ * Its **second positional became `--value`** in this task (`dl-082-cli-parameter-shape`): the key was
+ * the target and stays positional, the value was an attribute wearing a positional's clothes. That is
+ * a breaking change to a shipped command, tracked as such — `P2.1-dna-set.feature` still shows the
+ * old spelling and is rewritten by `bug-089`, and `CHANGELOG.md` by the `user-docs` phase.
+ *
+ * A path that names a collection or a list is refused here with the verb that does reach it, rather
+ * than with the schema re-validation's `expected array, received string` — which is
+ * `bug-083-dna-set-cannot-write-array-valued-fields`'s headline symptom and says nothing about how to
+ * write the field.
+ */
+const dnaSetFn = async (params) => {
+    const { root, positionals, options } = params;
+    const keyPath = dnaPathPositional('set', positionals);
+    const value = options?.value;
+    if (value === undefined) {
+        throw new usage_error_1.UsageError('missing required argument: --value');
+    }
+    // `wf(dna): set <key>` — the subject `dna set` has always written (task-025), kept verbatim so a
+    // reader (and `git log --grep`) sees the command that was run, not the verb it delegates to. The
+    // scalar-only restriction, `dl-080`(B)'s dirty-target guard (task-092) and the committed-tree
+    // post-condition all live in the shared pipeline now, on the one document it loads.
+    return runDnaMutation(root, { verb: 'update', field: keyPath, value }, `wf(dna): set ${keyPath}`, true);
+};
+/** Split a verb's invocation into the positional `<path>`, `--value` and the per-entry `--entry-<field>` values. */
+function dnaMutationRequest(verb, positionals, options) {
+    const field = dnaPathPositional(verb, positionals);
+    if (verb === 'add' && options?.value === undefined)
+        throw new usage_error_1.UsageError('missing required argument: --value');
+    // Every remaining option is an entry field, carried under its `--entry-<field>` name (see
+    // `DNA_ENTRY_OPTION_PREFIX`); it is stripped back to the schema's own field name here, which is what
+    // `applyDnaMutation` matches against the entry schema. Sorted so the request — and therefore the
+    // batch of text edits it produces — is a deterministic function of the invocation (REQ-SYS-07).
+    const fields = {};
+    for (const name of Object.keys(options ?? {}).sort()) {
+        if (name === 'value')
+            continue;
+        const entryField = (0, path_2.dnaEntryFieldOfOption)(name);
+        // Strict, and deliberately so: the CLI can only send names this operation declares (Commander
+        // refuses the rest), so accepting a BARE `version` here would mean the core layer speaks a
+        // vocabulary the CLI layer cannot produce — which is how a test at this layer went green while
+        // the real command line silently did nothing. The MCP surface, whose Tool arguments are arbitrary
+        // JSON, is the caller that can actually reach this, and it gets a named refusal.
+        if (entryField === undefined) {
+            throw new usage_error_1.UsageError(`unknown option: --${name} (entry fields are passed as --${path_2.DNA_ENTRY_OPTION_PREFIX}<field>)`);
+        }
+        fields[entryField] = options[name];
+    }
+    return { verb, field, value: options?.value, fields };
+}
+/** `dna add` — create an entry, or append to a list (`dl-081` option (E); spec-006 §3, Tool `dna.add`). */
+const dnaAddFn = async (params) => {
+    const { root, positionals, options } = params;
+    return runDnaMutation(root, dnaMutationRequest('add', positionals, options));
+};
+/** `dna remove` — drop an entry, a value from a list, or an optional field (Tool `dna.remove`). */
+const dnaRemoveFn = async (params) => {
+    const { root, positionals, options } = params;
+    return runDnaMutation(root, dnaMutationRequest('remove', positionals, options));
+};
+/** `dna update` — change a value, a list, or the fields of one entry (Tool `dna.update`). */
+const dnaUpdateFn = async (params) => {
+    const { root, positionals, options } = params;
+    return runDnaMutation(root, dnaMutationRequest('update', positionals, options));
+};
+/**
+ * The `--entry-<field>` namespace, re-exported from the DNA pillar (`src/dna/path.ts`), which owns it
+ * because it owns the derivation: the option set is read off `spec-002`'s entry schemas, and the
+ * refusal messages `src/dna/mutate.ts` writes have to spell those options the same way this module
+ * registers them. Re-exported rather than moved-and-forgotten so `src/core`'s public surface is
+ * unchanged (`spec-006` §1: the pillar is a leaf, and `src/core` is what both adapters import).
+ */
+var path_3 = require("../dna/path");
+Object.defineProperty(exports, "DNA_ENTRY_OPTION_PREFIX", { enumerable: true, get: function () { return path_3.DNA_ENTRY_OPTION_PREFIX; } });
+Object.defineProperty(exports, "dnaEntryOptionName", { enumerable: true, get: function () { return path_3.dnaEntryOptionName; } });
+Object.defineProperty(exports, "dnaEntryFieldOfOption", { enumerable: true, get: function () { return path_3.dnaEntryFieldOfOption; } });
+/**
+ * The options the DNA verbs declare beside their positional `<path>`: `--value` on all four, plus —
+ * for `add`/`update` — one `--entry-<field>` option per field the collection entry schemas declare,
+ * derived from `DnaYaml` rather than hand-listed (`dnaEntryOptionNames`, `src/dna/path.ts`), so a
+ * collection added to `spec-002` becomes writable without editing this file.
+ *
+ * `--value`'s description carries `dl-081`'s one stated convention, because the ratification records
+ * it as a convention rather than something the grammar shows: it is the new entry's IDENTITY when the
+ * path ends at a collection and the new VALUE when it ends at a leaf (task-093 AC6). `dna set` gets
+ * its own, narrower description: it is the scalar verb, so `--value` there has only the second
+ * meaning and advertising the first would describe a case the verb refuses.
+ */
+const DNA_VALUE_OPTION = {
+    name: 'value',
+    description: "the new entry's identity when <path> ends at a collection; the new value when it ends at a leaf (comma-separated for a list of values)",
+};
+const DNA_SET_VALUE_OPTION = {
+    name: 'value',
+    required: true,
+    description: 'the new value for <path> (scalar fields only — use `dna update` for collections and lists)',
+};
+const DNA_ENTRY_OPTIONS = (0, path_2.dnaEntryOptionNames)().map((field) => ({
+    name: (0, path_2.dnaEntryOptionName)(field),
+    description: `'${field}' of the entry <path> names, where that collection declares it`,
+}));
+/**
+ * `memory add` `CoreOperation.fn` (P1.3, `mutates: true` — the first Memory-document mutation and the
+ * pattern for all Memory CRUD; spec-006-core-domain-api §3 memory table). Follows `dna set`'s
+ * mutating-op template (task-025) exactly, over the Memory store instead of `dna.yaml`:
+ *
+ * 1. **`requireGitIdentity` pre-flight** (REQ-SEC-01, task-014) — refuse before any read/write when
+ *    the git identity is unset, returning its `CoreResult.error` unchanged (exit 1).
+ * 2. **Argument validation** — a missing `--type`/`--title` is a usage error: `throw new UsageError`
+ *    → exit **2** with the exact `missing required argument: --<name>` message
+ *    (spec-008-cli-grammar §5, mapped by `exitCodeForThrow`), same classification as `dna set`'s
+ *    missing positional.
+ * 3. **Resolve `--type` against the `memory.yaml` committed at `HEAD`** (spec-001-memory-yaml-schema)
+ *    via {@link resolveAddType} — the type registry, the type's `path` and its `template` scaffold
+ *    all resolve against the repository as committed, never against the working tree (task-095,
+ *    `bug-085`, `dl-080` option (B)). That step takes no parsed `MemoryYaml` and this function holds
+ *    none, so no call path can reach the decision with a working-tree registry. An unknown type is a
+ *    domain `NOT_FOUND` (exit 1) with the exact P1.3 message
+ *    `unknown memory type '<t>' (not defined in memory.yaml)`, returned BEFORE any write.
+ * 4. **Generate the id** deterministically from the type's committed `id_pattern` (task-002's
+ *    `generateId`, REQ-SYS-07): the `{slug}` from the title, and — only for a `{n}`-token pattern — a
+ *    sequence counter over the type's directory (`src/memory/add.ts`; no wall-clock/random). That
+ *    counter still reads the WORKING TREE: it is `bug-087` (`release: v0.3`), a different read in
+ *    this verb and deliberately not task-095's. What changed is only that the directory it counts in
+ *    is now derived from the committed `path` pattern.
+ * 5. **Fill the committed scaffold's bytes** with only the `id`/`status: draft`/`--title`/`--tags`
+ *    skeleton (P1.3; spec-010-memory-frontmatter-schema), then **write + commit** through task-022's
+ *    confined `writeMemoryEntry` (REQ-SEC-06 refuse-before-write + one scoped commit
+ *    `wf(<type>): add <id>`); the returned sha rides `CoreResult.commit`.
+ *
+ * A thrown `StorageError` (e.g. a confinement violation, an unresolved path placeholder for a
+ * workflow-seeded type) or a `ValidationError` (a malformed `id_pattern`) is a logic error mapped to a
+ * `CoreResult.error` (exit 1) so nothing escapes as an uncaught throw — the usage errors above are the
+ * only exit-2 path and are thrown before this try.
+ */
+const memoryAddFn = async (params) => {
+    const { root, options } = params;
+    const identity = (0, git_identity_1.requireGitIdentity)(root);
+    if (!identity.ok)
+        return identity;
+    const type = options?.type;
+    if (type === undefined)
+        throw new usage_error_1.UsageError('missing required argument: --type');
+    const title = options?.title;
+    if (title === undefined)
+        throw new usage_error_1.UsageError('missing required argument: --title');
+    const tags = (0, memory_1.parseTags)(options?.tags);
+    // task-095 / `bug-085`: the registry, the `path` and the scaffold all resolve at HEAD, inside a
+    // function that accepts no parsed `MemoryYaml` — so this verb cannot decide any of the three from
+    // a working-tree copy, in the same way task-091 made that true of the four transition verbs.
+    const resolved = (0, memory_add_type_1.resolveAddType)(root, type);
+    if (!resolved.ok)
+        return resolved;
+    const { pathPattern, idPattern, scaffold } = resolved.value;
+    try {
+        const sequence = (0, memory_1.hasNumericToken)(idPattern)
+            ? (0, memory_1.nextSequenceNumber)((0, memory_1.resolveTypeDirectory)(root, pathPattern), idPattern)
+            : 0;
+        const id = (0, validation_1.generateId)(idPattern, { slug: (0, memory_1.slugifyTitle)(title), n: sequence });
+        const content = (0, memory_1.renderAddDocument)(scaffold, { id, title, tags });
+        const message = `wf(${type}): add ${id}`;
+        // dl-080 (B) / bug-078, AC3: this verb CREATES, so the rule is absence rather than cleanliness.
+        // `nextSequenceNumber` counts the WORKING TREE, so a tree that disagrees with `HEAD` about how
+        // many elements exist can generate an id landing on an occupied path — and the write below is
+        // unconditional, which turns `wf(<type>): add <id>` into a commit that overwrites (or deletes
+        // lines from) an existing element. The path is resolved here rather than taken from
+        // `writeMemoryEntry`'s return value because the guard must run BEFORE the write; the resolution
+        // is pure, so doing it twice is free of side effects and keeps that throwing storage primitive's
+        // contract untouched. A confinement escape still throws `StorageError` from this same call.
+        const targetPath = (0, path_1.relative)(root, (0, memory_path_1.resolveConfinedMemoryPath)(root, pathPattern, { id })).split(path_1.sep).join('/');
+        const absent = (0, write_guard_1.requireAbsentTarget)(root, targetPath);
+        if (!absent.ok)
+            return absent;
+        const { path, sha } = (0, memory_1.writeMemoryEntry)(root, pathPattern, { id }, content, message);
+        const leaked = (0, write_guard_1.committedScopeError)(root, sha, targetPath, content);
+        if (leaked)
+            return leaked;
+        return (0, types_1.coreOk)({ id, path: (0, path_1.relative)(root, path) }, { sha, message });
+    }
+    catch (error) {
+        if (error instanceof storage_1.StorageError) {
+            return (0, types_1.coreErr)({ code: 'IO', message: error.message });
+        }
+        if (error instanceof validation_1.ValidationError) {
+            const reason = error.issues.length > 0 ? error.issues.map((issue) => issue.message).join('; ') : error.message;
+            return (0, types_1.coreErr)({ code: 'VALIDATION', message: reason });
+        }
+        throw error;
+    }
+};
+const NO_MEMORY_SEARCH_MATCHES_MESSAGE = 'no documents matched the query';
+/**
+ * `memory search` `CoreOperation.fn` (P1.5, `mutates: false` — the FIRST Memory-document READ
+ * operation registered in `CORE_MODULES`; spec-006-core-domain-api §3 memory table pins its MCP
+ * exposure to the mechanical zero-argument Resource `wingfoil://memory/search` verbatim, so no gap
+ * exists to fill with a richer Resource template — see this task's Execution Notes). Wraps
+ * task-008/023's `src/memory/query.ts` primitives — no scan/ranking/validation logic is
+ * reimplemented here:
+ *
+ * 1. **Empty-query guard** ({@link validateSearchQuery}, task-023/P1.12) runs ONLY when the caller
+ *    actually supplied a keyword positional (`positional !== undefined`): an explicit empty or
+ *    whitespace-only string (e.g. `wingfoil memory search ""`) throws `ValidationError.semantic`
+ *    (exit 2, message "empty search query" — `exitCodeForThrow` maps its `exitCode: 2` straight
+ *    through, the same throw-path precedent `dnaSetFn`'s `UsageError` set). An OMITTED keyword
+ *    (`wingfoil memory search --tag architecture`, P1.5 BDD Scenario "Filter results by metadata
+ *    tag") is a DIFFERENT, legitimate case — a tag-only browse, per `searchMemoryDocuments`'s own doc
+ *    comment ("browse by tag alone, no keyword" is not an empty query) — so it never reaches the
+ *    guard at all, and resolves to `''` below.
+ * 2. **Load `memory.yaml`** via the same `loadOrError` + `loadMemoryYaml` path every other read op uses.
+ * 3. **Scan + rank** via {@link searchMemoryDocuments} (task-008: deterministic metadata-before-body
+ *    ranking, REQ-SYS-07), narrowed by `--tag` through its own `MemorySearchOptions.tag` — the ONE
+ *    filter the scan primitive itself understands.
+ * 4. **`--type`/`--status` narrow the already-ranked result** — a plain array filter, not a second
+ *    scan pass: both are base frontmatter fields every Memory document carries
+ *    (spec-010-memory-frontmatter-schema), and `searchMemoryDocuments` already projects both onto
+ *    each match (task-021 added `type` alongside the pre-existing `status`), so no extra file read is
+ *    needed.
+ * 5. **Zero matches is `coreOk`, never `coreErr`** (P1.5 BDD "Error - query with no matches" — the
+ *    scenario's own title says "Error" but its assertion is exit `0`, so this is deliberately a
+ *    successful, empty result carrying the exact message, per spec-005-cli-command-contract §1: a
+ *    read-only command can only exit `0`/`1`).
+ *
+ * **REQ-STATE-06 (task-038; archived set widened by `dl-028-archived-states-excluded-from-context`):**
+ * `searchMemoryDocuments` excludes archived documents — `status: deprecated` or `superseded` — by
+ * default (the "default … `memory search` results" half of the Fit Criterion). This function passes
+ * `includeArchived: true` through to the scan ONLY when the caller's own `--status` narrow names an
+ * archived status (`isArchivedStatus`), so that intentional request still resolves; every other query
+ * (no `--status`, or a `--status` naming a live state such as `draft`) stays under the default
+ * exclusion.
+ */
+const memorySearchFn = async (params) => {
+    const { root, positional, options } = params;
+    if (positional !== undefined)
+        (0, memory_1.validateSearchQuery)(positional);
+    const query = positional ?? '';
+    const loaded = loadOrError(() => (0, loaders_1.loadMemoryYaml)(root));
+    if (!loaded.ok)
+        return loaded;
+    const tag = options?.tag;
+    const type = options?.type;
+    const status = options?.status;
+    const scanned = (0, memory_1.searchMemoryDocuments)(root, loaded.value, query, {
+        ...(tag !== undefined ? { tag } : {}),
+        ...((0, memory_1.isArchivedStatus)(status) ? { includeArchived: true } : {}),
+    });
+    const matches = scanned
+        .filter((match) => (type === undefined || match.type === type) && (status === undefined || match.status === status))
+        .map(({ path, id, title, type: docType, status: docStatus, tags }) => ({ path, id, title, type: docType, status: docStatus, tags }));
+    return matches.length === 0
+        ? (0, types_1.coreOk)({ query, matches, message: NO_MEMORY_SEARCH_MATCHES_MESSAGE })
+        : (0, types_1.coreOk)({ query, matches });
+};
+/**
+ * `memory history` `CoreOperation.fn` (P1.10, `mutates: false`; spec-006-core-domain-api §3 memory
+ * table). Composes two existing primitives and reimplements neither — the git walk, the commit-body
+ * parse and the per-commit frontmatter read all belong to `src/memory`:
+ *
+ * 1. **Argument validation** — an absent (or blank) `<id>` is a usage error: `throw new UsageError`
+ *    → exit **2** (spec-008-cli-grammar §4/§5, mapped by `exitCodeForThrow`), the same classification
+ *    `dna set`'s missing positional gets. Blank is folded in with absent deliberately: `memory
+ *    history ""` supplies a positional that names no document, so reporting it as "not found" would
+ *    dress a malformed invocation up as a domain outcome (and print an id-less message).
+ * 2. **Load `memory.yaml`** through the same `loadOrError` + `loadMemoryYaml` path every read op uses
+ *    — it declares the type `path` patterns that bound the id scan (spec-011: no full-repo walk).
+ * 3. **Resolve the id to a document** with task-009's {@link findMemoryDocumentById} — an EXACT
+ *    frontmatter-`id` match over the deterministically-sorted document set, never a substring (that
+ *    is `memory search`'s job). No match is a domain `NOT_FOUND` (exit 1) with the exact P1.10 message
+ *    `document not found: <id>`, returned rather than thrown. Archived documents are deliberately NOT
+ *    excluded: REQ-STATE-06 scopes its exclusion to default *search* results, and explicitly
+ *    guarantees an archived element remains "present on disk and in git history" — which is precisely
+ *    what this command reads.
+ * 4. **Reconstruct + project the trail** with task-015's `reconstructMemoryTransitions` (`git log
+ *    --follow` oldest-first + a `git show` per commit for that commit's frontmatter `status`, plus the
+ *    `Approver:`/`Reason:` body parse). This function only renames those fields into
+ *    {@link MemoryHistoryEntryView}'s user-facing shape; it derives no state, parses no body, and
+ *    reads no clock of its own (REQ-SYS-07 — the whole result is a pure function of the repository).
+ *
+ * A document that exists on disk but has never been committed yields `entries: []` — correctly, not
+ * as an error: per ADR-007 git history IS the audit trail, so an uncommitted document has none yet.
+ */
+const memoryHistoryFn = async (params) => {
+    const { root, positional: id } = params;
+    if (id === undefined || id.trim().length === 0) {
+        throw new usage_error_1.UsageError('missing required argument: memory history <id>');
+    }
+    const loaded = loadOrError(() => (0, loaders_1.loadMemoryYaml)(root));
+    if (!loaded.ok)
+        return loaded;
+    const found = (0, memory_1.findMemoryDocumentById)(root, loaded.value, id);
+    if (!found) {
+        return (0, types_1.coreErr)({ code: 'NOT_FOUND', message: `document not found: ${id}` });
+    }
+    const entries = (0, memory_1.reconstructMemoryTransitions)(root, found.path).map((transition) => ({
+        sha: transition.sha,
+        author: `${transition.authorName} <${transition.authorEmail}>`,
+        timestamp: transition.date,
+        operation: transition.operation,
+        from: transition.fromState,
+        to: transition.toState,
+        approver: transition.approval
+            ? `${transition.approval.approverName} <${transition.approval.approverEmail}> (${transition.approval.approverRole})`
+            : null,
+        reason: transition.reason,
+        subject: transition.subject,
+    }));
+    return (0, types_1.coreOk)({ id, path: found.path, entries });
+};
+/**
+ * `memory submit` `CoreOperation.fn` (P1.6, `mutates: true`; spec-006-core-domain-api §3). Submit is
+ * "the content is written — move it forward": it commits the document as the author left it, with
+ * `status` advanced. Order, every refusal before the single write:
+ *
+ * 1. **`requireGitIdentity`** (REQ-SEC-01) — exit 1.
+ * 2. **`<id>`** absent or blank → `UsageError` (exit 2), as `memory history`.
+ * 3. **{@link prepareMemoryTransition}** — it resolves the `memory.yaml` committed at `HEAD` itself
+ *    (task-091, `dl-080` (B)); no committed machine, an unreadable one, not found, unknown type,
+ *    invalid state, or an illegal transition, each a `CoreResult.error` (exit 1); an illegal one
+ *    carries the pinned `illegal transition <from> -> <to> for type '<type>'` (`dl-032`, P1.6 sc.2).
+ * 5. **Required fields** (spec-010 validation rules) — `title` and every `template.frontmatter.required`
+ *    field must be non-empty, else `VALIDATION` `missing required field on submit: <fields>` (exit 1).
+ * 6. **Edit + commit** — `status` set to the target and `rejection_reason` removed (spec-010 field-write
+ *    ownership; every other byte kept), then one commit scoped to that file, subject
+ *    `wf(<type>): submit <id>` with no bracket and no body (spec-004 §4.3). The rendered document is
+ *    re-parsed first (`commitMemoryTransition`'s post-condition: `status` is the target, no
+ *    `rejection_reason`, nothing else changed); a failure is `VALIDATION` (exit 1) with nothing written. No `--reason`: spec-008 §2
+ *    requires it only on the approval gates (`dl-027`).
+ */
+const memorySubmitFn = async (params) => {
+    const { root, positional: id } = params;
+    const identity = (0, git_identity_1.requireGitIdentity)(root);
+    if (!identity.ok)
+        return identity;
+    if (id === undefined || id.trim().length === 0) {
+        throw new usage_error_1.UsageError('missing required argument: memory submit <id>');
+    }
+    const prepared = (0, memory_transition_1.prepareMemoryTransition)(root, id, 'submit');
+    if (!prepared.ok)
+        return prepared;
+    const { type, path, frontmatter, content, from, to } = prepared.value;
+    const required = prepared.value.memoryYaml.types[type]?.template?.frontmatter.required ?? [];
+    const missing = (0, memory_1.missingRequiredFields)(frontmatter, required);
+    if (missing.length > 0) {
+        return (0, types_1.coreErr)({ code: 'VALIDATION', message: `missing required field on submit: ${missing.join(', ')}` });
+    }
+    const message = (0, memory_1.formatMemoryCommitMessage)({ type, op: 'submit', ids: [id] });
+    const rendered = (0, memory_1.renderSubmitDocument)(content, to);
+    // `carries-content`: submit is the ONE verb entitled to bring the author's body and required fields
+    // into its commit (spec-010's field-write ownership row), so it is not guarded against a modified
+    // working tree and its commit need not differ from HEAD~1 by `status` alone (task-088, bug-076 AC4).
+    const committed = (0, memory_transition_1.commitMemoryTransition)(root, prepared.value, rendered, message, { [memory_1.REJECTION_REASON_FIELD]: undefined }, 'carries-content');
+    if (!committed.ok)
+        return committed;
+    return (0, types_1.coreOk)({ id, path, from, to }, { sha: committed.value, message });
+};
+/**
+ * `memory approve` `CoreOperation.fn` (P1.7, `mutates: true`; spec-006-core-domain-api §3). Approve is
+ * the approval gate: it advances `status` across a `gates` edge and records **who** approved, **when**
+ * and **why** — identity and reason in the commit body, the ISO-8601 timestamp supplied by git itself
+ * (P1.2/P1.10), never written into the message. Order, every refusal before the single write, so
+ * "the state is unchanged" (P1.7 sc.2/sc.3) holds by construction:
+ *
+ * 1. **`requireGitIdentity`** (REQ-SEC-01) — exit 1. It is also the identity the `Approver:` line and
+ *    the commit's own author record, so the two can never name different principals.
+ * 2. **`<id>`** absent or blank → `UsageError` (exit 2), as `memory submit`/`memory history`.
+ * 3. **`requireReason`** (REQ-SEC-04, task-041) → `UsageError` `missing required argument: --reason`
+ *    (exit 2, P1.7 sc.2). Placed before any file is read, so an omitted reason touches nothing.
+ * 4. **{@link prepareMemoryTransition}** — it resolves the `memory.yaml` committed at `HEAD` itself
+ *    (task-091, `dl-080` (B)); no committed machine, an unreadable one, not found, unknown type,
+ *    invalid state, or an illegal transition, each a `CoreResult.error` (exit 1); an illegal one
+ *    carries the pinned `illegal transition <from> -> <to> for type '<type>'` (`dl-032`), whose `<to>`
+ *    is `approve`'s own next legal edge (`dl-053`).
+ * 6. **`requireApprovalAuthority`** (REQ-SEC-03, task-040) — exit 1 with
+ *    `user not authorized to approve type '<type>'` (P1.7 sc.3). It runs after step 5 because its
+ *    message interpolates the document's type, which is only knowable once the document is located,
+ *    and `findMemoryDocumentById` is a full scan of the registered content roots — resolving the type
+ *    twice would double the cost of every approve. Nothing is weakened by the order: the authority
+ *    *decision* depends on nothing step 5 computes (adr-006 fixes one uniform `approver` role, keyed
+ *    on the git identity), and step 5 writes nothing. It reads the roles from the **committed**
+ *    `.wingfoil/dna.yaml` and resolves that file itself (task-090, `bug-079`) — which is why no
+ *    `loadDnaYaml` call precedes it here: an uncommitted grant must not be able to reach this
+ *    decision, and the way to guarantee that is to leave the caller nothing to pass.
+ * 7. **Edit + commit** — `status` set to the target and **nothing else** (spec-010 field-write
+ *    ownership: approve changes only `status`; approver and reason live in the commit message). One
+ *    commit scoped to that file, subject `wf(<type>): approve <id> [<from> → <to>]` with the mandatory
+ *    `Approver:` / `Reason:` body (CLAUDE.md §5.1; `dl-054` confines the bracket to the
+ *    approver-gated verbs, which is why `memory submit` has none). `commitMemoryTransition` re-parses
+ *    the rendered frontmatter first and refuses (exit 1, nothing written) unless `status` is the
+ *    target and no other field's value moved — which is exactly spec-010's "only `status`" rule, so
+ *    no extra `expected` entry is needed here.
+ */
+const memoryApproveFn = async (params) => {
+    const { root, positional: id, options } = params;
+    const identity = (0, git_identity_1.requireGitIdentity)(root);
+    if (!identity.ok)
+        return identity;
+    if (id === undefined || id.trim().length === 0) {
+        throw new usage_error_1.UsageError('missing required argument: memory approve <id>');
+    }
+    const reason = (0, require_reason_1.requireReason)(options);
+    const prepared = (0, memory_transition_1.prepareMemoryTransition)(root, id, 'approve');
+    if (!prepared.ok)
+        return prepared;
+    const { type, path, content, from, to } = prepared.value;
+    const authorized = (0, approval_authority_1.requireApprovalAuthority)(root, type);
+    if (!authorized.ok)
+        return authorized;
+    const { name, email } = (0, git_identity_1.readGitIdentity)(root);
+    const message = (0, memory_1.formatMemoryCommitMessage)({
+        type,
+        op: 'approve',
+        ids: [id],
+        transition: { from, to },
+        approver: { name, email, role: approval_authority_1.APPROVER_ROLE },
+        reason,
+    });
+    const committed = (0, memory_transition_1.commitMemoryTransition)(root, prepared.value, (0, memory_1.setFrontmatterField)(content, 'status', to), message);
+    if (!committed.ok)
+        return committed;
+    return (0, types_1.coreOk)({ id, path, from, to }, { sha: committed.value, message });
+};
+/**
+ * `memory reject` `CoreOperation.fn` (P1.8, `mutates: true`; spec-006-core-domain-api §3) — the FIRST
+ * approver-gated verb, so the first operation that enforces REQ-SEC-03 (role authority) and REQ-SEC-04
+ * (mandatory reason) and the first to emit a commit with a `[from → to]` subject bracket and an
+ * `Approver:`/`Reason:` body (`dl-054-submit-commit-subject-bracket`, CLAUDE.md §5.1). Order, every
+ * refusal before the single write:
+ *
+ * 1. **`requireGitIdentity`** (REQ-SEC-01) — exit `1`.
+ * 2. **`<id>`** absent or blank → `UsageError` (exit `2`), as `memory submit`.
+ * 3. **`requireReason`** (REQ-SEC-04, task-041-mandatory-reason-on-verbs) → `UsageError`
+ *    `missing required argument: --reason` (exit `2`, P1.8 sc.3).
+ * 4. **{@link prepareMemoryTransition}** with op `reject`, against the `memory.yaml` committed at
+ *    `HEAD` (task-091, `dl-080` (B)) — no committed machine, an unreadable one, not found,
+ *    unknown type, invalid state, or an illegal transition (the document is in no `gates`
+ *    state), each a `CoreResult.error` at exit `1` carrying `dl-032`'s pinned contract message. The
+ *    target is the type's `gates.<from>.reject` value, taken verbatim (`spec-001`), so it need not be
+ *    a `sequence` member.
+ * 5. **{@link requireApprovalAuthority}** (REQ-SEC-03) — exit `1` with
+ *    `user not authorized to approve type '<type>'`. It runs AFTER step 4 because that message names
+ *    the element **type**, which is a fact of the document and is known only once the document has
+ *    been located; nothing is written in steps 1-5, so "the state is unchanged" holds either way. The
+ *    roles come from the **committed** `.wingfoil/dna.yaml`, which that function resolves itself
+ *    (task-090, `bug-079`): `reject` is an approval gate and records the same `Approver:` line, so it
+ *    takes the same baseline as `approve`, by construction rather than by remembering to.
+ * 6. **Edit + commit** — `status` set to the reject target and `rejection_reason` to the reason
+ *    verbatim (spec-010 field-write ownership: reject is the one verb that writes two fields), then
+ *    one commit scoped to that file. `commitMemoryTransition`'s post-condition re-parses the rendered
+ *    document and refuses (`VALIDATION`, exit `1`, nothing written) unless `status` AND
+ *    `rejection_reason` hold their expected values and no other field moved.
+ *
+ * The `Approver:` identity is the live git identity at `root` — the same one step 5 checked and the
+ * same one git records as the commit author, so the body line can never disagree with the attribution
+ * (adr-001/adr-006) — under the `APPROVER_ROLE` the authority was exercised as.
+ */
+const memoryRejectFn = async (params) => {
+    const { root, positional: id, options } = params;
+    const identity = (0, git_identity_1.requireGitIdentity)(root);
+    if (!identity.ok)
+        return identity;
+    if (id === undefined || id.trim().length === 0) {
+        throw new usage_error_1.UsageError('missing required argument: memory reject <id>');
+    }
+    const reason = (0, require_reason_1.requireReason)(options);
+    const prepared = (0, memory_transition_1.prepareMemoryTransition)(root, id, 'reject');
+    if (!prepared.ok)
+        return prepared;
+    const { type, path, from, to, content } = prepared.value;
+    const authorized = (0, approval_authority_1.requireApprovalAuthority)(root, type);
+    if (!authorized.ok)
+        return authorized;
+    const { name, email } = (0, git_identity_1.readGitIdentity)(root);
+    const message = (0, memory_1.formatMemoryCommitMessage)({
+        type,
+        op: 'reject',
+        ids: [id],
+        transition: { from, to },
+        approver: { name, email, role: approval_authority_1.APPROVER_ROLE },
+        reason,
+    });
+    const rendered = (0, memory_1.renderRejectDocument)(content, to, reason);
+    const committed = (0, memory_transition_1.commitMemoryTransition)(root, prepared.value, rendered, message, { [memory_1.REJECTION_REASON_FIELD]: reason });
+    if (!committed.ok)
+        return committed;
+    return (0, types_1.coreOk)({ id, path, from, to, reason }, { sha: committed.value, message });
+};
+/**
+ * `memory deprecate` `CoreFn` (P1.9, `mutates: true`; spec-006-core-domain-api §3) — the retire verb.
+ * It rides `spec-001-memory-yaml-schema`'s **implicit wildcard edge**: `deprecated` is "a built-in
+ * wildcard edge from *any* state to a reserved `deprecated` state, always legal", never declared in a
+ * type's `sequence`/`gates`/`waiting`. The target therefore comes from the engine
+ * (`prepareMemoryTransition` → `resolveTypeTransition`, itself resolved from `memory.yaml`), never
+ * from a literal here — so this one function retires a `task` sitting in a `waiting` state, an
+ * `accepted` `adr`, a terminal `decision-log`, and a type that falls back to `defaults.states`, with
+ * no per-type branch. (`adr`/`tech-spec`'s `superseded` is NOT this verb's target: it is a `waiting`
+ * edge fired by a later element's `supersedes:` field — see `SUPERSEDED_STATE` in
+ * `src/memory/state-machine.ts` and this task's Execution Notes, decision D1.)
+ *
+ * Order, every refusal before the single write:
+ *
+ * 1. **`requireGitIdentity`** (REQ-SEC-01) — exit `1`.
+ * 2. **`<id>`** absent or blank → `UsageError` (exit `2`), as `memory submit`/`memory reject`.
+ * 3. **{@link prepareMemoryTransition}** with op `deprecate`, against the `memory.yaml` committed at
+ *    `HEAD` (task-091, `dl-080` (B)) — no committed machine, an unreadable one, not found,
+ *    unknown type, or a `status` that is not a state of the type, each a
+ *    `CoreResult.error` (exit `1`). There is no illegal-transition branch: the wildcard edge is legal
+ *    from every state.
+ * 4. **Already-deprecated guard** (P1.9 sc.3) — `VALIDATION` `document already deprecated: <id>`
+ *    (exit `1`), state unchanged. It lives here rather than in the state machine because the engine
+ *    must keep the edge legal from *any* state; the condition is expressed as "the document is
+ *    already AT the resolved target", so it never hard-codes a state name.
+ * 5. **Edit + commit** — `status` set to the target and **nothing else** (spec-010 field-write
+ *    ownership: this verb is `status`-only, so `rejection_reason` and every other field survive
+ *    untouched — enforced, not assumed, by `commitMemoryTransition`'s re-parse post-condition, which
+ *    refuses the write if any unowned field moved). One commit scoped to that file, subject
+ *    `wf(<type>): deprecate <id> [<from> → deprecated]` (`dl-054` / `spec-004` §4.3: the bracket
+ *    belongs to `approve`/`reject`/`deprecate`), with a `Reason:` body line **only** when `--reason`
+ *    was given.
+ *
+ * Deliberately absent: no `Approver:` line and no `requireApprovalAuthority` call. `deprecate` is not
+ * an approval gate — REQ-SEC-03's Fit Criterion is scoped to an *approve* attempt, and REQ-SEC-04's
+ * own Traceability line (as amended by `dl-027`) says so in as many words: "`memory deprecate` is not
+ * an approval gate (no `Approver:` line, no authority check)". `memory history` (P1.10) already reads
+ * that shape back — it parses `Reason:` independently of `Approver:` for exactly this verb.
+ */
+const memoryDeprecateFn = async (params) => {
+    const { root, positional: id, options } = params;
+    const identity = (0, git_identity_1.requireGitIdentity)(root);
+    if (!identity.ok)
+        return identity;
+    if (id === undefined || id.trim().length === 0) {
+        throw new usage_error_1.UsageError('missing required argument: memory deprecate <id>');
+    }
+    // `--reason` is optional here (`dl-027`), but a reason that IS given must be recordable in the
+    // trailer — blank or trailer-shaped is a usage error at exit 2, before anything is read or written
+    // (`dl-067` clauses 1 and 4; `bug-042` F2/F3, whose amendment makes THIS verb the exploitable one).
+    const reason = (0, require_reason_1.optionalReason)(options);
+    const prepared = (0, memory_transition_1.prepareMemoryTransition)(root, id, 'deprecate');
+    if (!prepared.ok)
+        return prepared;
+    const { type, path, from, to, content } = prepared.value;
+    if (from === to) {
+        return (0, types_1.coreErr)({ code: 'VALIDATION', message: `document already deprecated: ${id}` });
+    }
+    const message = (0, memory_1.formatMemoryCommitMessage)({ type, op: 'deprecate', ids: [id], transition: { from, to }, reason });
+    const rendered = (0, memory_1.setFrontmatterField)(content, 'status', to);
+    const committed = (0, memory_transition_1.commitMemoryTransition)(root, prepared.value, rendered, message);
+    if (!committed.ok)
+        return committed;
+    return (0, types_1.coreOk)({ id, path, from, to, reason }, { sha: committed.value, message });
+};
+/**
+ * `directive create` `CoreOperation.fn` (P3.1, `mutates: true` — the FIRST Directives-pillar mutation
+ * and the pillar's first CLI verb; spec-006-core-domain-api §3 directives table). Follows `dna set`'s
+ * mutating-op template (task-025) exactly, over the Directives pillar instead of `dna.yaml`:
+ *
+ * 1. **`requireGitIdentity` pre-flight** (REQ-SEC-01, task-014) — refuse before any read/write when
+ *    the git identity is unset, returning its `CoreResult.error` unchanged (exit 1).
+ * 2. **Argument validation** — both failures are usage errors (`throw new UsageError` → exit **2**,
+ *    mapped by `exitCodeForThrow`): an absent `--name` uses spec-008-cli-grammar §4's exact
+ *    `missing required argument: --<name>` wording (same as `memoryAdd`), and a non-kebab-case name
+ *    uses P3.1's exact `invalid directive name (use kebab-case)` message
+ *    ({@link INVALID_DIRECTIVE_NAME_MESSAGE}). Because {@link isValidDirectiveName} runs before any
+ *    path is built, a traversal-shaped name (`../x`, `a/b`, `/etc/passwd`) can never reach the write.
+ * 3. **Already-exists check** — a file at `.wingfoil/directives/custom/<name>.md` makes this a domain
+ *    `CONFLICT` (the input is well-formed; the target is taken), returned NOT thrown, with P3.1's exact
+ *    `directive already exists: <name>` message → exit 1 via `exitCodeForError`. Nothing is written, so
+ *    the BDD's "no file is overwritten" holds by construction. The check is scoped to `custom/` only,
+ *    per `X_cli-cmds.md`'s "Unique within custom directives" — `built-in/` holds package-shipped
+ *    templates a user does not author against (spec-011's built-in/custom split).
+ * 4. **Render + persist + commit** — {@link renderCustomDirective} produces the whole document as a
+ *    pure function of `name` (REQ-SYS-07: no clock, no randomness, so two runs are byte-identical),
+ *    satisfying `DirectiveFrontmatter` (spec-013) so the new file loads through `loadDirectives`
+ *    alongside the ten `wingfoil init` scaffolds. Then `writeDocument` + `commitPaths` on the ONE
+ *    scoped path — exactly one commit, `wf(directive): create <name>` — and the sha rides
+ *    `CoreResult.commit`, the same shape `dnaSet` returns for `wf(dna): set <key>`.
+ */
+const directiveCreateFn = async (params) => {
+    const { root, options } = params;
+    const identity = (0, git_identity_1.requireGitIdentity)(root);
+    if (!identity.ok)
+        return identity;
+    const name = options?.name;
+    if (name === undefined)
+        throw new usage_error_1.UsageError('missing required argument: --name');
+    if (!(0, create_1.isValidDirectiveName)(name))
+        throw new usage_error_1.UsageError(create_1.INVALID_DIRECTIVE_NAME_MESSAGE);
+    // One spelling of the location, reused for the existence check, the write and the commit scope, so
+    // the three can never drift apart. `join` normalizes the separators, so the POSIX form is also the
+    // correct absolute path on Windows; the root-relative form is what `commitPaths` stages.
+    const relativePath = `.wingfoil/directives/custom/${name}.md`;
+    const absolutePath = (0, path_1.join)(root, relativePath);
+    if ((0, storage_1.documentExists)(absolutePath)) {
+        return (0, types_1.coreErr)({ code: 'CONFLICT', message: `directive already exists: ${name}` });
+    }
+    // dl-080 (B) / bug-078: the existence check above only sees the WORKING TREE, so a file deleted but
+    // not committed leaves this path "free" while `HEAD` still carries it — and the create then commits
+    // a diff that REMOVES the old content under a subject saying "create". Refuse instead.
+    const unmodified = (0, write_guard_1.requireUnmodifiedTarget)(root, relativePath);
+    if (!unmodified.ok)
+        return unmodified;
+    const content = (0, create_1.renderCustomDirective)(name);
+    (0, storage_1.writeDocument)(absolutePath, content);
+    const message = `wf(directive): create ${name}`;
+    const sha = (0, storage_1.commitPaths)(root, [relativePath], message);
+    const leaked = (0, write_guard_1.committedScopeError)(root, sha, relativePath, content);
+    if (leaked)
+        return leaked;
+    return (0, types_1.coreOk)({ name, path: relativePath }, { sha, message });
+};
+/**
+ * `directive assign` `CoreOperation.fn` (P3.2 **and P3.7**, `mutates: true`; spec-006 §3 row
+ * `directiveAssign`, module `directive` per dl-041). P3.7 (US-4-06, "bind multiple directives to one
+ * role") registers **no operation of its own** — spec-006 §3 has three `directive` rows and none for
+ * it, and `spec-008` §1 / `X_cli-cmds.md` list no fourth directive verb — so it is this operation
+ * with a list-valued `--directive`. Same mutating-op order as {@link directiveCreateFn}:
+ *
+ * 1. `requireGitIdentity` pre-flight (REQ-SEC-01).
+ * 2. `--directive` then `--role` presence — `UsageError`, spec-008 §4 wording, exit 2. A `--directive`
+ *    value that parses to **no ids** (`""`, `"  "`, `","`) counts as absent, the same reading
+ *    `parseTags` takes of an empty `--tags` (`[AUTHORING]`, task-056 D3: before P3.7 such a value
+ *    reached step 3 and failed with an empty id in the message, `unknown directive: `).
+ * 3. `checkAssignable` — which resolves **both** of its baselines from the repository as committed at
+ *    `HEAD` itself, the role catalogue (task-091, `bug-082`) and the directive inventory (task-096,
+ *    `bug-086`), per `dl-080` (B) — returns P3.2's exact
+ *    `unknown role '<role>' (not defined in dna.yaml)` / `unknown directive: <id>` as `NOT_FOUND`
+ *    (exit 1), role first and then each id in argument order. It validates **every** id before
+ *    anything is written, which is P3.7 Sc.3's "no partial assignment is persisted": one unknown id
+ *    leaves `roles.yaml` byte-identical and commits nothing. There is no working-tree pre-load to
+ *    pass it: an untracked directive file used to be bindable, and the committed `roles.yaml` then
+ *    named a directive no clone would have.
+ * 4. `updateRoleAssignments` appends the ids (`withAssignedDirectives`: idempotent, order-preserving,
+ *    never sorting) through the comment-preserving `roles.yaml` writer and makes ONE commit,
+ *    `wf(directive): assign <id1>, <id2> to <role>`, staging only `.wingfoil/roles.yaml`. A request
+ *    whose ids are all already bound is a success with no write and no commit (P3.7 Sc.2 "Binding is
+ *    idempotent"); a partially overlapping one appends only what is missing.
+ */
+const directiveAssignFn = async (params) => {
+    const { root, options } = params;
+    const identity = (0, git_identity_1.requireGitIdentity)(root);
+    if (!identity.ok)
+        return identity;
+    const directive = options?.directive;
+    if (directive === undefined)
+        throw new usage_error_1.UsageError('missing required argument: --directive');
+    const directives = (0, roles_edit_1.parseDirectiveIds)(directive);
+    if (directives.length === 0)
+        throw new usage_error_1.UsageError('missing required argument: --directive');
+    const role = options?.role;
+    if (role === undefined)
+        throw new usage_error_1.UsageError('missing required argument: --role');
+    const invalid = (0, directive_assign_1.checkAssignable)(root, role, directives);
+    if (invalid)
+        return (0, types_1.coreErr)(invalid);
+    const message = `wf(directive): assign ${directives.join(', ')} to ${role}`;
+    const updated = (0, directive_assign_1.updateRoleAssignments)(root, role, (current) => (0, roles_edit_1.withAssignedDirectives)(current, directives), message);
+    if (!updated.ok)
+        return updated;
+    return (0, types_1.coreOk)({ directives, role, assignments: updated.value.assignments }, updated.commit);
+};
+/**
+ * `directive remove` `CoreOperation.fn` (P3.3, `mutates: true`; spec-006 §3 row `directiveRemove`,
+ * module `directive` per dl-041 B). The first operation in the system that DELETES a file, and the
+ * one that completes **REQ-SEC-07**: `task-042-immutable-builtin-assets` shipped clause (a) as the
+ * `requireCustomAsset` primitive, and `dl-030-req-sec-07-referenced-asset-ownership` (`ready`,
+ * option (b)) assigns clause (b)'s directive half here. Both are enforced, in this order, and both
+ * strictly **before** anything on disk changes:
+ *
+ * 1. `requireGitIdentity` pre-flight (REQ-SEC-01).
+ * 2. `<name>` presence — a missing or blank positional is a `UsageError` → exit **2**
+ *    (`missing required argument: directive remove <name>`, the `memory submit <id>` precedent).
+ * 3. **Resolve the name to a real file**, never to a constructed path. `loadDirectives` reads every
+ *    installed directive and {@link selectDirectivesById} picks the winner for that id under
+ *    `dl-037`'s custom-wins precedence (`src/core/context.ts` — the same primitive `directives list`
+ *    and context assembly use, so the rule is implemented once). No match is a domain `NOT_FOUND`
+ *    with P3.2's wording, reused: `unknown directive: <name>`. Because the path comes from a file
+ *    that was just read, a traversal-shaped argument can never reach the filesystem — it simply
+ *    resolves to nothing.
+ *
+ *    This read stays on the **working tree**, deliberately (task-096 AC4). It answers *which file on
+ *    disk am I being asked to delete* — the asset itself, not a gate on it — and step 7's write guard
+ *    (`requireUnmodifiedTarget`, task-092) then decides whether that file may be deleted at all. Resolving it at `HEAD` instead would
+ *    answer an **untracked** directive file with `unknown directive: <id>`, which is false to the
+ *    user's screen, where the file plainly is; the refusal they need is the write guard's, which
+ *    names the file and its `git status` code. Deleting a file that exists in no commit is not this
+ *    verb's act anyway: its contract is to produce one commit that *records* the deletion, and there
+ *    is nothing there to record.
+ * 4. **REQ-SEC-07 clause (a)** — `requireCustomAsset('directive', <that file's path>)`. Passing the
+ *    RESOLVED path rather than the bare name is what makes P3.3's pinned
+ *    `built-in directives cannot be removed` fire instead of the primitive's generic refusal; task-042's
+ *    reviewer recorded that name→path gap as this task's hand-off. Since `task-057` a fresh project
+ *    really does carry six built-ins, so the scenario is exercised against the real scaffold.
+ * 5. **REQ-SEC-06** — {@link requireConfinedTarget}, step 4's filesystem-level companion
+ *    (`task-102`, `bug-044`). `requireCustomAsset` judges the path's *shape* and is right to pass
+ *    `directives/custom/<name>.md`; only `realpath` knows that a symlinked `custom/` puts that file
+ *    outside the project entirely. Before this ran, the verb unlinked the outside file for real and
+ *    then failed on `git add` with a raw `Command failed: git …` — a destroyed file, an unmapped
+ *    error, and nothing recorded. The check is here, ahead of every mutation, because the order
+ *    *is* the property: a refusal issued after the deletion is a report, not a guard.
+ * 6. **REQ-SEC-07 clause (b)** — {@link checkUnreferenced} over the `roles.yaml` committed at `HEAD`:
+ *    a role (or `global`) that still binds the id refuses the removal, naming the referrer. It
+ *    resolves that baseline itself (task-096, `bug-086`, `dl-080` (B)); there is no working-tree
+ *    pre-load to pass it, because an **uncommitted** deletion of the reference used to be enough to
+ *    destroy a file the committed `roles.yaml` still bound. A `roles.yaml` absent from `HEAD` still
+ *    means "no bindings yet" (task-051/053), not a failure. Note the interaction with step 4: a custom
+ *    file SHADOWING a built-in is removable, so removing it changes which file wins resolution — that
+ *    is dl-037's precedence working as specified, and the built-in is left byte-identical.
+ * 7. **Delete + commit** — `removeDocument` then `commitPaths` on the ONE scoped path, producing
+ *    exactly one commit `wf(directive): remove <name>`; the sha rides `CoreResult.commit`, the same
+ *    shape every other mutating op returns. `commitPaths` stages with `git add -- <path>`, which
+ *    records the deletion, and commits with `git commit --only -- <path>` (bug-027), so nothing else
+ *    a caller had staged is swept in.
+ *
+ * `roles.yaml` is never written: P3.3 refuses a still-assigned directive rather than unbinding it, so
+ * this operation has no interaction with the comment-preserving `roles.yaml` writer at all.
+ */
+const directiveRemoveFn = async (params) => {
+    const { root, positional: name } = params;
+    const identity = (0, git_identity_1.requireGitIdentity)(root);
+    if (!identity.ok)
+        return identity;
+    if (name === undefined || name.trim().length === 0) {
+        throw new usage_error_1.UsageError('missing required argument: directive remove <name>');
+    }
+    const directiveFiles = loadOrError(() => (0, loaders_1.loadDirectives)(root));
+    if (!directiveFiles.ok)
+        return directiveFiles;
+    const target = (0, context_1.selectDirectivesById)(directiveFiles.value, new Set([name])).byId.get(name);
+    if (target === undefined) {
+        return (0, types_1.coreErr)({ code: 'NOT_FOUND', message: `unknown directive: ${name}` });
+    }
+    const custom = (0, builtin_asset_1.requireCustomAsset)('directive', target.path);
+    if (!custom.ok)
+        return custom;
+    // `DirectiveFile.path` is built with the PLATFORM separator (`join('directives', …)` in
+    // `./loaders.ts`), so re-spell it with `/` for the value we return and the path we stage — git
+    // speaks POSIX separators, and the payload must not differ by platform (REQ-SYS-07).
+    const relativePath = ['.wingfoil', ...target.path.split(/[\\/]/)].join('/');
+    // REQ-SEC-06 / bug-044: `requireCustomAsset` above judged the SHAPE of that path and passed it,
+    // correctly — every segment is inside the project. Only the filesystem knows that a symlinked
+    // `custom/` puts the file itself outside. This is the companion clause, and it stands here, next
+    // to its string-level sibling and ahead of every mutation, because the bug was order: the shipped
+    // verb unlinked the outside file and reported afterwards.
+    const confined = (0, confinement_1.requireConfinedTarget)(root, relativePath, 'remove');
+    if (!confined.ok)
+        return confined;
+    const referrer = (0, directive_assign_1.checkUnreferenced)(root, name);
+    if (referrer)
+        return (0, types_1.coreErr)(referrer);
+    // dl-080 (B) / bug-078: staging a deletion discards the working-tree blob, so an uncommitted edit
+    // to the directive being removed does not ride into the commit — it is DESTROYED, reaching no
+    // commit anywhere. Different harm, same rule: the target carries modifications this operation does
+    // not own, so refuse and let the author decide what to do with them.
+    const unmodified = (0, write_guard_1.requireUnmodifiedTarget)(root, relativePath);
+    if (!unmodified.ok)
+        return unmodified;
+    (0, storage_1.removeDocument)((0, path_1.join)(root, relativePath));
+    const message = `wf(directive): remove ${name}`;
+    const sha = (0, storage_1.commitPaths)(root, [relativePath], message);
+    const leaked = (0, write_guard_1.committedScopeError)(root, sha, relativePath, null);
+    if (leaked)
+        return leaked;
+    return (0, types_1.coreOk)({ name, path: relativePath }, { sha, message });
+};
+/**
+ * `directives list` `CoreOperation.fn` (P3.4, `mutates: false` — spec-006 §3 directives table). Wraps
+ * `loadDirectiveListing` (`./directives-list.ts`, which carries the annotation rules and the
+ * rationale for not deduplicating shadowed ids) in the same `loadOrError` mapping every read-only
+ * pillar query uses, so a schema-invalid directive file or `roles.yaml` is a `VALIDATION` domain
+ * failure (exit 1), never a throw.
+ *
+ * This replaces the bare `wrapReadOnly(loadDirectives)` registration task-006 wired in: the payload
+ * keeps every field that registration returned (`path`, `frontmatter`, per entry, unchanged) and adds
+ * the role annotation P3.4 requires. Since task-055 (dl-042) the value is `{ entries, warnings }`.
+ */
+const directivesListFn = async (params) => {
+    const { root, options } = params;
+    return loadOrError(() => (0, directives_list_1.loadDirectiveListing)(root, options?.role));
+};
+/**
+ * The production `CoreModule` registry (spec-006 §2, §4). `src/cli`'s command registrar and
+ * `src/mcp`'s Tool/Resource registrar both import this exact array — see spec-006 §4.1: "no
+ * duplicated or hand-copied operation list in either surface module".
+ *
+ * SCOPE (task-006-dual-interface-shared-core, see the task's Execution Notes for the full
+ * rationale): only the core functions that already legitimately exist are wired in here today —
+ * task-004's three read-only per-pillar loaders that have a natural spec-006 §3 counterpart
+ * (`dnaShow`, `directivesList`, `workflowList` — all `mutates: false`), plus
+ * task-028-implement-paths-category's `paths` (P2.5, `wingfoil paths [category]`) — the first FLAT,
+ * no-verb command (`deriveVerb('paths', 'paths') === ''`, spec-008-cli-grammar §1) and the first to
+ * declare a `--list` flag (`CoreOperation.flags`, `./registry.ts`); its `category` rides the same
+ * generic bare-positional seam `dna show`'s `section` does (task-026's `ParamsContext.positional`),
+ * so no per-operation positional metadata is needed here. `loadMemoryYaml`
+ * is deliberately NOT registered as a `memory` module operation: it loads the Memory *pillar's own
+ * config* (`memory.yaml`'s types/state-machines), a different concept from spec-006 §3's `memory`
+ * module (which operates on Memory *documents* — `memoryAdd`, `memorySearch`, ...); registering it
+ * under a `memoryXxx` name would misrepresent it as the latter. As of
+ * task-025-implement-dna-set the registry has its FIRST mutating operation — `dna.dnaSet`
+ * (`mutates: true`, P2.1); `memory.memoryAdd` (P1.3, task-020), `directive.directiveCreate`
+ * (P3.1, task-050), `directive.directiveAssign` (P3.2, task-051) and `memory.memorySubmit` (P1.6,
+ * task-045) have since joined it, and the remaining spec-006 §3 mutating functions
+ * (`memoryApprove`, `directiveRemove`, `workflowStart`, ...) are still later tasks' scope. The
+ * REQ-SYS-05 parity test in `test/core/parity.test.ts` runs against this exact array, so it is now a
+ * live regression guard: each of those mutating ops must appear as both a CLI command and an MCP
+ * Tool, or the diff fails.
+ */
+exports.CORE_MODULES = [
+    {
+        name: 'dna',
+        operations: {
+            // The DNA mutation surface (task-093, `dl-081-dna-mutation-surface-shape` option (E)): three
+            // verbs carrying the collection in their argument rather than in the verb name, so the verb
+            // count stays constant as `spec-002`'s schema grows and spec-006 §3's one-Tool-per-function rule
+            // costs three Tools (`dna.add`, `dna.remove`, `dna.update`) instead of the dozen a
+            // per-collection verb set would need. The path itself is the POSITIONAL `<path>` every command
+            // in this CLI uses for its target (`dl-082-cli-parameter-shape`), registered generically by
+            // `src/cli/program.ts`, which is why no option declares it here.
+            dnaAdd: { name: 'dnaAdd', mutates: true, options: [DNA_VALUE_OPTION, ...DNA_ENTRY_OPTIONS], fn: dnaAddFn },
+            // `remove` declares no entry-field options: it takes what to drop, never what to write.
+            dnaRemove: { name: 'dnaRemove', mutates: true, options: [DNA_VALUE_OPTION], fn: dnaRemoveFn },
+            // The FIRST `mutates: true` operation in production (spec-006 §3 dna table) — by construction an
+            // MCP Tool (`dna.set`) + CLI command (`wingfoil dna set`), and the op the REQ-SYS-05 parity test
+            // now actually guards (task-025-implement-dna-set). Its second positional became `--value` in
+            // task-093 (`dl-082`) — a breaking change to a shipped command, made before `minor-v0.2` ships.
+            dnaSet: { name: 'dnaSet', mutates: true, options: [DNA_SET_VALUE_OPTION], fn: dnaSetFn },
+            dnaShow: { name: 'dnaShow', mutates: false, fn: dnaShowFn },
+            dnaUpdate: { name: 'dnaUpdate', mutates: true, options: [DNA_VALUE_OPTION, ...DNA_ENTRY_OPTIONS], fn: dnaUpdateFn },
+        },
+    },
+    {
+        name: 'memory',
+        operations: {
+            // The FIRST Memory-document mutation (P1.3, spec-006 §3 memory table) — `mutates: true`, so by
+            // construction an MCP Tool (`memory.add`) + CLI command (`wingfoil memory add`), and the second
+            // op the REQ-SYS-05 parity test now guards (alongside `dna.set`). It declares the value-bearing
+            // `--type`/`--title`/`--tags` options (task-020's `CoreOperation.options` seam, reused by
+            // task-021). `loadMemoryYaml` (the Memory *pillar config* loader) is deliberately NOT registered
+            // here — it is a different concept from this `memory` module, which operates on Memory *documents*.
+            memoryAdd: {
+                name: 'memoryAdd',
+                mutates: true,
+                options: [
+                    { name: 'type', required: true },
+                    { name: 'title', required: true },
+                    { name: 'tags' },
+                ],
+                fn: memoryAddFn,
+            },
+            // P1.10 (task-049-memory-history) — `mutates: false`, so by construction an MCP Resource +
+            // CLI command (`wingfoil memory history <id>`). It declares no flags and no value options: the
+            // document id rides the generic bare `positional` seam (task-026), per spec-008-cli-grammar §7's
+            // bare-`<id>` rule for a command whose noun already scopes the type.
+            memoryHistory: { name: 'memoryHistory', mutates: false, fn: memoryHistoryFn },
+            // The FIRST Memory-document READ operation (P1.5, spec-006 §3 memory table) — `mutates: false`,
+            // so by construction an MCP Resource (`wingfoil://memory/search`, the mechanical zero-argument
+            // form spec-006 §3 pins verbatim) + CLI command (`wingfoil memory search`). Its keyword rides the
+            // generic bare `positional` seam (task-026); `--tag`/`--status`/`--type` are OPTIONAL value
+            // options (task-020's seam) — none is `required`, since the AC/BDD only mandate the bare keyword
+            // form and the `--tag` filter (task-021-implement-memory-search's Execution Notes).
+            memorySearch: {
+                name: 'memorySearch',
+                mutates: false,
+                options: [{ name: 'tag' }, { name: 'status' }, { name: 'type' }],
+                fn: memorySearchFn,
+            },
+            // P1.6 (task-045-memory-submit) — `mutates: true`: CLI `wingfoil memory submit <id>` + MCP Tool
+            // `memory.submit`. The id rides the bare `positional` seam (spec-008 §7); no flags, no options.
+            memorySubmit: { name: 'memorySubmit', mutates: true, fn: memorySubmitFn },
+            // P1.7 (task-046-memory-approve) — `mutates: true`: CLI `wingfoil memory approve <id> --reason
+            // <text>` + MCP Tool `memory.approve`. The id rides the bare `positional` seam (spec-008 §7);
+            // `--reason` is the one declared value option, `required` per spec-008 §2 / REQ-SEC-04 (the
+            // declaration is metadata — `memoryApproveFn` does the enforcing, via `requireReason`).
+            memoryApprove: {
+                name: 'memoryApprove',
+                mutates: true,
+                options: [{ name: 'reason', required: true }],
+                fn: memoryApproveFn,
+            },
+            // P1.8 (task-047-memory-reject) — `mutates: true`: CLI `wingfoil memory reject <id> --reason
+            // <text>` + MCP Tool `memory.reject`. The FIRST approver-gated operation (REQ-SEC-03) and the
+            // first with a `required` value option: `required` is declarative metadata only (Commander
+            // registers every declared option the same way), so `memoryRejectFn` enforces it via
+            // `requireReason` (REQ-SEC-04, task-041). The id rides the bare `positional` seam (spec-008 §7).
+            memoryReject: {
+                name: 'memoryReject',
+                mutates: true,
+                options: [{ name: 'reason', required: true }],
+                fn: memoryRejectFn,
+            },
+            // P1.9 (task-048-memory-deprecate) — `mutates: true`: CLI `wingfoil memory deprecate <id>
+            // [--reason <text>]` + MCP Tool `memory.deprecate`. `--reason` is declared WITHOUT `required`,
+            // unlike `memoryReject`'s: `spec-008` §2 and `dl-027-req-sec-04-deprecate-reason-scope`
+            // (option (a), already applied to REQ-SEC-04) make it optional on this verb, which is not an
+            // approval gate. The id rides the bare `positional` seam (spec-008 §7).
+            memoryDeprecate: {
+                name: 'memoryDeprecate',
+                mutates: true,
+                options: [{ name: 'reason' }],
+                fn: memoryDeprecateFn,
+            },
+        },
+    },
+    {
+        name: 'directives',
+        operations: {
+            directivesList: {
+                name: 'directivesList',
+                mutates: false,
+                options: [{ name: 'role' }],
+                fn: directivesListFn,
+            },
+        },
+    },
+    {
+        name: 'paths',
+        operations: {
+            // Self-named (operation name === module name) — the flat/no-verb `wingfoil paths [category]`
+            // form (see `deriveVerb`, `./registry.ts`), not `wingfoil paths paths`. `category` rides the
+            // generic bare positional (task-026's seam); only `--list` is declared here.
+            paths: { name: 'paths', mutates: false, flags: ['list'], fn: pathsFn },
+        },
+    },
+    {
+        name: 'workflow',
+        operations: {
+            workflowList: {
+                name: 'workflowList',
+                mutates: false,
+                fn: wrapReadOnly(loaders_1.loadWorkflowsYaml),
+            },
+        },
+    },
+    // task-050-directive-create (P3.1). A `directive` (SINGULAR) module, DISTINCT from the `directives`
+    // module above, because `CoreModule.name` IS the wire-visible `wingfoil <noun>` segment
+    // (`buildCliCommands`, `src/cli/registrar.ts`) and the `{module}.{verb}` MCP Tool name
+    // (`deriveMcpToolName`, `src/mcp/registrar.ts`) — and the P3 pillar deliberately exposes TWO nouns:
+    // `wingfoil directive create|assign|remove` (BDD P3.1/P3.2/P3.3; spec-008-cli-grammar §1 lists the
+    // noun as singular `directive`) alongside `wingfoil directives list` (BDD P3.4). spec-006 §3's own
+    // directives table pins both spellings on adjacent rows (`wingfoil directive create` + Tool
+    // `directive.create`; `wingfoil directives list` + Resource `wingfoil://directives/list`). Filing
+    // `directiveCreate` under the plural module would instead derive `wingfoil directives
+    // directive-create` (`deriveVerb` kebab-cases the whole name when it does not start with the module
+    // name), contradicting all of the above — so a second module is what realizes the approved contract
+    // without touching `deriveVerb` or either registrar. Placed last purely to keep this task's diff off
+    // the concurrently-edited `directives` block; `enumerateOperations` sorts, so position is inert.
+    {
+        name: 'directive',
+        operations: {
+            // The FIRST Directives-pillar mutation (P3.1) — `mutates: true`, so by construction an MCP Tool
+            // (`directive.create`) + CLI command (`wingfoil directive create`), and the third op the
+            // REQ-SYS-05 parity test guards (alongside `dna.set` and `memory.add`). `--name` is declared
+            // `required` as metadata; `directiveCreateFn` itself enforces it (throwing a `UsageError` →
+            // exit 2), matching `memoryAdd`'s `--type`/`--title` precedent.
+            directiveCreate: {
+                name: 'directiveCreate',
+                mutates: true,
+                options: [{ name: 'name', required: true }],
+                fn: directiveCreateFn,
+            },
+            // P3.2 (task-051-directive-assign) — on this SINGULAR module per dl-041 B, so `deriveVerb` yields
+            // `assign`: CLI `wingfoil directive assign`, Tool `directive.assign`.
+            directiveAssign: {
+                name: 'directiveAssign',
+                mutates: true,
+                options: [
+                    { name: 'directive', required: true },
+                    { name: 'role', required: true },
+                ],
+                fn: directiveAssignFn,
+            },
+            // P3.3 (task-052-directive-remove) — on this SINGULAR module per dl-041 B, so `deriveVerb`
+            // yields `remove`: CLI `wingfoil directive remove <name>`, Tool `directive.remove`. It declares
+            // no flags and no value options: the name rides the bare `positional` seam (spec-008 §7), like
+            // `memory submit <id>`. Completes REQ-SEC-07 for the directive surface (clause (a) via
+            // task-042's `requireCustomAsset`, clause (b) via `checkUnreferenced` — dl-030).
+            directiveRemove: { name: 'directiveRemove', mutates: true, fn: directiveRemoveFn },
+        },
+    },
+];
+//# sourceMappingURL=index.js.map