wingfoil 0.2.1 → 0.3.0

package/dist/core/index.js

@@ -14,7 +14,12 @@ 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;
+exports.workflowStatusAtHead = exports.statusWorkflow = exports.renderStatusConsole = exports.W_APPROVAL_ROLE_WITHOUT_AUTHORITY = exports.routeApproval = exports.approvalDiagnostics = exports.WORKFLOWS_MANIFEST_PATH = exports.workflowExistsMessage = exports.renderRemoveConsole = exports.renderCreateConsole = exports.NO_DECLARATION_MESSAGE = exports.KIND_CONFLICT_MESSAGE = exports.renderStartConsole = exports.renderEndConsole = exports.NO_PLAN_TYPE_MESSAGE = exports.NO_ACTIVE_WORKFLOW_MESSAGE = exports.workflowFinalizeAtHead = exports.renderFinalizeConsole = exports.phaseRecordTrailers = exports.NO_ACTIVE_WORKFLOW_TO_FINALIZE = exports.workflowNextAtHead = exports.renderNextConsole = exports.nextWorkflow = exports.buildStep = exports.loadWorkflowRegistryAtRev = exports.loadWorkflowRegistryAtHead = exports.loadWorkflowRegistry = exports.RevisionError = exports.resolveRevision = exports.isWellFormedRevision = exports.loadWorkflowsYamlAtRev = exports.loadWorkflowsYaml = exports.loadRolesYamlAtRev = exports.loadRolesYamlAtHead = exports.loadRolesYaml = exports.loadMemoryYamlAtRev = exports.loadMemoryYamlAtHead = exports.loadMemoryYaml = exports.loadDnaYamlAtRev = exports.loadDnaYamlAtHead = exports.loadDnaYaml = exports.loadDirectivesAtRev = exports.loadDirectivesAtHead = exports.loadDirectives = exports.ROLES_YAML_PATH = exports.MEMORY_YAML_PATH = exports.DNA_YAML_PATH = exports.DIRECTIVES_DIR_PATH = exports.ConfigFileMissingError = exports.MODULE_NAME = void 0;
+exports.requireUnmodifiedTargets = exports.requireUnmodifiedTarget = exports.requireNoDivergentStage = exports.requireInspectableTarget = exports.requireAbsentTarget = exports.committedScopeError = exports.CONFIG_WRITE_CONTRACT = exports.resolveAddType = exports.verifyCommittedScope = exports.commitMemoryTransition = exports.beginMemoryTransition = exports.selectRelevantMemoryDocuments = exports.NO_RELEVANT_MEMORY_NOTE = exports.filterRelevantMemoryDocuments = exports.DEFAULT_CONTEXT_LIMITS = exports.WINGFOIL_NOT_INITIALIZED = exports.WINGFOIL_ALREADY_INITIALIZED = exports.requireInitializedProject = exports.initWingfoilProject = exports.initWingfoilStorage = exports.runAsDryRun = exports.DRY_RUN_FLAG = exports.UNASSIGNED_ASSIGNMENT = exports.GLOBAL_ASSIGNMENT = exports.loadDirectiveListing = exports.buildDirectiveListing = exports.WrittenTimestamp = exports.validateExecutionContext = exports.serializeExecutionContext = exports.selectDirectivesById = exports.resolveRoleDirectives = exports.CONTEXT_PAYLOAD_FORMAT = exports.assembleExecutionContext = exports.parseElementRef = exports.malformedElementRefMessage = exports.W_UNRESOLVED_TOKEN = exports.W_UNCOMMITTED_INPUTS = exports.W_MEMORY_INVALID_STATE = exports.W_INSTANCE_WORKFLOW_UNKNOWN = exports.resolveInstanceRef = exports.NO_ITERATION_NOTE = exports.deduceWorkflowState = exports.selectWorkflowInstance = exports.readDeductionSnapshotAtHead = exports.deduceWorkflowStateAtHead = exports.workflowExitStates = exports.machineStates = exports.iterationStartState = exports.workflowCoreDiagnostics = exports.W_WORKFLOW_CHECKS_NOT_RUN = void 0;
+exports.CORE_MODULES = exports.dnaEntryFieldOfOption = exports.dnaEntryOptionName = exports.DNA_ENTRY_OPTION_PREFIX = exports.DNA_REWRITE_PLANNED_WARNING = exports.DNA_REWRITE_WARNING = exports.verifyBuiltinTemplates = exports.verifyCommittedPaths = exports.undeclaredCommittedPaths = void 0;
+exports.coreErrorOf = coreErrorOf;
+exports.loadDnaRoleSet = loadDnaRoleSet;
+exports.dnaRewriteConflict = dnaRewriteConflict;
 /**
  * `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):
@@ -43,24 +48,42 @@ const storage_1 = require("../storage");
 // (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 errors_1 = require("../storage/errors");
 const memory_1 = require("../memory");
 const loaders_1 = require("./loaders");
+const workflow_list_show_1 = require("./workflow-list-show");
+const workflow_next_1 = require("./workflow-next");
+const workflow_start_end_1 = require("./workflow-start-end");
+const workflow_finalize_1 = require("./workflow-finalize");
+const workflow_status_1 = require("./workflow-status");
+const workflow_create_remove_1 = require("./workflow-create-remove");
 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 required_fields_1 = require("./required-fields");
+const init_1 = require("./init");
 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_supersede_1 = require("./memory-supersede");
+const memory_amend_1 = require("./memory-amend");
 const memory_add_type_1 = require("./memory-add-type");
+const memory_add_link_1 = require("./memory-add-link");
 const write_guard_1 = require("./write-guard");
+const agent_execute_1 = require("./agent-execute");
+const agent_list_1 = require("./agent-list");
+const agent_show_1 = require("./agent-show");
 const usage_error_1 = require("./usage-error");
+const registry_1 = require("./registry");
 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");
+// A missing working-tree configuration file, named repository-relative (task-179, `bug-245`).
+Object.defineProperty(exports, "ConfigFileMissingError", { enumerable: true, get: function () { return loaders_2.ConfigFileMissingError; } });
 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; } });
@@ -70,17 +93,98 @@ Object.defineProperty(exports, "loadDirectives", { enumerable: true, get: functi
 // 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; } });
+// The same readers at any commit (task-137, `spec-012` §2 `stateRef`); each `…AtHead` is its
+// `…AtRev` at `'HEAD'`.
+Object.defineProperty(exports, "loadDirectivesAtRev", { enumerable: true, get: function () { return loaders_2.loadDirectivesAtRev; } });
 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, "loadDnaYamlAtRev", { enumerable: true, get: function () { return loaders_2.loadDnaYamlAtRev; } });
 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, "loadMemoryYamlAtRev", { enumerable: true, get: function () { return loaders_2.loadMemoryYamlAtRev; } });
 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, "loadRolesYamlAtRev", { enumerable: true, get: function () { return loaders_2.loadRolesYamlAtRev; } });
 Object.defineProperty(exports, "loadWorkflowsYaml", { enumerable: true, get: function () { return loaders_2.loadWorkflowsYaml; } });
+Object.defineProperty(exports, "loadWorkflowsYamlAtRev", { enumerable: true, get: function () { return loaders_2.loadWorkflowsYamlAtRev; } });
+var revision_1 = require("./revision");
+Object.defineProperty(exports, "isWellFormedRevision", { enumerable: true, get: function () { return revision_1.isWellFormedRevision; } });
+Object.defineProperty(exports, "resolveRevision", { enumerable: true, get: function () { return revision_1.resolveRevision; } });
+Object.defineProperty(exports, "RevisionError", { enumerable: true, get: function () { return revision_1.RevisionError; } });
+// task-194: the workflow registry with spec-003's core checks, and the exit-state computation
+// (spec-017 §4.4) task-198's deduction reuses.
+var workflow_registry_1 = require("./workflow-registry");
+Object.defineProperty(exports, "loadWorkflowRegistry", { enumerable: true, get: function () { return workflow_registry_1.loadWorkflowRegistry; } });
+Object.defineProperty(exports, "loadWorkflowRegistryAtHead", { enumerable: true, get: function () { return workflow_registry_1.loadWorkflowRegistryAtHead; } });
+Object.defineProperty(exports, "loadWorkflowRegistryAtRev", { enumerable: true, get: function () { return workflow_registry_1.loadWorkflowRegistryAtRev; } });
+// task-216: `workflow next` at `HEAD` (`spec-017` §6, §7.3, §8 `Step` / `NextResult`); the operation is
+// `CORE_MODULES`' `workflowNext`, and the step builder is what `agent execute --next` (task-235) and `status`
+// (task-225) reuse. `workflowNextAtHead` is also what the MCP Resource `wingfoil://workflows/-/next` serves (task-239).
+var workflow_next_2 = require("./workflow-next");
+Object.defineProperty(exports, "buildStep", { enumerable: true, get: function () { return workflow_next_2.buildStep; } });
+Object.defineProperty(exports, "nextWorkflow", { enumerable: true, get: function () { return workflow_next_2.nextWorkflow; } });
+Object.defineProperty(exports, "renderNextConsole", { enumerable: true, get: function () { return workflow_next_2.renderNextConsole; } });
+Object.defineProperty(exports, "workflowNextAtHead", { enumerable: true, get: function () { return workflow_next_2.workflowNextAtHead; } });
+// task-226: `workflow finalize` (`spec-017` §7.9, §8 `FinalizeResult`); the operation is `CORE_MODULES`'
+// `workflowFinalize`.
+var workflow_finalize_2 = require("./workflow-finalize");
+Object.defineProperty(exports, "NO_ACTIVE_WORKFLOW_TO_FINALIZE", { enumerable: true, get: function () { return workflow_finalize_2.NO_ACTIVE_WORKFLOW_TO_FINALIZE; } });
+Object.defineProperty(exports, "phaseRecordTrailers", { enumerable: true, get: function () { return workflow_finalize_2.phaseRecordTrailers; } });
+Object.defineProperty(exports, "renderFinalizeConsole", { enumerable: true, get: function () { return workflow_finalize_2.renderFinalizeConsole; } });
+Object.defineProperty(exports, "workflowFinalizeAtHead", { enumerable: true, get: function () { return workflow_finalize_2.workflowFinalizeAtHead; } });
+// task-217: `CORE_MODULES`' `workflowStart` / `workflowEnd` (`spec-017` §7.1–§7.2) and their values.
+var workflow_start_end_2 = require("./workflow-start-end");
+Object.defineProperty(exports, "NO_ACTIVE_WORKFLOW_MESSAGE", { enumerable: true, get: function () { return workflow_start_end_2.NO_ACTIVE_WORKFLOW_MESSAGE; } });
+Object.defineProperty(exports, "NO_PLAN_TYPE_MESSAGE", { enumerable: true, get: function () { return workflow_start_end_2.NO_PLAN_TYPE_MESSAGE; } });
+Object.defineProperty(exports, "renderEndConsole", { enumerable: true, get: function () { return workflow_start_end_2.renderEndConsole; } });
+Object.defineProperty(exports, "renderStartConsole", { enumerable: true, get: function () { return workflow_start_end_2.renderStartConsole; } });
+var workflow_create_remove_2 = require("./workflow-create-remove");
+Object.defineProperty(exports, "KIND_CONFLICT_MESSAGE", { enumerable: true, get: function () { return workflow_create_remove_2.KIND_CONFLICT_MESSAGE; } });
+Object.defineProperty(exports, "NO_DECLARATION_MESSAGE", { enumerable: true, get: function () { return workflow_create_remove_2.NO_DECLARATION_MESSAGE; } });
+Object.defineProperty(exports, "renderCreateConsole", { enumerable: true, get: function () { return workflow_create_remove_2.renderCreateConsole; } });
+Object.defineProperty(exports, "renderRemoveConsole", { enumerable: true, get: function () { return workflow_create_remove_2.renderRemoveConsole; } });
+Object.defineProperty(exports, "workflowExistsMessage", { enumerable: true, get: function () { return workflow_create_remove_2.workflowExistsMessage; } });
+Object.defineProperty(exports, "WORKFLOWS_MANIFEST_PATH", { enumerable: true, get: function () { return workflow_create_remove_2.WORKFLOWS_MANIFEST_PATH; } });
+// task-225: `workflow status` at `HEAD` (`spec-017` §5.1–§5.4, §7.4, §8 `StatusResult`); approval detection and
+// routing live in the step builder above, so `next` reports them too. The operation is `CORE_MODULES`' `workflowStatus`.
+var workflow_next_3 = require("./workflow-next");
+Object.defineProperty(exports, "approvalDiagnostics", { enumerable: true, get: function () { return workflow_next_3.approvalDiagnostics; } });
+Object.defineProperty(exports, "routeApproval", { enumerable: true, get: function () { return workflow_next_3.routeApproval; } });
+Object.defineProperty(exports, "W_APPROVAL_ROLE_WITHOUT_AUTHORITY", { enumerable: true, get: function () { return workflow_next_3.W_APPROVAL_ROLE_WITHOUT_AUTHORITY; } });
+var workflow_status_2 = require("./workflow-status");
+Object.defineProperty(exports, "renderStatusConsole", { enumerable: true, get: function () { return workflow_status_2.renderStatusConsole; } });
+Object.defineProperty(exports, "statusWorkflow", { enumerable: true, get: function () { return workflow_status_2.statusWorkflow; } });
+Object.defineProperty(exports, "workflowStatusAtHead", { enumerable: true, get: function () { return workflow_status_2.workflowStatusAtHead; } });
+var workflow_core_checks_1 = require("./workflow-core-checks");
+Object.defineProperty(exports, "W_WORKFLOW_CHECKS_NOT_RUN", { enumerable: true, get: function () { return workflow_core_checks_1.W_WORKFLOW_CHECKS_NOT_RUN; } });
+Object.defineProperty(exports, "workflowCoreDiagnostics", { enumerable: true, get: function () { return workflow_core_checks_1.workflowCoreDiagnostics; } });
+var workflow_exit_state_1 = require("./workflow-exit-state");
+Object.defineProperty(exports, "iterationStartState", { enumerable: true, get: function () { return workflow_exit_state_1.iterationStartState; } });
+Object.defineProperty(exports, "machineStates", { enumerable: true, get: function () { return workflow_exit_state_1.machineStates; } });
+Object.defineProperty(exports, "workflowExitStates", { enumerable: true, get: function () { return workflow_exit_state_1.workflowExitStates; } });
+var workflow_deduction_1 = require("./workflow-deduction");
+Object.defineProperty(exports, "deduceWorkflowStateAtHead", { enumerable: true, get: function () { return workflow_deduction_1.deduceWorkflowStateAtHead; } });
+Object.defineProperty(exports, "readDeductionSnapshotAtHead", { enumerable: true, get: function () { return workflow_deduction_1.readDeductionSnapshotAtHead; } });
+Object.defineProperty(exports, "selectWorkflowInstance", { enumerable: true, get: function () { return workflow_deduction_1.selectWorkflowInstance; } });
+var deduce_1 = require("../workflow/deduce");
+Object.defineProperty(exports, "deduceWorkflowState", { enumerable: true, get: function () { return deduce_1.deduceWorkflowState; } });
+Object.defineProperty(exports, "NO_ITERATION_NOTE", { enumerable: true, get: function () { return deduce_1.NO_ITERATION_NOTE; } });
+Object.defineProperty(exports, "resolveInstanceRef", { enumerable: true, get: function () { return deduce_1.resolveInstanceRef; } });
+Object.defineProperty(exports, "W_INSTANCE_WORKFLOW_UNKNOWN", { enumerable: true, get: function () { return deduce_1.W_INSTANCE_WORKFLOW_UNKNOWN; } });
+Object.defineProperty(exports, "W_MEMORY_INVALID_STATE", { enumerable: true, get: function () { return deduce_1.W_MEMORY_INVALID_STATE; } });
+Object.defineProperty(exports, "W_UNCOMMITTED_INPUTS", { enumerable: true, get: function () { return deduce_1.W_UNCOMMITTED_INPUTS; } });
+Object.defineProperty(exports, "W_UNRESOLVED_TOKEN", { enumerable: true, get: function () { return deduce_1.W_UNRESOLVED_TOKEN; } });
+var element_ref_1 = require("./element-ref");
+Object.defineProperty(exports, "malformedElementRefMessage", { enumerable: true, get: function () { return element_ref_1.malformedElementRefMessage; } });
+Object.defineProperty(exports, "parseElementRef", { enumerable: true, get: function () { return element_ref_1.parseElementRef; } });
 var context_2 = require("./context");
 Object.defineProperty(exports, "assembleExecutionContext", { enumerable: true, get: function () { return context_2.assembleExecutionContext; } });
+Object.defineProperty(exports, "CONTEXT_PAYLOAD_FORMAT", { enumerable: true, get: function () { return context_2.CONTEXT_PAYLOAD_FORMAT; } });
 Object.defineProperty(exports, "resolveRoleDirectives", { enumerable: true, get: function () { return context_2.resolveRoleDirectives; } });
 Object.defineProperty(exports, "selectDirectivesById", { enumerable: true, get: function () { return context_2.selectDirectivesById; } });
+Object.defineProperty(exports, "serializeExecutionContext", { enumerable: true, get: function () { return context_2.serializeExecutionContext; } });
+Object.defineProperty(exports, "validateExecutionContext", { enumerable: true, get: function () { return context_2.validateExecutionContext; } });
+Object.defineProperty(exports, "WrittenTimestamp", { enumerable: true, get: function () { return context_2.WrittenTimestamp; } });
 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; } });
@@ -95,17 +199,25 @@ __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 dry_run_1 = require("./dry-run");
+Object.defineProperty(exports, "DRY_RUN_FLAG", { enumerable: true, get: function () { return dry_run_1.DRY_RUN_FLAG; } });
+Object.defineProperty(exports, "runAsDryRun", { enumerable: true, get: function () { return dry_run_1.runAsDryRun; } });
+var init_2 = require("./init");
+Object.defineProperty(exports, "initWingfoilStorage", { enumerable: true, get: function () { return init_2.initWingfoilStorage; } });
+Object.defineProperty(exports, "initWingfoilProject", { enumerable: true, get: function () { return init_2.initWingfoilProject; } });
+Object.defineProperty(exports, "requireInitializedProject", { enumerable: true, get: function () { return init_2.requireInitializedProject; } });
+Object.defineProperty(exports, "WINGFOIL_ALREADY_INITIALIZED", { enumerable: true, get: function () { return init_2.WINGFOIL_ALREADY_INITIALIZED; } });
+Object.defineProperty(exports, "WINGFOIL_NOT_INITIALIZED", { enumerable: true, get: function () { return init_2.WINGFOIL_NOT_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; } });
+Object.defineProperty(exports, "selectRelevantMemoryDocuments", { enumerable: true, get: function () { return relevance_1.selectRelevantMemoryDocuments; } });
+// `prepareMemoryTransition` is deliberately not re-exported: outside `./memory-transition` a transition
+// starts at `beginMemoryTransition`, which runs the identity pre-flight first (task-132 review).
 var memory_transition_2 = require("./memory-transition");
+Object.defineProperty(exports, "beginMemoryTransition", { enumerable: true, get: function () { return memory_transition_2.beginMemoryTransition; } });
 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; } });
@@ -113,6 +225,8 @@ 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, "requireInspectableTarget", { enumerable: true, get: function () { return write_guard_2.requireInspectableTarget; } });
+Object.defineProperty(exports, "requireNoDivergentStage", { enumerable: true, get: function () { return write_guard_2.requireNoDivergentStage; } });
 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; } });
@@ -124,31 +238,71 @@ Object.defineProperty(exports, "verifyBuiltinTemplates", { enumerable: true, get
  * 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.
+ * "no function throws for *expected* domain failures" implies unexpected ones still may). Every
+ * read-only query (`dnaShowFn`, `pathsFn`, `workflowListFn`, …) maps its loader's failures through it,
+ * so the mapping is written once. (The `wrapReadOnly` adapter it was factored out of had one caller
+ * left, `workflowList`, until task-204 gave that operation a flag and was removed with 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;
+        const refusal = coreErrorOf(error);
+        if (refusal === null)
+            throw error;
+        return (0, types_1.coreErr)(refusal);
     }
 }
-/** 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));
-    };
+/**
+ * The expected failure a pillar loader throws, as the {@link CoreError} a read-only query returns for
+ * it, or `null` when `error` is not one (a programmer bug, which the caller re-throws). This is
+ * {@link loadOrError}'s mapping on its own, for a surface that calls a loader directly rather than
+ * through a `CoreOperation` — the MCP server's Resource and Prompt handlers (task-174, `bug-184`), so a
+ * refusal there carries the same details (`./error-details.ts`) the CLI prints:
+ *
+ * - a loader that collects spec-003 diagnostics (task-136): the first error is the reason, and the whole
+ *   ordered array rides `details` under spec-003's own name for it, `diagnostics`;
+ * - a `ValidationError` from the shared two-pass pipeline: `details.issues`;
+ * - a missing file (`ENOENT`): `NOT_FOUND`, with the system message.
+ */
+function coreErrorOf(error) {
+    if (error instanceof validation_1.DiagnosticsError) {
+        return { code: 'VALIDATION', message: error.message, details: { diagnostics: error.diagnostics } };
+    }
+    if (error instanceof validation_1.ValidationError) {
+        return { code: 'VALIDATION', message: error.message, details: { issues: error.issues } };
+    }
+    const errno = error;
+    if (errno && errno.code === 'ENOENT') {
+        return { code: 'NOT_FOUND', message: errno.message };
+    }
+    return null;
+}
+/**
+ * The DNA role set — `dna.yaml` `team.roles[].name`, in declaration order — read once, by `wingfoil
+ * mcp`'s pre-flight, for the Prompts channel to serve for the server's whole life (`dl-049` (b),
+ * spec-004 §3.1 "derived from DNA at server start", spec-014 §1; task-174).
+ *
+ * A root with no `.wingfoil/` is refused with the shared not-initialized message
+ * ({@link requireInitializedProject}, task-143) before anything is read, so the refusal names no path
+ * (`bug-035`); an unreadable or invalid `dna.yaml` is refused as every read-only query refuses it.
+ */
+function loadDnaRoleSet(root) {
+    return loadConfigOrError(root, () => (0, loaders_1.loadDnaYaml)(root).team.roles.map(({ name }) => name));
+}
+/**
+ * {@link loadOrError} for a read that needs the project's configuration: a root with no `.wingfoil/` is
+ * refused first with the shared not-initialized message ({@link requireInitializedProject}, task-143),
+ * which names no path; otherwise the loader runs and its failures map as `loadOrError` maps them — a
+ * missing file as `ConfigFileMissingError`'s repository-relative message (task-179, `bug-198`,
+ * `bug-245`).
+ */
+function loadConfigOrError(root, loader) {
+    const initialized = (0, init_1.requireInitializedProject)(root);
+    if (!initialized.ok)
+        return initialized;
+    return loadOrError(loader);
 }
 /**
  * `paths` `CoreOperation.fn` (P2.5, spec-002-dna-yaml-schema's `Paths` node) —
@@ -169,7 +323,7 @@ function wrapReadOnly(loader) {
  */
 const pathsFn = async (params) => {
     const { root, positional: category } = params;
-    const loaded = loadOrError(() => (0, loaders_1.loadDnaYaml)(root));
+    const loaded = loadConfigOrError(root, () => (0, loaders_1.loadDnaYaml)(root));
     if (!loaded.ok)
         return loaded;
     if (category === undefined)
@@ -196,7 +350,7 @@ const pathsFn = async (params) => {
  */
 const dnaShowFn = async (params) => {
     const { root, positional: section } = params;
-    const loaded = loadOrError(() => (0, loaders_1.loadDnaYaml)(root));
+    const loaded = loadConfigOrError(root, () => (0, loaders_1.loadDnaYaml)(root));
     if (!loaded.ok || section === undefined)
         return loaded;
     const key = set_1.DNA_KEY_ALIASES[section] ?? section;
@@ -206,18 +360,39 @@ const dnaShowFn = async (params) => {
     }
     return (0, types_1.coreOk)(dna[key]);
 };
+/**
+ * The refusal of a DNA write the in-place editor cannot express, when `--force` was not given
+ * (task-193, approver ruling R20/Q9 of `release-planning-rel-v0.3-plan`: the same rule as
+ * `dl-062` for `roles.yaml`, task-169's `rolesRewriteConflict`). `CONFLICT`, exit 1, nothing
+ * written. Pinned in `spec-008` §6.
+ */
+function dnaRewriteConflict(field) {
+    return `dna.yaml cannot be updated in place; edit ${field} by hand, or pass --force to rewrite the whole file`;
+}
+/**
+ * The warning a `--force`d whole-file rewrite of `dna.yaml` carries on its success (task-193), on
+ * task-169's success-warning channel (`CoreResult.warnings`). It names what the `js-yaml` `dump` of
+ * the parsed document does not keep — the list `ROLES_REWRITE_WARNING` gives for `roles.yaml`,
+ * since the two files go through the same `dump`. Pinned in `spec-008` §6.
+ */
+exports.DNA_REWRITE_WARNING = 'dna.yaml was rewritten as a whole file (--force): comments are not kept, and neither are quoting, flow style, ' +
+    'blank lines, line endings or number formatting (1.0 becomes 1)';
+/** {@link DNA_REWRITE_WARNING} as a `--dry-run` words it: the rewrite is planned, not done (task-210 review). */
+exports.DNA_REWRITE_PLANNED_WARNING = exports.DNA_REWRITE_WARNING.replace('dna.yaml was rewritten', 'dna.yaml would be rewritten');
 /**
  * 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
+ * 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
@@ -238,13 +413,20 @@ const dnaShowFn = async (params) => {
  *    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).
+ *    `undefined`, and the only other candidate is the whole-file `dump(dna, { lineWidth: -1 })` —
+ *    correct, but it keeps no comment. Both are deterministic (REQ-SYS-07). Since task-193 (`bug-019`,
+ *    `bug-126`; ruling R20/Q9, as `dl-062`) that rewrite is **refused** (`CONFLICT`, exit 1,
+ *    {@link dnaRewriteConflict}) unless `force` authorizes it, and a forced one succeeds with
+ *    {@link DNA_REWRITE_WARNING}. The refusal comes after step 7, so a write the schema would refuse
+ *    anyway is reported as the `VALIDATION` it is, not as something `--force` could fix. `force`
+ *    authorizes the rewrite and does not demand it: an in-place edit is still made in place, unwarned.
  * 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,
+ *    validates the exact bytes about to be written: `--value` is a string, so
+ *    `wingfoil dna set version --value 2` serializes `'2'` and fails `z.number()` on read-back — refused
+ *    at exit 1, `expected number, received string`, nothing written (measured with that command on a
+ *    fresh `init --template scrum` repository, task-184, bug-096). 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
@@ -255,14 +437,20 @@ const dnaShowFn = async (params) => {
  *    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) {
+async function runDnaMutation(root, request, subject, scalarOnly, force) {
     const identity = (0, git_identity_1.requireGitIdentity)(root);
     if (!identity.ok)
         return identity;
+    // REQ-SEC-06 / bug-121 (task-172): `writeDocument` follows a symlinked `dna.yaml`, so a file that
+    // leads outside the project, or is itself a link, is refused before any read or write. First, so a
+    // path that leaves the project is reported as leaving it (`requireConfinedTarget`'s ordering rule).
+    const confined = (0, confinement_1.requireConfinedWriteTarget)(root, loaders_1.DNA_YAML_PATH, 'write');
+    if (!confined.ok)
+        return confined;
     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));
+    const loaded = loadConfigOrError(root, () => (0, loaders_1.loadDnaYaml)(root));
     if (!loaded.ok)
         return loaded;
     if (scalarOnly) {
@@ -281,21 +469,33 @@ async function runDnaMutation(root, request, subject = dnaCommitSubject(request)
         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));
+    const inPlace = (0, edit_1.applyDnaEditInText)(current, applied.edit, applied.dna);
+    const serialized = inPlace ?? (0, js_yaml_1.dump)(applied.dna, { lineWidth: -1 });
+    // Labelled repository-relative, as every working-tree loader labels it (task-179, `bug-245`).
+    const parsed = schema_1.DnaYaml.safeParse((0, validation_1.parseYaml)(serialized, loaders_1.DNA_YAML_PATH));
     if (!parsed.success) {
-        const validationError = (0, validation_1.toValidationError)(parsed.error, dnaPath);
+        const validationError = (0, validation_1.toValidationError)(parsed.error, loaders_1.DNA_YAML_PATH);
         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 warnings = [];
+    const plannedWarnings = [];
+    if (inPlace === undefined) {
+        if (!force)
+            return (0, types_1.coreErr)({ code: 'CONFLICT', message: dnaRewriteConflict(request.field) });
+        warnings.push(exports.DNA_REWRITE_WARNING);
+        plannedWarnings.push(exports.DNA_REWRITE_PLANNED_WARNING);
+    }
+    const sha = (0, storage_1.writeAndCommit)(root, [{ path: loaders_1.DNA_YAML_PATH, content: serialized }], subject, {
+        warnings,
+        plannedWarnings,
+    });
     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 });
+    return (0, types_1.coreOk)(outcome, { sha, message: subject }, warnings);
 }
 /**
  * The one-line commit subject a DNA mutation writes: `wf(dna): {verb} {field} [{value}]`, extending
@@ -311,39 +511,40 @@ function dnaCommitSubject(request) {
  * 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:
+ * Two usage errors, in the order they are checked:
  *
- * 1. **Missing** — nothing to act on.
+ * 1. **Missing** — nothing to act on: {@link missingOperandReason}'s `missing required argument: <path>`,
+ *    the wording every command uses (task-179, `bug-168`). The CLI registrar refuses it first, with the
+ *    usage hint; this is the same refusal for a caller that reaches core without the registrar.
  * 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).
+ *    (`dl-083-dotted-entry-names-in-paths`, task-099).
  *
- * All three are exit `2` (`UsageError` → `exitCodeForThrow`, `spec-005-cli-command-contract` §1).
+ * A surplus operand — the old `dna set <key> <value>` spelling — is not checked here: since task-179
+ * (`bug-180`) the registrar refuses it before the project root is resolved, as for every command, with
+ * the `the value travels in --value` migration hint the four verbs declare ({@link DNA_SURPLUS_HINT}).
+ *
+ * Both are exit `2` (`UsageError` → `exitCodeForThrow`, `spec-005-cli-command-contract` §1).
  */
-function dnaPathPositional(verb, positionals) {
+function dnaPathPositional(positionals) {
     const path = positionals?.[0];
     if (path === undefined) {
-        throw new usage_error_1.UsageError(`missing required argument: wingfoil dna ${verb} <path> --value <value>`);
+        throw new usage_error_1.UsageError((0, registry_1.missingOperandReason)('path'));
     }
     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;
 }
+/**
+ * What the surplus-operand refusal of the four DNA path verbs adds (`CorePositional.surplusHint`): the
+ * value moved out of a second positional into `--value` (`dl-082`, task-093), so a stale
+ * `dna set <key> <value>` is told where it goes.
+ */
+const DNA_SURPLUS_HINT = 'the value travels in --value';
 /**
  * `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
@@ -362,8 +563,8 @@ function dnaPathPositional(verb, positionals) {
  * write the field.
  */
 const dnaSetFn = async (params) => {
-    const { root, positionals, options } = params;
-    const keyPath = dnaPathPositional('set', positionals);
+    const { root, positionals, options, force } = params;
+    const keyPath = dnaPathPositional(positionals);
     const value = options?.value;
     if (value === undefined) {
         throw new usage_error_1.UsageError('missing required argument: --value');
@@ -372,11 +573,11 @@ const dnaSetFn = async (params) => {
     // 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);
+    return runDnaMutation(root, { verb: 'update', field: keyPath, value }, `wf(dna): set ${keyPath}`, true, force === 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);
+    const field = dnaPathPositional(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
@@ -402,18 +603,21 @@ function dnaMutationRequest(verb, positionals, options) {
 }
 /** `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));
+    const { root, positionals, options, force } = params;
+    const request = dnaMutationRequest('add', positionals, options);
+    return runDnaMutation(root, request, dnaCommitSubject(request), false, force === true);
 };
 /** `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));
+    const { root, positionals, options, force } = params;
+    const request = dnaMutationRequest('remove', positionals, options);
+    return runDnaMutation(root, request, dnaCommitSubject(request), false, force === true);
 };
 /** `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));
+    const { root, positionals, options, force } = params;
+    const request = dnaMutationRequest('update', positionals, options);
+    return runDnaMutation(root, request, dnaCommitSubject(request), false, force === true);
 };
 /**
  * The `--entry-<field>` namespace, re-exported from the DNA pillar (`src/dna/path.ts`), which owns it
@@ -445,23 +649,38 @@ 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)',
+};
+/**
+ * `--force` on the four DNA write verbs (task-193, ruling R20/Q9): the opt-in to the whole-file rewrite
+ * the in-place editor would otherwise refuse. A per-command flag, listed in `spec-008` §12.
+ */
+const DNA_FORCE_FLAG = {
+    name: 'force',
+    description: 'rewrite the whole dna.yaml when it cannot be edited in place (comments and formatting are not kept)',
 };
 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,
@@ -469,14 +688,26 @@ const DNA_ENTRY_OPTIONS = (0, path_2.dnaEntryOptionNames)().map((field) => ({
  *    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.
+ *    With `--workflow <ref> [--step <key>]` (task-227, `spec-017` §7.10), the step the element is linked to
+ *    is then resolved from the deduction at `HEAD` ({@link resolveAddLink}); a refusal (`NOT_FOUND`,
+ *    `CONFLICT`, `VALIDATION`) is returned before the id is allocated, and the add commit carries the
+ *    `WingFoil-Instance` / `WingFoil-Step` trailers. `--step` without `--workflow` is a usage error (exit 2).
  * 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
+ *    `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 matched
+ *    against the already-materialized pattern (`src/memory/add.ts`; no wall-clock/random): the
+ *    highest number any local branch, remote-tracking ref, `HEAD` or the working tree holds, across
+ *    every folder the committed `path` pattern can resolve to, plus one (task-128, `dl-101` §2 (a),
+ *    `bug-087`, `bug-162`). That read is wider than `HEAD` on purpose — it can only raise the number —
+ *    and is the declared baseline `command-baseline` records for it.
+ * 5. **Fill the committed scaffold's bytes** with only the `id`/`status`/`--title`/`--tags`
+ *    skeleton (P1.3; spec-010-memory-frontmatter-schema) plus the `--set` fields (a context token only
+ *    where the scaffold declares it). `status` is the head of the type's committed machine
+ *    (`spec-001`; `bug-214`, task-180), and a WIP limit declared on that state is checked
+ *    (`requireWipSlot`, `CONFLICT`, exit 1), its holders counted at `HEAD` and on every local and
+ *    remote-tracking branch (`dl-156` Q1 (a), task-274). 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`.
  *
@@ -486,56 +717,118 @@ const DNA_ENTRY_OPTIONS = (0, path_2.dnaEntryOptionNames)().map((field) => ({
  * 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;
+    const { root, options, fields: extraFields } = params;
+    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);
+    // task-227 (`spec-017` §7.10): `--step` picks a step of the instance `--workflow` names.
+    const workflowRef = singleOption(options, 'workflow');
+    const stepKey = singleOption(options, 'step');
+    if (stepKey !== undefined && workflowRef === undefined)
+        throw new usage_error_1.UsageError('missing required argument: --workflow');
+    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.
     const resolved = (0, memory_add_type_1.resolveAddType)(root, type);
     if (!resolved.ok)
         return resolved;
-    const { pathPattern, idPattern, scaffold } = resolved.value;
+    const { pathPattern, idPattern, scaffold, initialState, memoryYaml: committedMemoryYaml } = 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)
+        // task-227: the step the element is linked to, decided at HEAD before the id is allocated, so every
+        // refusal precedes the write (and a dry run refuses the same way). A `spec-003` error at HEAD maps as
+        // `workflow next` maps it; a git failure is a `StorageError`, mapped below.
+        let link;
+        if (workflowRef !== undefined) {
+            const resolvedLink = loadOrError(() => (0, memory_add_link_1.resolveAddLink)(root, workflowRef, stepKey, type));
+            const linked = resolvedLink.ok ? resolvedLink.value : resolvedLink;
+            if (!linked.ok)
+                return linked;
+            link = linked.value;
+        }
+        const trailers = link === undefined ? [] : (0, memory_add_link_1.addLinkTrailers)(link);
+        // spec-001's order: {date} → {author} → field/context tokens → {slug} → {n}, so the counter sees
+        // the materialized prefix. {date} is read ONCE, from the author date git records for this add's
+        // commit, and the commit is pinned to it below, as it is to the author {author} slugs (task-163).
+        const date = (0, validation_1.patternTokens)(idPattern).includes('date') ? (0, memory_1.readAuthorDate)(root, identity.value) : undefined;
+        const materialized = (0, memory_1.expandFieldTokens)(idPattern, set.values, { date, authorName: identity.value.name });
+        const sequence = (0, memory_1.hasNumericToken)(materialized)
+            ? (0, memory_1.nextSequenceNumber)(root, pathPattern, 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 message = `wf(${type}): add ${id}`;
+        const id = (0, validation_1.generateId)(materialized, { slug: (0, memory_1.slugifyTitle)(title), n: sequence });
+        const extra = Object.keys(extraFields ?? {})
+            .sort()
+            .map((name) => [name, extraFields[name]]);
+        const content = (0, memory_1.renderAddDocument)(scaffold, { id, title, tags, fields: [...(0, memory_1.writtenFields)(scaffold, set.values), ...extra], status: initialState });
+        const pathValues = { ...set.values, id };
+        const subject = `wf(${type}): add ${id}`;
+        // What the operation reports is the message it records, the build signature aside (`commitPaths`).
+        const message = trailers.length === 0 ? subject : `${subject}\n\n${trailers.join('\n')}`;
         // 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
+        // Since task-128 a `{n}` id is above every number any baseline holds, but a slug-only id
+        // (`note-{slug}`) still lands on an occupied path whenever the title repeats, and a `{n}` id can
+        // land on a git-ignored file (no baseline the counter reads holds it). The write below
+        // is unconditional, which would turn `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 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);
+        // `add` is the verb that enters the initial state, so a WIP limit declared there holds here too
+        // (task-180, `dl-110` P3 (a)), counted at `HEAD` — the commit the type was resolved at — and on
+        // every local and remote-tracking branch (`dl-156` Q1 (a), task-274).
+        const slot = (0, memory_transition_1.requireWipSlot)(root, 'HEAD', committedMemoryYaml, type, initialState);
+        if (!slot.ok)
+            return slot;
+        const warnings = slot.value.map(validation_1.formatDiagnostic);
+        const { path, sha } = (0, memory_1.writeMemoryEntry)(root, pathPattern, pathValues, content, subject, {
+            author: identity.value,
+            warnings,
+            trailers,
+            // `@`: git reads a bare `<seconds> <offset>` as a timestamp only from 9 digits of seconds up
+            // (`0 +0000` is "invalid date format"); `@<seconds> <offset>` is a timestamp at any width.
+            ...(date === undefined ? {} : { env: { GIT_AUTHOR_DATE: `@${date}` } }),
+        });
         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 });
+        return (0, types_1.coreOk)({ id, path: (0, path_1.relative)(root, path) }, { sha, message }, warnings);
     }
     catch (error) {
         if (error instanceof storage_1.StorageError) {
-            return (0, types_1.coreErr)({ code: 'IO', message: error.message });
+            // One rule, one code (task-130, `bug-123`, `spec-005` §3): a confinement refusal is `VALIDATION`
+            // here as it is from the transition verbs' guard — the request named a target REQ-SEC-06
+            // forbids, or one outside its type's folder (task-281, `bug-325`, approver ruling D1: exit 1).
+            // Every other storage failure (a git read, an unresolved path token) stays `IO`.
+            const confinement = error.code === errors_1.E_PATH_ESCAPES_ROOT || error.code === errors_1.E_PATH_OUTSIDE_TYPE_FOLDER || error.code === errors_1.E_TARGET_IS_SYMLINK;
+            return (0, types_1.coreErr)({ code: confinement ? 'VALIDATION' : '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 });
+            // Every `ValidationError` src/ builds carries at least one issue (task-189: each construction
+            // site passes a literal issue, is guarded by `issues.length > 0`, or maps a failed Zod parse),
+            // so the issues ARE the reason; there is no issue-less fallback to choose.
+            return (0, types_1.coreErr)({ code: 'VALIDATION', message: error.issues.map((issue) => issue.message).join('; ') });
         }
         throw error;
     }
@@ -585,22 +878,26 @@ const memorySearchFn = async (params) => {
     if (positional !== undefined)
         (0, memory_1.validateSearchQuery)(positional);
     const query = positional ?? '';
-    const loaded = loadOrError(() => (0, loaders_1.loadMemoryYaml)(root));
+    const loaded = loadConfigOrError(root, () => (0, loaders_1.loadMemoryYaml)(root));
     if (!loaded.ok)
         return loaded;
     const tag = options?.tag;
     const type = options?.type;
     const status = options?.status;
+    const diagnostics = [];
     const scanned = (0, memory_1.searchMemoryDocuments)(root, loaded.value, query, {
         ...(tag !== undefined ? { tag } : {}),
         ...((0, memory_1.isArchivedStatus)(status) ? { includeArchived: true } : {}),
+        onDiagnostic: (diagnostic) => diagnostics.push(diagnostic),
     });
     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 }));
+    // task-171 (`bug-031`): a file the scan could not read is a warning, never the search's failure.
+    const warnings = diagnostics.map(validation_1.formatDiagnostic);
     return matches.length === 0
-        ? (0, types_1.coreOk)({ query, matches, message: NO_MEMORY_SEARCH_MATCHES_MESSAGE })
-        : (0, types_1.coreOk)({ query, matches });
+        ? (0, types_1.coreOk)({ query, matches, message: NO_MEMORY_SEARCH_MATCHES_MESSAGE }, undefined, warnings)
+        : (0, types_1.coreOk)({ query, matches }, undefined, warnings);
 };
 /**
  * `memory history` `CoreOperation.fn` (P1.10, `mutates: false`; spec-006-core-domain-api §3 memory
@@ -617,7 +914,9 @@ const memorySearchFn = async (params) => {
  * 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
+ *    `document not found: <id>`, returned rather than thrown. A document written in a `format` newer
+ *    than this build reads is refused, `VALIDATION` (exit 1) with the `dl-149` `E_INVALID_FORMAT` text
+ *    (task-257, `bug-241`); one the lookup passes on its way is a warning. 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.
@@ -629,20 +928,49 @@ const memorySearchFn = async (params) => {
  *
  * 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.
+ * A git read that fails — a tree git cannot read, an answer past the read buffer — is a `CoreError`
+ * `IO` (exit `1`) carrying git's message, never an empty trail (task-142, `bug-072`).
  */
 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>');
+        throw new usage_error_1.UsageError((0, registry_1.missingOperandReason)('id'));
     }
-    const loaded = loadOrError(() => (0, loaders_1.loadMemoryYaml)(root));
+    const loaded = loadConfigOrError(root, () => (0, loaders_1.loadMemoryYaml)(root));
     if (!loaded.ok)
         return loaded;
-    const found = (0, memory_1.findMemoryDocumentById)(root, loaded.value, id);
+    const diagnostics = [];
+    let found;
+    try {
+        found = (0, memory_1.findMemoryDocumentById)(root, loaded.value, id, { onDiagnostic: (diagnostic) => diagnostics.push(diagnostic) });
+    }
+    catch (error) {
+        // The `dl-149` refusal of the element the lookup names (task-257, `bug-241`): a document written in
+        // a newer format is not read by today's rules. Any other failure (an unreadable directory) is not
+        // that refusal and propagates as it did (review F2).
+        if (!(0, validation_1.isNewerFormatError)(error))
+            throw error;
+        return (0, types_1.coreErr)({
+            code: 'VALIDATION',
+            message: `cannot read the history of ${id}: its document is written in a newer format: ${error.message}`,
+            details: { issues: error.issues },
+        });
+    }
     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) => ({
+    let transitions;
+    try {
+        transitions = (0, memory_1.reconstructMemoryTransitions)(root, found.path);
+    }
+    catch (error) {
+        // A git read that failed is `IO`, never an empty trail (task-142, `bug-072`): the walk throws
+        // rather than answering "no history" for a history it could not read. Since task-171 the tolerant
+        // reconstruction throws nothing else (a revision that does not parse is an entry, `bug-188`), so
+        // what reaches here is a `StorageError`.
+        return (0, types_1.coreErr)({ code: 'IO', message: error.message });
+    }
+    const entries = transitions.map((transition) => ({
         sha: transition.sha,
         author: `${transition.authorName} <${transition.authorEmail}>`,
         timestamp: transition.date,
@@ -654,55 +982,81 @@ const memoryHistoryFn = async (params) => {
             : null,
         reason: transition.reason,
         subject: transition.subject,
+        wingfoil: transition.wingfoil,
+        ...(transition.unreadable !== undefined ? { unreadable: transition.unreadable } : {}),
     }));
-    return (0, types_1.coreOk)({ id, path: found.path, entries });
+    // task-171: the documents the lookup could not read (`bug-031`), then each revision of this one whose
+    // frontmatter does not parse (`bug-188`), named with its commit.
+    for (const transition of transitions) {
+        if (transition.unreadable !== undefined) {
+            diagnostics.push((0, memory_1.memoryUnreadableDiagnostic)(found.path, `${(0, memory_1.firstLineOf)(transition.unreadable)} (at ${transition.sha})`));
+        }
+    }
+    return (0, types_1.coreOk)({ id, path: found.path, entries }, undefined, diagnostics.map(validation_1.formatDiagnostic));
 };
 /**
  * `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,
+ * 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. Steps 2 and 3 are {@link beginMemoryTransition},
+ *    the preamble every transition verb shares (task-132, `bug-142`; `spec-006` §7).
+ * 3. **{@link prepareMemoryTransition}** — it resolves the `memory.yaml` and the document committed at
+ *    `HEAD` itself (task-091, `dl-080` (B); task-247, `bug-187`); 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).
+ *    A field the type lists in `template.frontmatter.not_applicable_allowed` may hold
+ *    `"n/a — <reason>"`; a not-applicable value anywhere else, or one with no reason, is `VALIDATION`
+ *    `not-applicable value on submit: …` naming the field (`dl-124`, task-168, {@link requireRequiredFields}).
  * 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
+ *    `wf(<type>): submit <id>` with no bracket (spec-004 §4.3, `dl-054`) and, when the author's edits
+ *    ride along, one body line `Carries content: …` naming them (`describeSubmitContent`; task-209,
+ *    `dl-106` W1 (a), `spec-008` §2); a pure transition has no body. 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>');
+        throw new usage_error_1.UsageError((0, registry_1.missingOperandReason)('id'));
     }
-    const prepared = (0, memory_transition_1.prepareMemoryTransition)(root, id, 'submit');
+    const prepared = (0, memory_transition_1.beginMemoryTransition)(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 fieldsFilled = (0, required_fields_1.requireRequiredFields)(prepared.value.memoryYaml, type, frontmatter, 'submit');
+    if (!fieldsFilled.ok)
+        return fieldsFilled;
+    // The subject stays plain (`dl-054`, ruling R20); the body declares the content the commit carries
+    // beyond the state move, measured against the document committed at the sha the transition was
+    // decided at (task-209, `dl-106` W1 (a)). A pure transition gets no body line.
     const rendered = (0, memory_1.renderSubmitDocument)(content, to);
+    const committedContent = (0, storage_1.readPathAtRev)(root, prepared.value.sha, path);
+    const described = (0, memory_1.describeSubmitContent)(committedContent, content, to);
+    // `describeSubmitContent` compares line-ending-normalized text; whether the line endings change the
+    // blob is git's answer, after its own filters (`core.autocrlf`, `.gitattributes`; review F1). It is
+    // asked whatever else changed (re-review 1): against the rendered committed copy when nothing else
+    // did, otherwise against this rendering written in the committed document's line endings.
+    let lineEndingsChanged = false;
+    if (committedContent !== null) {
+        const baseline = described.length === 0 ? (0, memory_1.renderSubmitDocument)(committedContent, to) : (0, memory_1.withLineEndingsOf)(rendered, committedContent);
+        lineEndingsChanged = !(0, storage_1.storesAsBlob)(root, path, rendered, baseline);
+    }
+    const carries = lineEndingsChanged ? [...described, memory_1.LINE_ENDINGS_ITEM] : described;
+    const message = (0, memory_1.formatMemoryCommitMessage)({ type, op: 'submit', ids: [id], carries });
     // `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 });
+    return (0, types_1.coreOk)({ id, path, from, to }, { sha: committed.value, message }, prepared.value.warnings);
 };
 /**
  * `memory approve` `CoreOperation.fn` (P1.7, `mutates: true`; spec-006-core-domain-api §3). Approve is
@@ -711,21 +1065,24 @@ 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
- *    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,
+ * 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. Steps 3 and 4 are {@link beginMemoryTransition}
+ *    (task-132, `bug-142`; `spec-006` §7), which reads the identity ONCE: step 6 authorizes it, the
+ *    `Approver:` line names it, and the commit is authored as it (`--author`), so the three can never
+ *    name different principals (`bug-149`).
+ * 4. **{@link prepareMemoryTransition}** — it resolves the `memory.yaml` and the document committed at
+ *    `HEAD` itself (task-091, `dl-080` (B); task-247, `bug-187`); 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`).
+ *    is `(none)`: `approve` reaches nothing from `<from>` (task-181, `bug-165`).
  * 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
+ *    and `findMemoryDocumentByIdAtRev` at `HEAD` 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
@@ -734,29 +1091,40 @@ const memorySubmitFn = async (params) => {
  * 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:` / `Reason:` body (AGENTS.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.
+ * 8. **The `supersedes:` trigger** (task-162, `dl-065` Q1.1; {@link prepareSupersede}). When the target
+ *    is the `waiting` state whose forward edge leads to `superseded` (`adr` `accepted`, `tech-spec`
+ *    `approved`) and the document's committed `supersedes:` names an element, that element is
+ *    resolved at the same `HEAD` sha, and refused (exit `1`) when it is missing, of another type, not
+ *    in that state, or not writable as a status change. This runs after step 6 and before step 7's
+ *    write, and both documents pass `checkMemoryTransition` before either is written, so a refusal
+ *    leaves the repository as it was. The approve commit comes first; then a second commit, scoped
+ *    to the superseded document, `wf(<type>): finalize <A> [<state> → superseded]`, with a `Reason:`
+ *    citing the approve sha and no `Approver:` line (`spec-008` §2). The result reports both; its
+ *    `commit` is the approve's.
  */
 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>');
+        throw new usage_error_1.UsageError((0, registry_1.missingOperandReason)('id'));
     }
     const reason = (0, require_reason_1.requireReason)(options);
-    const prepared = (0, memory_transition_1.prepareMemoryTransition)(root, id, 'approve');
+    const prepared = (0, memory_transition_1.beginMemoryTransition)(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);
+    const authorized = (0, approval_authority_1.requireApprovalAuthority)(root, type, prepared.value.identity);
     if (!authorized.ok)
         return authorized;
-    const { name, email } = (0, git_identity_1.readGitIdentity)(root);
+    const supersede = (0, memory_supersede_1.prepareSupersede)(root, prepared.value);
+    if (!supersede.ok)
+        return supersede;
+    const superseded = supersede.value;
+    const { name, email } = prepared.value.identity;
     const message = (0, memory_1.formatMemoryCommitMessage)({
         type,
         op: 'approve',
@@ -765,24 +1133,89 @@ const memoryApproveFn = async (params) => {
         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);
+    const rendered = (0, memory_1.setFrontmatterField)(content, 'status', to);
+    let renderedSuperseded = '';
+    if (superseded !== null) {
+        // Both documents are checked before either is written, so a refusal of the second leaves the
+        // first unwritten too (task-162). The approved one is checked again by its own commit below.
+        renderedSuperseded = (0, memory_1.setFrontmatterField)(superseded.content, 'status', superseded.to);
+        const checkedApproved = (0, memory_transition_1.checkMemoryTransition)(root, prepared.value, rendered);
+        if (!checkedApproved.ok)
+            return checkedApproved;
+        const checkedSuperseded = (0, memory_transition_1.checkMemoryTransition)(root, superseded, renderedSuperseded);
+        if (!checkedSuperseded.ok) {
+            return (0, types_1.coreErr)({
+                ...checkedSuperseded.error,
+                message: `cannot approve ${id}: its supersedes: field names ${superseded.id}, which cannot be superseded: ${checkedSuperseded.error.message}`,
+            });
+        }
+    }
+    // Both lookups read the same HEAD sha in path order; a file unreadable to both is named once. Known
+    // before the first commit, so a dry run, which stops there, reports them too (task-210 review, F4).
+    const warnings = superseded === null ? prepared.value.warnings : [...new Set([...prepared.value.warnings, ...superseded.warnings])];
+    const committed = (0, memory_transition_1.commitMemoryTransition)(root, prepared.value, rendered, message, {}, 'declared-fields-only', warnings);
     if (!committed.ok)
         return committed;
-    return (0, types_1.coreOk)({ id, path, from, to }, { sha: committed.value, message });
+    if (superseded === null)
+        return (0, types_1.coreOk)({ id, path, from, to }, { sha: committed.value, message }, warnings);
+    const finalizeMessage = (0, memory_1.formatMemoryCommitMessage)({
+        type,
+        op: 'finalize',
+        ids: [superseded.id],
+        transition: { from: superseded.from, to: superseded.to },
+        reason: (0, memory_supersede_1.supersedeReason)(id, committed.value),
+    });
+    let finalized;
+    try {
+        finalized = (0, memory_transition_1.commitMemoryTransition)(root, superseded, renderedSuperseded, finalizeMessage);
+    }
+    catch (error) {
+        // A refused commit is worded from its parts, without the primitive's "the working tree and the index
+        // are as they were": the next statement makes the working tree differ on purpose (task-210 review,
+        // F5). Any other error keeps `String`'s `name: message`.
+        finalized = (0, types_1.coreErr)({ code: 'IO', message: (0, storage_1.commitFailureSummary)(error) });
+        // The commit primitive put the file back when git refused the commit (task-210, `bug-217`); the
+        // recovery below commits the file as it stands, so write the finalized status into it again — the
+        // one write here meant to outlive a failed commit, because the approve has already happened.
+        (0, storage_1.writeDocument)((0, path_1.join)(root, superseded.path), renderedSuperseded);
+    }
+    if (!finalized.ok) {
+        // Reachable only when git itself fails between the two commits (a hook, a full disk): every
+        // refusal was checked above. The approve stays — rewriting a commit behind the user's back is
+        // worse (dl-035) — so say exactly what is left to do.
+        return (0, types_1.coreErr)({
+            ...finalized.error,
+            message: `${id} was approved in ${committed.value}, but the commit moving ${superseded.id} to ${superseded.to} failed: ` +
+                `${finalized.error.message.trim()}. Its status is written in the working tree (${superseded.path}). ` +
+                `Complete the pair by committing that file alone, from the repository root:\n\n` +
+                // `--cleanup=whitespace`, as `commitPaths` passes it (bug-051, task-192 review): under the
+                // operator's `commit.cleanup=strip` a reason line opening with `#` would otherwise be lost.
+                `git commit --only --cleanup=whitespace -F - -- ${superseded.path} <<'EOF'\n${finalizeMessage}\nEOF`,
+        });
+    }
+    return (0, types_1.coreOk)({
+        id,
+        path,
+        from,
+        to,
+        superseded: { id: superseded.id, path: superseded.path, from: superseded.from, to: superseded.to },
+    }, { sha: committed.value, message }, warnings);
 };
 /**
  * `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
+ * `Approver:`/`Reason:` body (`dl-054-submit-commit-subject-bracket`, AGENTS.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,
+ * 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`. Steps 3 and 4 are {@link beginMemoryTransition}
+ *    (task-132, `bug-142`; `spec-006` §7).
+ * 4. **{@link prepareMemoryTransition}** with op `reject`, against the `memory.yaml` and the document
+ *    committed at `HEAD` (task-091, `dl-080` (B); task-247, `bug-187`) — 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
@@ -800,27 +1233,24 @@ const memoryApproveFn = async (params) => {
  *    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.
+ * The `Approver:` identity is the one step 3 resolved — the same value step 5 checked and the commit
+ * is authored as (`--author`, task-132, `bug-149`), 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>');
+        throw new usage_error_1.UsageError((0, registry_1.missingOperandReason)('id'));
     }
     const reason = (0, require_reason_1.requireReason)(options);
-    const prepared = (0, memory_transition_1.prepareMemoryTransition)(root, id, 'reject');
+    const prepared = (0, memory_transition_1.beginMemoryTransition)(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);
+    const authorized = (0, approval_authority_1.requireApprovalAuthority)(root, type, prepared.value.identity);
     if (!authorized.ok)
         return authorized;
-    const { name, email } = (0, git_identity_1.readGitIdentity)(root);
+    const { name, email } = prepared.value.identity;
     const message = (0, memory_1.formatMemoryCommitMessage)({
         type,
         op: 'reject',
@@ -833,7 +1263,7 @@ const memoryRejectFn = async (params) => {
     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 });
+    return (0, types_1.coreOk)({ id, path, from, to, reason }, { sha: committed.value, message }, prepared.value.warnings);
 };
 /**
  * `memory deprecate` `CoreFn` (P1.9, `mutates: true`; spec-006-core-domain-api §3) — the retire verb.
@@ -844,15 +1274,19 @@ const memoryRejectFn = async (params) => {
  * 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.)
+ * edge fired by a later element's `supersedes:` field when that element is approved — see
+ * `SUPERSEDED_STATE` in `src/memory/state-machine.ts`, `./memory-supersede.ts` (task-162) and
+ * task-048's Execution Notes, decision D1. A `superseded` element can still be deprecated.)
  *
  * 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,
+ * 1. **`<id>`** absent or blank → `UsageError` (exit `2`), as `memory submit`/`memory reject`; so is a
+ *    `--reason` that is given but blank, carrying a control character other than tab or newline, or
+ *    trailer-shaped (`optionalReason`). Both precede the identity check (task-125, `bug-172`).
+ * 2. **`requireGitIdentity`** (REQ-SEC-01) — exit `1`. Steps 2 and 3 are {@link beginMemoryTransition}
+ *    (task-132, `bug-142`; `spec-006` §7).
+ * 3. **{@link prepareMemoryTransition}** with op `deprecate`, against the `memory.yaml` and the
+ *    document committed at `HEAD` (task-091, `dl-080` (B); task-247, `bug-187`) — 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.
@@ -876,17 +1310,15 @@ 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>');
+        throw new usage_error_1.UsageError((0, registry_1.missingOperandReason)('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).
+    // trailer — blank, carrying a control character other than tab or newline, or trailer-shaped is a
+    // usage error at exit 2, before anything is read or written (`dl-067` clauses 1 and 4 as amended;
+    // `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');
+    const prepared = (0, memory_transition_1.beginMemoryTransition)(root, id, 'deprecate');
     if (!prepared.ok)
         return prepared;
     const { type, path, from, to, content } = prepared.value;
@@ -898,21 +1330,148 @@ const memoryDeprecateFn = async (params) => {
     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 });
+    return (0, types_1.coreOk)({ id, path, from, to, reason }, { sha: committed.value, message }, prepared.value.warnings);
+};
+/**
+ * `memory park` `CoreOperation.fn` (task-180, `mutates: true`; `dl-110` P1 (a)) — return a started
+ * element to an earlier state along its type's declared `returns` edge (`spec-001`), e.g. a `task` from
+ * `in-progress` back to `backlog`. Returning is not rejecting (`dl-110` Rationale): the commit says the
+ * work is not being done now, not that it was wrong, so `memory history` keeps the two apart. Order,
+ * every refusal before the single write (`spec-006` §7):
+ *
+ * 1. **`<id>`** absent or blank, then **`requireReason`** (`dl-067`) → `UsageError` (exit `2`), before
+ *    the identity is read (task-125, `bug-172`). The reason is mandatory: a park records why.
+ * 2. **{@link beginMemoryTransition}** with op `park` — identity (REQ-SEC-01), then the document and
+ *    its edge at `HEAD` (`dl-080`): a state with no `returns` edge is `INVALID_TRANSITION` with the
+ *    `dl-032` contract message (exit `1`). A WIP limit declared on the target state does not refuse a
+ *    park: a return along a `returns` edge takes no slot check (`dl-156` Q2 (i), task-274).
+ * 3. **Edit + commit** — `status` set to the target and nothing else (`spec-010` field-write ownership,
+ *    enforced by `commitMemoryTransition`'s post-condition), one commit scoped to that file:
+ *    `wf(<type>): park <id> [<from> → <to>]` with a `Reason:` block (`spec-008` §2).
+ *
+ * Deliberately absent: no `Approver:` line and no authority check. A park is a scheduling decision, not
+ * an approval gate; `dl-110` names no approver for it. What parking does to the work around the element
+ * under `dev-loop` (the task's worktree, its bugs' `sync_state`) is `dl-110` P2, owned by the workflow,
+ * not by this verb.
+ */
+const memoryParkFn = async (params) => {
+    const { root, positional: id, options } = params;
+    if (id === undefined || id.trim().length === 0) {
+        throw new usage_error_1.UsageError((0, registry_1.missingOperandReason)('id'));
+    }
+    const reason = (0, require_reason_1.requireReason)(options);
+    const prepared = (0, memory_transition_1.beginMemoryTransition)(root, id, 'park');
+    if (!prepared.ok)
+        return prepared;
+    const { type, path, from, to, content } = prepared.value;
+    const message = (0, memory_1.formatMemoryCommitMessage)({ type, op: 'park', 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 }, prepared.value.warnings);
+};
+/**
+ * `memory amend` `CoreOperation.fn` (task-127, `mutates: true`; `dl-108` A1 (a), A2 (i), A3). It
+ * records the author's uncommitted edit of one document as an amendment: one commit, that file only,
+ * `status` untouched, under an approver's name. It is the verb for a correction to an element no
+ * transition verb can move (an `approved` tech-spec, a `ready` decision-log). Order, every refusal
+ * before the single write:
+ *
+ * 1. **`<id>`** absent or blank, then **`requireReason`** (`dl-067`) → `UsageError` (exit `2`), before
+ *    anything is read. Both precede the identity check (task-125, `bug-172`), as on `approve`.
+ * 2. **`requireGitIdentity`** (REQ-SEC-01) — exit `1`. Step 2 and the lookup in step 3 are
+ *    {@link beginMemoryTransition} (task-132, `bug-142`; `spec-006` §7); the identity it returns is
+ *    the one step 4 authorizes, the `Approver:` line names and the commit is authored as.
+ * 3. **{@link prepareMemoryTransition}** with op `amend` — the document located at `HEAD`, its type and
+ *    state resolved against the `memory.yaml` committed there (`dl-080` (B); task-247, `bug-187`), its
+ *    content taken from the working tree; its target is its own
+ *    state, so no illegal-transition refusal exists for this verb. Then
+ *    {@link requireConfinedWriteTarget} (REQ-SEC-06): a document outside the project, or one that is
+ *    itself a symbolic link, is refused before any question about its content.
+ * 4. **{@link requireApprovalAuthority}** (REQ-SEC-03, `dl-108` A2 (i)) — the same check and message
+ *    as `approve`, from the committed `dna.yaml`; exit `1`. It runs as soon as the type is known
+ *    (step 3), the same place `approve` runs it, so a caller without authority learns nothing about
+ *    the edit (task-127 review F6).
+ * 5. **{@link requireAmendableType}** — the committed entry must declare `amendable: true`
+ *    (`dl-108` A3, `spec-001`); exit `1`.
+ *    Then **{@link requireReadableScaffold}**: the type's scaffold committed at `HEAD`, which step 6
+ *    reads, must be one `memory add` would read — a newer or malformed `format` is refused with
+ *    `memory add`'s message (`dl-149`; task-257, `bug-243`); exit `1`.
+ * 6. **{@link requireAmendableEdit}** — the document must be committed at `HEAD`, carry a change, and
+ *    leave every field the type's {@link amendReservedFields} lists as committed (`spec-010` §
+ *    Field-write ownership: `release` only where the committed scaffold declares it, task-170);
+ *    exit `1`, naming the field. Then {@link requireRequiredFieldsKept}: past the initial
+ *    state, `title` and the type's required fields must stay non-empty (`spec-010` § Validation
+ *    rules); exit `1`, naming the field.
+ * 7. **Commit** — {@link commitMemoryTransition} under `carries-content`, the scope `memory submit`
+ *    uses: the working-tree bytes are the content of record, so they are written back unchanged and
+ *    committed as that one path. `commitPaths` stages only that path, so other modified or staged
+ *    files stay where they are (`bug-027`); the post-condition checks that the commit holds only that
+ *    path and that `status` is the unchanged state (`bug-076`). Subject
+ *    `wf(<type>): amend <id> [<s> → <s>]` with the `Approver:` / `Reason:` body (`spec-008` §2).
+ */
+const memoryAmendFn = async (params) => {
+    const { root, positional: id, options } = params;
+    if (id === undefined || id.trim().length === 0) {
+        throw new usage_error_1.UsageError((0, registry_1.missingOperandReason)('id'));
+    }
+    const reason = (0, require_reason_1.requireReason)(options);
+    const prepared = (0, memory_transition_1.beginMemoryTransition)(root, id, 'amend');
+    if (!prepared.ok)
+        return prepared;
+    const { memoryYaml, type, path, content, frontmatter, from, to } = prepared.value;
+    // Before any question about the edit: is this file the project's to write at all (REQ-SEC-06,
+    // `bug-117`/`bug-120`)? The other verbs ask it first inside `commitMemoryTransition`; `amend` asks
+    // it here too, because its own checks read the document against `HEAD`, and a symlinked document
+    // would otherwise be refused for a field change it never made.
+    const confined = (0, confinement_1.requireConfinedWriteTarget)(root, path, 'write');
+    if (!confined.ok)
+        return confined;
+    const authorized = (0, approval_authority_1.requireApprovalAuthority)(root, type, prepared.value.identity);
+    if (!authorized.ok)
+        return authorized;
+    const amendable = (0, memory_amend_1.requireAmendableType)(memoryYaml, type);
+    if (!amendable.ok)
+        return amendable;
+    const scaffold = (0, memory_amend_1.requireReadableScaffold)(root, memoryYaml, type);
+    if (!scaffold.ok)
+        return scaffold;
+    const edit = (0, memory_amend_1.requireAmendableEdit)(root, id, path, content, (0, memory_amend_1.amendReservedFields)(root, memoryYaml, type));
+    if (!edit.ok)
+        return edit;
+    const filled = (0, memory_amend_1.requireRequiredFieldsKept)(memoryYaml, type, from, frontmatter);
+    if (!filled.ok)
+        return filled;
+    const { name, email } = prepared.value.identity;
+    const message = (0, memory_1.formatMemoryCommitMessage)({
+        type,
+        op: 'amend',
+        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, content, message, {}, 'carries-content');
+    if (!committed.ok)
+        return committed;
+    return (0, types_1.coreOk)({ id, path, from, to }, { sha: committed.value, message }, prepared.value.warnings);
 };
 /**
  * `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**,
+ * 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,19 +1487,25 @@ 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.
     const relativePath = `.wingfoil/directives/custom/${name}.md`;
     const absolutePath = (0, path_1.join)(root, relativePath);
+    // REQ-SEC-06 / bug-121 (task-172): a DANGLING link at the path reads as free to `documentExists`
+    // (`existsSync` follows it), and `writeDocument` would create the file wherever it points. Refused
+    // before the existence check, so a path that leaves the project is reported as leaving it.
+    const confined = (0, confinement_1.requireConfinedWriteTarget)(root, relativePath, 'write');
+    if (!confined.ok)
+        return confined;
     if ((0, storage_1.documentExists)(absolutePath)) {
         return (0, types_1.coreErr)({ code: 'CONFLICT', message: `directive already exists: ${name}` });
     }
@@ -951,9 +1516,8 @@ const directiveCreateFn = async (params) => {
     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 sha = (0, storage_1.writeAndCommit)(root, [{ path: relativePath, content }], message);
     const leaked = (0, write_guard_1.committedScopeError)(root, sha, relativePath, content);
     if (leaked)
         return leaked;
@@ -966,11 +1530,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
@@ -984,13 +1548,12 @@ const directiveCreateFn = async (params) => {
  *    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.
+ *    idempotent"); a partially overlapping one appends only what is missing. A file the in-place
+ *    editor cannot edit is refused (`CONFLICT`, exit 1) unless `--force` authorizes the whole-file
+ *    rewrite, whose success then carries a warning the CLI prints on stderr (task-169, `dl-062`).
  */
 const directiveAssignFn = async (params) => {
-    const { root, options } = params;
-    const identity = (0, git_identity_1.requireGitIdentity)(root);
-    if (!identity.ok)
-        return identity;
+    const { root, options, force } = params;
     const directive = options?.directive;
     if (directive === undefined)
         throw new usage_error_1.UsageError('missing required argument: --directive');
@@ -1000,14 +1563,19 @@ 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);
     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);
+    const updated = (0, directive_assign_1.updateRoleAssignments)(root, role, (current) => (0, roles_edit_1.withAssignedDirectives)(current, directives), message, {
+        force: force === true,
+    });
     if (!updated.ok)
         return updated;
-    return (0, types_1.coreOk)({ directives, role, assignments: updated.value.assignments }, updated.commit);
+    return (0, types_1.coreOk)({ directives, role, assignments: updated.value.assignments }, updated.commit, updated.warnings);
 };
 /**
  * `directive remove` `CoreOperation.fn` (P3.3, `mutates: true`; spec-006 §3 row `directiveRemove`,
@@ -1017,9 +1585,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**
- *    (`missing required argument: directive remove <name>`, the `memory submit <id>` precedent).
+ * 1. `<name>` presence — a missing or blank positional is a `UsageError` → exit **2**
+ *    (`missing required argument: <name>`, the one missing-operand wording, task-179).
+ * 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,18 +1635,26 @@ const directiveAssignFn = async (params) => {
  */
 const directiveRemoveFn = async (params) => {
     const { root, positional: name } = params;
+    if (name === undefined || name.trim().length === 0) {
+        throw new usage_error_1.UsageError((0, registry_1.missingOperandReason)('name'));
+    }
     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);
+    const inventory = loadOrError(() => (0, loaders_1.loadDirectiveInventory)(root));
+    if (!inventory.ok)
+        return inventory;
+    const target = (0, context_1.selectDirectivesById)(inventory.value.files, new Set([name])).byId.get(name);
     if (target === undefined) {
-        return (0, types_1.coreErr)({ code: 'NOT_FOUND', message: `unknown directive: ${name}` });
+        // task-143: the entry asked for may be one the loader skipped (a dangling link, an unreadable
+        // file), so its warnings ride this refusal's `details` — the channel both surfaces render
+        // (task-130) — rather than a stderr line from core, which `--format json` cannot carry.
+        const { warnings } = inventory.value;
+        return (0, types_1.coreErr)({
+            code: 'NOT_FOUND',
+            message: `unknown directive: ${name}`,
+            ...(warnings.length > 0 ? { details: { issues: warnings.map((detail) => ({ detail })) } } : {}),
+        });
     }
     const custom = (0, builtin_asset_1.requireCustomAsset)('directive', target.path);
     if (!custom.ok)
@@ -1105,9 +1681,8 @@ const directiveRemoveFn = async (params) => {
     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 sha = (0, storage_1.writeAndCommit)(root, [{ path: relativePath, content: null }], message);
     const leaked = (0, write_guard_1.committedScopeError)(root, sha, relativePath, null);
     if (leaked)
         return leaked;
@@ -1126,8 +1701,86 @@ const directiveRemoveFn = async (params) => {
  */
 const directivesListFn = async (params) => {
     const { root, options } = params;
+    // task-143 (bug-154): with no `.wingfoil/` the loaders read nothing and the listing came back empty,
+    // exit 0 — under `--role`, with a "no directives assigned" warning nothing was read to establish.
+    const initialized = (0, init_1.requireInitializedProject)(root);
+    if (!initialized.ok)
+        return initialized;
     return loadOrError(() => (0, directives_list_1.loadDirectiveListing)(root, options?.role));
 };
+/** `workflowList` `CoreOperation.fn` (P4.6, `spec-017` §7.5): {@link workflowListAtHead}, refusals mapped. */
+const workflowListFn = async (params) => {
+    const { root, all } = params;
+    return loadOrError(() => (0, workflow_list_show_1.workflowListAtHead)(root, all === true));
+};
+/**
+ * `workflowShow` `CoreOperation.fn` (P4.7, `spec-017` §7.6): {@link workflowShowAtHead}, refusals mapped; a
+ * missing `<ref>` is the one missing-operand usage error (exit `2`) for a caller that bypasses the registrar.
+ */
+const workflowShowFn = async (params) => {
+    const { root, positional } = params;
+    if (positional === undefined)
+        throw new usage_error_1.UsageError((0, registry_1.missingOperandReason)('ref'));
+    const result = loadOrError(() => (0, workflow_list_show_1.workflowShowAtHead)(root, positional));
+    return result.ok ? result.value : result;
+};
+/**
+ * `workflowNext` `CoreOperation.fn` (P4.4, `spec-017` §7.3): {@link workflowNextAtHead}, refusals mapped — a
+ * `spec-003` error at `HEAD` is `VALIDATION` (exit 1), a `<ref>` naming no open instance `NOT_FOUND` (exit 1);
+ * every deduced outcome exits 0.
+ */
+const workflowNextFn = async (params) => {
+    const { root, positional, options } = params;
+    const result = loadOrError(() => (0, workflow_next_1.workflowNextAtHead)(root, positional, options?.['assigned-to']));
+    return result.ok ? result.value : result;
+};
+/**
+ * `workflowFinalize` `CoreOperation.fn` (`spec-017` §7.9, ruling R11): {@link workflowFinalizeAtHead}, its
+ * refusals returned (`CONFLICT`, `NOT_FOUND`, `VALIDATION`: exit 1) or thrown as a `UsageError` (an
+ * unrecordable or missing `--reason`: exit 2); a `spec-003` error at `HEAD` is `VALIDATION`, exit 1.
+ */
+const workflowFinalizeFn = async (params) => {
+    const { root, positional, options } = params;
+    const step = options?.['step'];
+    const result = loadOrError(() => (0, workflow_finalize_1.workflowFinalizeAtHead)(root, { ...(positional === undefined ? {} : { ref: positional }), ...(step === undefined ? {} : { step }), ...(options === undefined ? {} : { options }) }));
+    return result.ok ? result.value : result;
+};
+/**
+ * `workflowStart` / `workflowEnd` `CoreOperation.fn`s (P4.2, P4.3; `spec-017` §7.1–§7.2; task-217): the two
+ * operations of `./workflow-start-end`, with `start` writing through this registry's own `memoryAdd` and
+ * `memorySubmit`. A `spec-003` error at `HEAD` (or a token value outside the id class) is `VALIDATION`,
+ * exit 1, as every workflow operation maps it ({@link coreErrorOf}).
+ */
+async function refusalOf(run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        const refusal = coreErrorOf(error);
+        if (refusal === null)
+            throw error;
+        return (0, types_1.coreErr)(refusal);
+    }
+}
+const workflowStartFn = (params) => refusalOf(() => (0, workflow_start_end_1.workflowStart)(params, { add: memoryAddFn, submit: memorySubmitFn }));
+const workflowEndFn = (params) => refusalOf(() => (0, workflow_start_end_1.workflowEnd)(params));
+/**
+ * `workflowCreate` / `workflowRemove` `CoreOperation.fn`s (P4.8, P4.9; `spec-017` §7.7–§7.8; task-211): the two
+ * operations of `./workflow-create-remove`. A `spec-003` error at `HEAD` is `VALIDATION`, exit 1
+ * ({@link coreErrorOf}); the argument errors are thrown `UsageError`s (exit 2).
+ */
+const workflowCreateFn = (params) => refusalOf(() => (0, workflow_create_remove_1.workflowCreate)(params));
+const workflowRemoveFn = (params) => refusalOf(() => (0, workflow_create_remove_1.workflowRemove)(params));
+/**
+ * `workflowStatus` `CoreOperation.fn` (P4.5, `spec-017` §7.4): {@link workflowStatusAtHead}, refusals mapped — a
+ * `spec-003` error at `HEAD` is `VALIDATION` (exit 1), a `<ref>` naming no open instance `NOT_FOUND` (exit 1);
+ * every deduced outcome exits 0, a routing error included (BDD P4.14 sc. 3).
+ */
+const workflowStatusFn = async (params) => {
+    const { root, positional } = params;
+    const result = loadOrError(() => (0, workflow_status_1.workflowStatusAtHead)(root, positional));
+    return result.ok ? result.value : result;
+};
 /**
  * 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
@@ -1156,30 +1809,141 @@ const directivesListFn = async (params) => {
  * Tool, or the diff fails.
  */
 exports.CORE_MODULES = [
+    // task-177 (`spec-016` §1): the `agent` module, registered under the name its operations carry
+    // (`agentExecute`, `agentList`, `agentShow`, spec-016 §8). `agentShow` is the first (task-220);
+    // `agentExecute` follows (task-218 the pre-launch half, task-228 the launch), and `agentList`
+    // (task-240) completes the v0.3 set. `src/agent` holds the adapter manifest, the run log and the pipeline.
+    {
+        name: 'agent',
+        description: 'launch an agent on an element, and read recorded agent runs',
+        operations: {
+            // task-218 (`spec-016` §3): `mutates: true` — its one write is the run record's commit (§4.4,
+            // task-228), so it takes `--dry-run`, which prints the launch plan. CLI only in v0.3: the
+            // production server does not run `registerCoreModules`, and the `agent.execute` Tool is v0.4
+            // (spec-016 §7, §8). Reads `HEAD` (spec-008 §11).
+            agentExecute: {
+                name: 'agentExecute',
+                mutates: true,
+                description: 'launch an agent CLI through its adapter on one Memory element, with its context assembled and checked first',
+                // task-235 (spec-016 §3.1, ruling R16): the step forms. `--workflow` and `--step` imply `--next`.
+                flags: [{ name: 'next', description: "take the workflow, phase, element and role from the active workflow's next step" }],
+                options: [
+                    { name: 'workflow', valueName: 'ref', description: 'take the step from this workflow (its most recent open instance) or open instance id; implies --next' },
+                    { name: 'step', valueName: 'key', description: 'take this step of the frontier, e.g. dev-loop.red@task:task-042-login-form; implies --next' },
+                    { name: 'element', valueName: 'type:id', description: "the element the agent works on, e.g. task:task-042-login-form; with a step, it overrides the step's element" },
+                    { name: 'role', valueName: 'role', description: "the role the agent runs as, a dna.yaml team.roles name (default: the step's role; with no step, developer, with a warning)" },
+                    { name: 'agent', valueName: 'name', description: 'the team.agents entry to launch (default: the first with an adapter that executes the role)' },
+                ],
+                example: 'wingfoil agent execute --next',
+                fn: agent_execute_1.agentExecuteFn,
+                // spec-016 §3.4 (task-228): the agent owns stdout, so the recorded run is reported on stderr.
+                renderToStderr: agent_execute_1.renderAgentExecuteStderr,
+            },
+            // task-240 (`spec-016` §5): read-only, and a declared `HEAD` read (§5.1, `spec-006` §6 item 6): the
+            // run log and the workflow deduction at one commit. Its console rendering is §5's sections
+            // (`renderConsole`); each diagnostic is also a success warning, the console's `warning:` line.
+            // `--active` is v0.4 and not declared, so it is refused as an unknown option (exit 2). CLI only
+            // in v0.3 (spec-016 §7, §8).
+            agentList: {
+                name: 'agentList',
+                mutates: false,
+                description: 'list the recorded agent runs and the workflow steps waiting for an agent, as committed at HEAD',
+                flags: [
+                    { name: 'past', description: 'list the recorded runs (the run log at HEAD); without --past or --waiting, both sections' },
+                    { name: 'waiting', description: "list the open workflows' ready steps whose role an agent executes; without --past or --waiting, both sections" },
+                ],
+                options: [
+                    { name: 'element', valueName: 'type:id', description: 'keep the runs and steps of this element, e.g. task:task-042-login-form' },
+                    { name: 'phase', valueName: 'name', description: 'keep the runs and steps of this workflow phase, e.g. red' },
+                ],
+                example: 'wingfoil agent list --past --element task:task-042-login-form',
+                fn: agent_list_1.agentListFn,
+                renderConsole: agent_list_1.renderAgentListConsole,
+            },
+            // task-220 (`spec-016` §6): read-only, and a declared `HEAD` read (§5.1, `spec-006` §6 item 6).
+            // Its console rendering is the `key: value` lines §6 defines, not the indented JSON every other
+            // command prints until P5.1.4 (`renderConsole`, spec-008 §2). Not served over MCP before v0.4
+            // (spec-016 §7): the production server does not run `registerCoreModules`.
+            agentShow: {
+                name: 'agentShow',
+                mutates: false,
+                description: 'print one recorded agent run and the commit that added it',
+                positional: { name: 'run-id', required: true, description: 'the run id, <element-id>/<phase>/<n>' },
+                example: 'wingfoil agent show task-042-login-form/red/1',
+                fn: agent_show_1.agentShowFn,
+                renderConsole: agent_show_1.renderAgentShowConsole,
+            },
+        },
+    },
     {
         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', surplusHint: DNA_SURPLUS_HINT },
+                options: [DNA_VALUE_OPTION, ...DNA_ENTRY_OPTIONS],
+                example: 'wingfoil dna add team.members --value "Ada Lovelace" --entry-email ada@example.com --entry-roles approver',
+                flags: [DNA_FORCE_FLAG],
+                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', surplusHint: DNA_SURPLUS_HINT },
+                options: [DNA_VALUE_OPTION],
+                example: 'wingfoil dna remove paths.docs --value README.md',
+                flags: [DNA_FORCE_FLAG],
+                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)', surplusHint: DNA_SURPLUS_HINT },
+                options: [DNA_SET_VALUE_OPTION],
+                example: 'wingfoil dna set project.name --value "My Project"',
+                flags: [DNA_FORCE_FLAG],
+                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', surplusHint: DNA_SURPLUS_HINT },
+                options: [DNA_VALUE_OPTION, ...DNA_ENTRY_OPTIONS],
+                example: 'wingfoil dna update modules.api --entry-description "Public HTTP API"',
+                flags: [DNA_FORCE_FLAG],
+                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 +1954,48 @@ exports.CORE_MODULES = [
             memoryAdd: {
                 name: 'memoryAdd',
                 mutates: true,
+                description: "create a document in its type's initial state (the first state of its sequence; draft by default) 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)',
+                    },
+                    // task-227 (`spec-017` §7.10, ruling R16; `spec-008` §12): link the added element to a workflow step,
+                    // through the `WingFoil-Instance` / `WingFoil-Step` trailers of the add commit (§4.8).
+                    {
+                        name: 'workflow',
+                        valueName: 'ref',
+                        description: 'link the document to a step of this open workflow instance (an instance id, or a workflow name)',
+                    },
+                    {
+                        name: 'step',
+                        valueName: 'key',
+                        description: 'the frontier step to link to, when several of the instance add this type (needs --workflow)',
+                    },
                 ],
+                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 +2005,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 +2032,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 +2046,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 +2060,57 @@ 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,
             },
+            // task-180 (`dl-110` P1 (a)) — `mutates: true`: CLI `wingfoil memory park <id> --reason <text>` + MCP
+            // Tool `memory.park`.
+            // `--reason` is `required` (metadata; `memoryParkFn` enforces it via `requireReason`). The id
+            // rides the bare `positional` seam (spec-008 §7).
+            memoryPark: {
+                name: 'memoryPark',
+                mutates: true,
+                description: "return a started document to an earlier state along its type's declared returns edge (for a task, in-progress → backlog)",
+                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 the work stops for now, recorded as the commit's Reason:" }],
+                example: 'wingfoil memory park task-001-my-first-task --reason "Blocked on the schema decision; back to the backlog."',
+                fn: memoryParkFn,
+            },
+            // task-127 (`dl-108`) — `mutates: true`: CLI `wingfoil memory amend <id> --reason <text>` + MCP
+            // Tool `memory.amend`. Approver-gated like `memoryApprove`, so `--reason` is `required`
+            // (metadata; `memoryAmendFn` enforces it via `requireReason`). The id rides the bare
+            // `positional` seam (spec-008 §7), which also gives it task-129's surplus-operand refusal.
+            memoryAmend: {
+                name: 'memoryAmend',
+                mutates: true,
+                description: 'record an uncommitted correction to a document as an amendment, leaving its state unchanged',
+                positional: { name: 'id', required: true, description: 'the document id, e.g. spec-001-storage-layout' },
+                options: [
+                    {
+                        name: 'reason',
+                        required: true,
+                        valueName: 'text',
+                        description: "why the document is corrected, recorded as the commit's Reason:; needs the approver role",
+                    },
+                ],
+                example: 'wingfoil memory amend spec-001-storage-layout --reason "Later measurements corrected the §2 figures."',
+                fn: memoryAmendFn,
+            },
         },
     },
     {
         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,17 +2120,152 @@ 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, governance, runs or health (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: 'start and end workflows, read, create and remove the workflows the project declares, and record the steps nothing else completes (no step is executed yet)',
         operations: {
+            // task-204 (`spec-017` §7.5–§7.6, §8): both read `HEAD`, a declared exception (§1.1, ruling R15;
+            // `spec-006` §6 item 6), from the snapshot and deduction `workflow next` / `status` answer from. A
+            // `spec-003` error at `HEAD` (loader or core check, task-194) is `VALIDATION`, exit 1, with every
+            // diagnostic in `details`; warnings ride the payload's `diagnostics`. The MCP Resources
+            // `wingfoil://workflows…` are not these operations and keep the working tree (spec-017 §9).
             workflowList: {
                 name: 'workflowList',
                 mutates: false,
-                fn: wrapReadOnly(loaders_1.loadWorkflowsYaml),
+                description: 'list the workflows you can run now, as committed at HEAD',
+                flags: [{ name: 'all', description: 'list every workflow, the includable ones no open workflow has reached as well' }],
+                example: 'wingfoil workflow list --all',
+                fn: workflowListFn,
+            },
+            // task-216 (`spec-017` §7.3): reads `HEAD`, gating (§1.1 item 1): its first step is what `agent execute
+            // --next` launches on. Exit 0 for every deduced outcome; 1 for a `spec-003` error or an unknown `<ref>`.
+            // Console: the step's key, trail, role, scope, actions with bindings, directive ids and any "human
+            // needed" line (§8). The MCP Resource `wingfoil://workflows/-/next` serves the same payload (task-239,
+            // `src/mcp/workflow-resource.ts`).
+            workflowNext: {
+                name: 'workflowNext',
+                mutates: false,
+                description: 'print the next step of an open workflow: its verb, role, element, directives and bindings, as committed at HEAD',
+                positional: { name: 'ref', description: 'a workflow name or an open workflow instance id (default: the active instance)' },
+                options: [{ name: 'assigned-to', valueName: 'who', description: "keep the steps whose role 'me', a member name or email, or a role name holds" }],
+                example: 'wingfoil workflow next --assigned-to me',
+                fn: workflowNextFn,
+                renderConsole: workflow_next_1.renderNextConsole,
+            },
+            // task-217 (`spec-017` §7.1–§7.2): both decide at `HEAD` (§1.1 item 1, gating). `start` records the
+            // instance as a `plan` element in two commits (`wf(plan): add`, `wf(plan): submit`); `end` closes it
+            // with `wf(plan): finalize <id> [active → done]`. The MCP Tools `workflow.start` / `workflow.end` are
+            // v0.4 (P5.2.3); the production server serves no Tool.
+            workflowStart: {
+                name: 'workflowStart',
+                mutates: true,
+                description: 'start a workflow: record it as an active plan element and print its first step',
+                positional: { name: 'name', required: true, description: 'the startable workflow to start' },
+                options: [
+                    { name: 'element', valueName: 'type:id', description: 'the element the workflow runs on, when it declares one (default: the active workflow\'s element of that type)' },
+                    { name: 'title', valueName: 'title', description: "the plan's title (default: '<workflow> — <phase>')" },
+                    {
+                        name: 'set',
+                        repeatable: true,
+                        valueName: 'name=value',
+                        description: "override a derived plan token: phase=<v> (default: the element's id, else 1) or scope=<v> (default: the workflow name)",
+                    },
+                ],
+                example: 'wingfoil workflow start release-cycle --element release:minor-v1',
+                fn: workflowStartFn,
+                renderConsole: workflow_start_end_1.renderStartConsole,
+            },
+            workflowEnd: {
+                name: 'workflowEnd',
+                mutates: true,
+                description: 'end a complete workflow: move its plan element to done; the previous open workflow becomes active',
+                positional: { name: 'ref', description: 'a workflow name or an open workflow instance id (default: the active instance)' },
+                example: 'wingfoil workflow end',
+                fn: workflowEndFn,
+                renderConsole: workflow_start_end_1.renderEndConsole,
+            },
+            // task-226 (`spec-017` §7.9, ruling R11): records a checkpoint, an `awaits` or an approval no element
+            // carries as one commit with no file change, `workflow: finalize <instance> <key>`, carrying the
+            // phase-record trailers. Gates on the deduction and `dna.yaml` at `HEAD` (§11). The MCP Tool
+            // `workflow.finalize` is v0.4 (P5.2.3): the production server serves no Tool (§9).
+            workflowFinalize: {
+                name: 'workflowFinalize',
+                mutates: true,
+                description: 'record that a step of an open workflow is complete, as an empty commit with the phase-record trailers',
+                positional: { name: 'ref', description: 'a workflow name or an open workflow instance id (default: the active instance)' },
+                options: [
+                    { name: 'step', valueName: 'key', description: 'the frontier step to record, by its key (default: the next step)' },
+                    { name: 'reason', valueName: 'text', description: 'why; required on a phase that declares approval:, recorded with an Approver: line' },
+                ],
+                example: 'wingfoil workflow finalize --step dev-loop.red@task:task-130',
+                fn: workflowFinalizeFn,
+                renderConsole: workflow_finalize_1.renderFinalizeConsole,
+            },
+            // task-225 (`spec-017` §7.4, §5.1–§5.4): reads `HEAD`, declared (§1.1, ruling R15), from the deduction `next`
+            // answers from. Every open instance with its phases, frontier and late elements, the pending approvals routed
+            // to `dna.yaml` members, and the ungated elements; the console view's "human needed" lines are the v0.3
+            // notification channel (§5.3). The MCP Resource `wingfoil://workflows/-/status` serves the same payload
+            // (task-239, `src/mcp/workflow-resource.ts`).
+            workflowStatus: {
+                name: 'workflowStatus',
+                mutates: false,
+                description: 'print every open workflow, its pending approvals and who they are routed to, and the elements waiting at a gate, as committed at HEAD',
+                positional: { name: 'ref', description: 'a workflow name or an open workflow instance id (default: every open instance)' },
+                example: 'wingfoil workflow status',
+                fn: workflowStatusFn,
+                renderConsole: workflow_status_1.renderStatusConsole,
+            },
+            workflowShow: {
+                name: 'workflowShow',
+                mutates: false,
+                description: 'print one workflow resolved, its included workflows nested under their phases, as committed at HEAD',
+                positional: { name: 'ref', required: true, description: 'a workflow name, or the id of an open workflow instance' },
+                example: 'wingfoil workflow show release-cycle',
+                fn: workflowShowFn,
+            },
+            // task-211 (`spec-017` §7.7–§7.8, REQ-SEC-07): both decide at `HEAD` (§11) and write one commit with the
+            // workflow file and `workflows.yaml` (`wf(workflow): create|remove <name>`), after loading the registry the
+            // commit would leave. `create`'s one filesystem read is its target's existence (`dl-086`); `remove` refuses
+            // a built-in, a workflow another one includes (`dl-030`; the referrer source is `include:` alone, `dl-066`
+            // option 1) and one with an open instance. The MCP Tools `workflow.create` / `workflow.remove` are v0.4.
+            workflowCreate: {
+                name: 'workflowCreate',
+                mutates: true,
+                description: 'create a custom workflow file with one phase and include it in workflows.yaml',
+                positional: { name: 'name', required: true, description: 'the new workflow, written to .wingfoil/workflows/custom/<name>.yaml' },
+                options: [
+                    { name: 'kind', valueName: 'main|sub', description: 'main: startable; sub: includable (or declare --startable / --includable instead)' },
+                    { name: 'element', valueName: 'type', description: 'the Memory type the workflow runs on' },
+                    { name: 'description', valueName: 'text', description: "the workflow's description" },
+                ],
+                flags: [
+                    { name: 'startable', description: 'the workflow can be started on its own (instead of --kind)' },
+                    { name: 'includable', description: "a phase can include the workflow (instead of --kind)" },
+                ],
+                example: 'wingfoil workflow create arch-review --kind main',
+                fn: workflowCreateFn,
+                renderConsole: workflow_create_remove_1.renderCreateConsole,
+            },
+            workflowRemove: {
+                name: 'workflowRemove',
+                mutates: true,
+                description: 'delete a custom workflow and its workflows.yaml entry, unless another workflow includes it or an open workflow runs it',
+                positional: { name: 'ref', required: true, description: 'a workflow name, or the id of an open workflow instance (built-in workflows cannot be removed)' },
+                example: 'wingfoil workflow remove arch-review',
+                fn: workflowRemoveFn,
+                renderConsole: workflow_create_remove_1.renderRemoveConsole,
             },
         },
     },
@@ -1296,6 +2284,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 +2294,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 +2304,15 @@ 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' },
                 ],
+                // task-169 (`dl-062` Q1 option 3): the opt-in to the whole-file rewrite the in-place editor
+                // would otherwise refuse. A per-command flag, documented in spec-008 §12, not §2.
+                flags: [{ name: 'force', description: 'rewrite the whole roles.yaml when it cannot be edited in place (comments and formatting are not kept)' }],
+                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 +2320,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,
+            },
         },
     },
 ];