wingfoil 0.2.1 → 0.2.2

package/dist/core/index.js

@@ -211,13 +211,15 @@ const dnaShowFn = async (params) => {
  * 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
+ * 1. **Argument validation** — done by the callers before this body runs (`dnaPathPositional`,
+ *    `dnaMutationRequest`, `dnaSetFn`'s `--value` check): 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, whatever the git
+ *    identity (task-125, `bug-172`). A path that is well-formed but names nothing the schema declares
+ *    is a different failure and exits **1** — see step 5.
+ * 2. **`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
@@ -445,23 +447,30 @@ const DNA_VALUE_OPTION = {
 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)',
+    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`,
 }));
+/** A single-valued option of {@link MemoryAddParams.options}: a repeated occurrence keeps the last. */
+function singleOption(options, name) {
+    const value = options?.[name];
+    return typeof value === 'string' || value === undefined ? value : value[value.length - 1];
+}
 /**
  * `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`
+ * 1. **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.
+ *    missing positional. So is every spelling fault of `--set` (`spec-008` §10: no `=`, a name that
+ *    is not a field name, a reserved name, a blank value, a name given twice — task-110). It runs
+ *    first, so a malformed invocation exits 2 whatever the git identity (task-125, `bug-172`).
+ * 2. **`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).
  * 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,
@@ -470,13 +479,17 @@ const DNA_ENTRY_OPTIONS = (0, path_2.dnaEntryOptionNames)().map((field) => ({
  *    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
+ *    `generateId`, REQ-SYS-07), in `spec-001`'s fixed order (task-110, `dl-107` S2): first every
+ *    frontmatter/context token from `--set` (a `--set` name the committed `id_pattern` and `path` do
+ *    not contain is refused, exit 1; a token with no value names the option that supplies it), then
+ *    the `{slug}` from the title, and — only for a `{n}`-token pattern — a sequence counter over the
+ *    type's directory, matched against the already-materialized pattern (`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
+ *    skeleton (P1.3; spec-010-memory-frontmatter-schema) plus the `--set` fields (a context token only
+ *    where the scaffold declares it), 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`.
  *
@@ -487,16 +500,19 @@ const DNA_ENTRY_OPTIONS = (0, path_2.dnaEntryOptionNames)().map((field) => ({
  */
 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;
+    const type = singleOption(options, 'type');
     if (type === undefined)
         throw new usage_error_1.UsageError('missing required argument: --type');
-    const title = options?.title;
+    const title = singleOption(options, 'title');
     if (title === undefined)
         throw new usage_error_1.UsageError('missing required argument: --title');
-    const tags = (0, memory_1.parseTags)(options?.tags);
+    const tags = (0, memory_1.parseTags)(singleOption(options, 'tags'));
+    const set = (0, memory_1.parseSetOptions)(options?.set);
+    if (!set.ok)
+        throw new usage_error_1.UsageError(set.message);
+    const identity = (0, git_identity_1.requireGitIdentity)(root);
+    if (!identity.ok)
+        return identity;
     // 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.
@@ -504,12 +520,24 @@ const memoryAddFn = async (params) => {
     if (!resolved.ok)
         return resolved;
     const { pathPattern, idPattern, scaffold } = resolved.value;
+    const unknown = (0, memory_1.unknownSetNames)(set.values, idPattern, pathPattern);
+    if (unknown.length > 0) {
+        return (0, types_1.coreErr)({
+            code: 'VALIDATION',
+            message: unknown
+                .map((name) => `--set ${name}: memory type '${type}' has no token {${name}} in its id_pattern or path`)
+                .join('; '),
+        });
+    }
     try {
-        const sequence = (0, memory_1.hasNumericToken)(idPattern)
-            ? (0, memory_1.nextSequenceNumber)((0, memory_1.resolveTypeDirectory)(root, pathPattern), idPattern)
+        // spec-001's order: field/context tokens → {slug} → {n}, so the counter sees the materialized prefix.
+        const materialized = (0, memory_1.expandFieldTokens)(idPattern, set.values);
+        const sequence = (0, memory_1.hasNumericToken)(materialized)
+            ? (0, memory_1.nextSequenceNumber)((0, memory_1.resolveTypeDirectory)(root, pathPattern, set.values), materialized)
             : 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 id = (0, validation_1.generateId)(materialized, { slug: (0, memory_1.slugifyTitle)(title), n: sequence });
+        const content = (0, memory_1.renderAddDocument)(scaffold, { id, title, tags, fields: (0, memory_1.writtenFields)(scaffold, set.values) });
+        const pathValues = { ...set.values, id };
         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
@@ -519,11 +547,11 @@ const memoryAddFn = async (params) => {
         // `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 targetPath = (0, path_1.relative)(root, (0, memory_path_1.resolveConfinedMemoryPath)(root, pathPattern, pathValues)).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 { path, sha } = (0, memory_1.writeMemoryEntry)(root, pathPattern, pathValues, content, message);
         const leaked = (0, write_guard_1.committedScopeError)(root, sha, targetPath, content);
         if (leaked)
             return leaked;
@@ -662,8 +690,9 @@ const memoryHistoryFn = async (params) => {
  * "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`.
+ * 1. **`<id>`** absent or blank → `UsageError` (exit 2), as `memory history` — before the identity
+ *    check, so the exit code does not depend on the machine (task-125, `bug-172`).
+ * 2. **`requireGitIdentity`** (REQ-SEC-01) — exit 1.
  * 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
@@ -679,12 +708,12 @@ const memoryHistoryFn = async (params) => {
  */
 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 identity = (0, git_identity_1.requireGitIdentity)(root);
+    if (!identity.ok)
+        return identity;
     const prepared = (0, memory_transition_1.prepareMemoryTransition)(root, id, 'submit');
     if (!prepared.ok)
         return prepared;
@@ -711,11 +740,12 @@ const memorySubmitFn = async (params) => {
  * (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
+ * 1. **`<id>`** absent or blank → `UsageError` (exit 2), as `memory submit`/`memory history`.
+ * 2. **`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. Both
+ *    usage checks precede the identity check (task-125, `bug-172`).
+ * 3. **`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
@@ -742,13 +772,13 @@ const memorySubmitFn = async (params) => {
  */
 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 identity = (0, git_identity_1.requireGitIdentity)(root);
+    if (!identity.ok)
+        return identity;
     const prepared = (0, memory_transition_1.prepareMemoryTransition)(root, id, 'approve');
     if (!prepared.ok)
         return prepared;
@@ -777,10 +807,11 @@ const memoryApproveFn = async (params) => {
  * `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).
+ * 1. **`<id>`** absent or blank → `UsageError` (exit `2`), as `memory submit`.
+ * 2. **`requireReason`** (REQ-SEC-04, task-041-mandatory-reason-on-verbs) → `UsageError`
+ *    `missing required argument: --reason` (exit `2`, P1.8 sc.3). Both usage checks precede the
+ *    identity check (task-125, `bug-172`).
+ * 3. **`requireGitIdentity`** (REQ-SEC-01) — exit `1`.
  * 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`
@@ -806,13 +837,13 @@ const memoryApproveFn = async (params) => {
  */
 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 identity = (0, git_identity_1.requireGitIdentity)(root);
+    if (!identity.ok)
+        return identity;
     const prepared = (0, memory_transition_1.prepareMemoryTransition)(root, id, 'reject');
     if (!prepared.ok)
         return prepared;
@@ -849,8 +880,10 @@ const memoryRejectFn = async (params) => {
  *
  * 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`.
+ * 1. **`<id>`** absent or blank → `UsageError` (exit `2`), as `memory submit`/`memory reject`; so is a
+ *    `--reason` that is given but blank or trailer-shaped (`optionalReason`). Both precede the
+ *    identity check (task-125, `bug-172`).
+ * 2. **`requireGitIdentity`** (REQ-SEC-01) — exit `1`.
  * 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
@@ -876,9 +909,6 @@ const memoryRejectFn = async (params) => {
  */
 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>');
     }
@@ -886,6 +916,9 @@ const memoryDeprecateFn = async (params) => {
     // 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 identity = (0, git_identity_1.requireGitIdentity)(root);
+    if (!identity.ok)
+        return identity;
     const prepared = (0, memory_transition_1.prepareMemoryTransition)(root, id, 'deprecate');
     if (!prepared.ok)
         return prepared;
@@ -905,14 +938,16 @@ const memoryDeprecateFn = async (params) => {
  * 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**,
+ * 1. **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.
+ *    It runs before the identity check, so the exit code does not depend on the machine (task-125,
+ *    `bug-172`).
+ * 2. **`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).
  * 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
@@ -928,14 +963,14 @@ const memoryDeprecateFn = async (params) => {
  */
 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);
+    const identity = (0, git_identity_1.requireGitIdentity)(root);
+    if (!identity.ok)
+        return identity;
     // 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.
@@ -966,11 +1001,11 @@ const directiveCreateFn = async (params) => {
  * 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`
+ * 1. `--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: `).
+ * 2. `requireGitIdentity` pre-flight (REQ-SEC-01), after the usage checks (task-125, `bug-172`).
  * 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
@@ -988,9 +1023,6 @@ const directiveCreateFn = async (params) => {
  */
 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');
@@ -1000,6 +1032,9 @@ const directiveAssignFn = async (params) => {
     const role = options?.role;
     if (role === undefined)
         throw new usage_error_1.UsageError('missing required argument: --role');
+    const identity = (0, git_identity_1.requireGitIdentity)(root);
+    if (!identity.ok)
+        return identity;
     const invalid = (0, directive_assign_1.checkAssignable)(root, role, directives);
     if (invalid)
         return (0, types_1.coreErr)(invalid);
@@ -1017,9 +1052,9 @@ const directiveAssignFn = async (params) => {
  * 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**
+ * 1. `<name>` presence — a missing or blank positional is a `UsageError` → exit **2**
  *    (`missing required argument: directive remove <name>`, the `memory submit <id>` precedent).
+ * 2. `requireGitIdentity` pre-flight (REQ-SEC-01), after the usage check (task-125, `bug-172`).
  * 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`
@@ -1067,12 +1102,12 @@ const directiveAssignFn = async (params) => {
  */
 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 identity = (0, git_identity_1.requireGitIdentity)(root);
+    if (!identity.ok)
+        return identity;
     const directiveFiles = loadOrError(() => (0, loaders_1.loadDirectives)(root));
     if (!directiveFiles.ok)
         return directiveFiles;
@@ -1158,28 +1193,69 @@ const directivesListFn = async (params) => {
 exports.CORE_MODULES = [
     {
         name: 'dna',
+        description: "read and change dna.yaml, the project's structural map",
         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 },
+            // in this CLI uses for its target (`dl-082-cli-parameter-shape`): each verb declares it as its
+            // `positional` (task-120, what `--help` names), which is why no option declares it here.
+            dnaAdd: {
+                name: 'dnaAdd',
+                mutates: true,
+                description: 'add an entry to a collection, or values to a list',
+                positional: { name: 'path', required: true, description: 'the collection (e.g. team.members) or list (e.g. paths.sources) to add to' },
+                options: [DNA_VALUE_OPTION, ...DNA_ENTRY_OPTIONS],
+                example: 'wingfoil dna add team.members --value "Ada Lovelace" --entry-email ada@example.com --entry-roles approver',
+                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 },
+            dnaRemove: {
+                name: 'dnaRemove',
+                mutates: true,
+                description: 'remove a collection entry, or values from a list',
+                positional: { name: 'path', required: true, description: 'the entry to remove (<collection>.<name>), or the list to remove the --value values from' },
+                options: [DNA_VALUE_OPTION],
+                example: 'wingfoil dna remove paths.docs --value README.md',
+                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 },
+            dnaSet: {
+                name: 'dnaSet',
+                mutates: true,
+                description: 'set one scalar field',
+                positional: { name: 'path', required: true, description: 'the dotted path of the scalar field, e.g. project.name (double-quote a segment that contains a dot)' },
+                options: [DNA_SET_VALUE_OPTION],
+                example: 'wingfoil dna set project.name --value "My Project"',
+                fn: dnaSetFn,
+            },
+            dnaShow: {
+                name: 'dnaShow',
+                mutates: false,
+                description: 'print dna.yaml, or one top-level section of it',
+                positional: { name: 'section', description: 'a top-level key: project, modules, stacks, team or paths (omit it for the whole file)' },
+                example: 'wingfoil dna show project',
+                fn: dnaShowFn,
+            },
+            dnaUpdate: {
+                name: 'dnaUpdate',
+                mutates: true,
+                description: 'change fields of an existing collection entry',
+                positional: { name: 'path', required: true, description: 'the entry (<collection>.<name>), or one of its fields (<collection>.<name>.<field>) with --value' },
+                options: [DNA_VALUE_OPTION, ...DNA_ENTRY_OPTIONS],
+                example: 'wingfoil dna update modules.api --entry-description "Public HTTP API"',
+                fn: dnaUpdateFn,
+            },
         },
     },
     {
         name: 'memory',
+        description: 'create Memory documents, move them through their state machine, and read them back',
         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
@@ -1190,18 +1266,36 @@ exports.CORE_MODULES = [
             memoryAdd: {
                 name: 'memoryAdd',
                 mutates: true,
+                description: "create a document in its type's initial state (draft) from the type's template",
                 options: [
-                    { name: 'type', required: true },
-                    { name: 'title', required: true },
-                    { name: 'tags' },
+                    { name: 'type', required: true, valueName: 'type', description: 'the Memory type, as the committed memory.yaml declares it' },
+                    { name: 'title', required: true, valueName: 'title', description: 'the document title; also the source of the {slug} token' },
+                    { name: 'tags', valueName: 't1,t2', description: 'comma-separated tags, written as the tags list' },
+                    // task-110, `spec-008-cli-grammar` §10 (`dl-107` S2): the value of an id_pattern/path token,
+                    // written into the frontmatter field of that name. One declared option — not one derived
+                    // option per field, whose first member, `--version`, is a global action flag.
+                    {
+                        name: 'set',
+                        repeatable: true,
+                        valueName: 'name=value',
+                        description: 'fill the id_pattern/path token {name} and write the frontmatter field of that name (repeatable)',
+                    },
                 ],
+                example: 'wingfoil memory add --type task --title "My first task" --tags demo,quickstart',
                 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 },
+            memoryHistory: {
+                name: 'memoryHistory',
+                mutates: false,
+                description: "print a document's audit trail, reconstructed from git",
+                positional: { name: 'id', required: true, description: 'the document id, e.g. task-001-my-first-task' },
+                example: 'wingfoil memory history task-001-my-first-task',
+                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
@@ -1211,12 +1305,26 @@ exports.CORE_MODULES = [
             memorySearch: {
                 name: 'memorySearch',
                 mutates: false,
-                options: [{ name: 'tag' }, { name: 'status' }, { name: 'type' }],
+                description: 'find documents by keyword and/or metadata',
+                positional: { name: 'keyword', description: 'a case-insensitive substring matched against title, id, tags and body (omit it to filter by metadata alone)' },
+                options: [
+                    { name: 'tag', valueName: 'tag', description: 'keep documents carrying this tag' },
+                    { name: 'status', valueName: 'status', description: 'keep documents in this state' },
+                    { name: 'type', valueName: 'type', description: 'keep documents of this Memory type' },
+                ],
+                example: 'wingfoil memory search --status approved --type task',
                 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 },
+            memorySubmit: {
+                name: 'memorySubmit',
+                mutates: true,
+                description: "move a document one step forward along its type's sequence — for the default machine, draft → pending",
+                positional: { name: 'id', required: true, description: 'the document id, e.g. task-001-my-first-task' },
+                example: 'wingfoil memory submit task-001-my-first-task',
+                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
@@ -1224,7 +1332,10 @@ exports.CORE_MODULES = [
             memoryApprove: {
                 name: 'memoryApprove',
                 mutates: true,
-                options: [{ name: 'reason', required: true }],
+                description: 'pass a gate: move a document forward from a gated state (default machine: pending → approved)',
+                positional: { name: 'id', required: true, description: 'the document id, e.g. task-001-my-first-task' },
+                options: [{ name: 'reason', required: true, valueName: 'text', description: "why you approve it, recorded as the commit's Reason:; needs the approver role" }],
+                example: 'wingfoil memory approve task-001-my-first-task --reason "Scope and acceptance criteria are clear."',
                 fn: memoryApproveFn,
             },
             // P1.8 (task-047-memory-reject) — `mutates: true`: CLI `wingfoil memory reject <id> --reason
@@ -1235,7 +1346,10 @@ exports.CORE_MODULES = [
             memoryReject: {
                 name: 'memoryReject',
                 mutates: true,
-                options: [{ name: 'reason', required: true }],
+                description: "send a gated document back to its gate's reject target (default machine: pending → draft)",
+                positional: { name: 'id', required: true, description: 'the document id, e.g. task-001-my-first-task' },
+                options: [{ name: 'reason', required: true, valueName: 'text', description: "what must change before resubmitting, recorded as the commit's Reason: and as rejection_reason; needs the approver role" }],
+                example: 'wingfoil memory reject task-001-my-first-task --reason "Add acceptance criteria before resubmitting."',
                 fn: memoryRejectFn,
             },
             // P1.9 (task-048-memory-deprecate) — `mutates: true`: CLI `wingfoil memory deprecate <id>
@@ -1246,18 +1360,24 @@ exports.CORE_MODULES = [
             memoryDeprecate: {
                 name: 'memoryDeprecate',
                 mutates: true,
-                options: [{ name: 'reason' }],
+                description: 'retire a document, from any state, to deprecated',
+                positional: { name: 'id', required: true, description: 'the document id, e.g. task-001-my-first-task' },
+                options: [{ name: 'reason', valueName: 'text', description: "why the document is retired, recorded as the commit's Reason: (not blank when given)" }],
+                example: 'wingfoil memory deprecate dl-001-use-postgresql --reason "Superseded by the hosted-DB decision."',
                 fn: memoryDeprecateFn,
             },
         },
     },
     {
         name: 'directives',
+        description: 'list the directives and the roles they apply to',
         operations: {
             directivesList: {
                 name: 'directivesList',
                 mutates: false,
-                options: [{ name: 'role' }],
+                description: 'list directives with the roles each is assigned to',
+                options: [{ name: 'role', valueName: 'role', description: 'keep only the directives that apply to this role, globals included' }],
+                example: 'wingfoil directives list --role developer',
                 fn: directivesListFn,
             },
         },
@@ -1267,16 +1387,27 @@ exports.CORE_MODULES = [
         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 },
+            // generic bare positional (task-026's seam), declared as `positional` so `--help` names it.
+            paths: {
+                name: 'paths',
+                mutates: false,
+                description: 'print the resource paths declared in dna.yaml paths:',
+                positional: { name: 'category', description: 'sources, tests, docs, config or governance (omit it for the whole map)' },
+                flags: [{ name: 'list', description: 'accepted for the planned drill-down view; it does not change the output yet' }],
+                example: 'wingfoil paths sources',
+                fn: pathsFn,
+            },
         },
     },
     {
         name: 'workflow',
+        description: 'read the workflows the project declares (there is no workflow engine yet)',
         operations: {
             workflowList: {
                 name: 'workflowList',
                 mutates: false,
+                description: 'print the workflow manifest (workflows.yaml) and every workflow it includes, with their phases',
+                example: 'wingfoil workflow list',
                 fn: wrapReadOnly(loaders_1.loadWorkflowsYaml),
             },
         },
@@ -1296,6 +1427,7 @@ exports.CORE_MODULES = [
     // the concurrently-edited `directives` block; `enumerateOperations` sorts, so position is inert.
     {
         name: 'directive',
+        description: 'create, assign and remove custom directives',
         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
@@ -1305,7 +1437,9 @@ exports.CORE_MODULES = [
             directiveCreate: {
                 name: 'directiveCreate',
                 mutates: true,
-                options: [{ name: 'name', required: true }],
+                description: 'create a custom directive from a scaffold',
+                options: [{ name: 'name', required: true, valueName: 'name', description: 'the new directive, written to .wingfoil/directives/custom/<name>.md' }],
+                example: 'wingfoil directive create --name api-style',
                 fn: directiveCreateFn,
             },
             // P3.2 (task-051-directive-assign) — on this SINGULAR module per dl-041 B, so `deriveVerb` yields
@@ -1313,10 +1447,12 @@ exports.CORE_MODULES = [
             directiveAssign: {
                 name: 'directiveAssign',
                 mutates: true,
+                description: 'assign one or more directives to a role in roles.yaml',
                 options: [
-                    { name: 'directive', required: true },
-                    { name: 'role', required: true },
+                    { name: 'directive', required: true, valueName: 'name[,name...]', description: 'the directive(s) to assign, comma-separated' },
+                    { name: 'role', required: true, valueName: 'role', description: 'the role to assign them to, as the committed dna.yaml declares it' },
                 ],
+                example: 'wingfoil directive assign --directive api-style --role developer',
                 fn: directiveAssignFn,
             },
             // P3.3 (task-052-directive-remove) — on this SINGULAR module per dl-041 B, so `deriveVerb`
@@ -1324,7 +1460,14 @@ exports.CORE_MODULES = [
             // 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 },
+            directiveRemove: {
+                name: 'directiveRemove',
+                mutates: true,
+                description: 'delete a custom directive',
+                positional: { name: 'name', required: true, description: 'the custom directive to delete (built-in directives cannot be removed)' },
+                example: 'wingfoil directive remove api-style',
+                fn: directiveRemoveFn,
+            },
         },
     },
 ];