ai-delivery-workflow 0.3.0 → 0.5.0

package/skills/ai-delivery-orchestrate/SKILL.md

@@ -11,6 +11,20 @@ Coordinate state and handoffs. Do not produce specialist product, architecture,
 
 Read `.workflow/config/workspace.yaml` before any Git or source operation. The workspace root is the workflow repository; the configured direct child is the only code repository. Workflow facts, approvals, manifests, and checkpoints are committed in the workflow repository. Source, tests, code branches, code Tags, and application commits exist only in the code repository. Every code reference in a workflow artifact must carry `repo_id`, `code_commit`, optional `code_tag`, `source_path`, and SHA-256.
 
+## Code Intelligence
+
+For source discovery and change-impact analysis, resolve `code_repository.path` from the authoritative workspace configuration. Prefer `codegraph_explore` with the absolute code repository as `projectPath`; when MCP is unavailable but the indexed CLI is ready, use `codegraph explore "<query>" --path <code-repository>`. When CodeGraph is unavailable, uninitialized, unsupported, or fails, fall back to Semble, then `rg` and direct source reads. Treat `codegraph affected` as test recommendations only; it never narrows required tests or a formal Gate. Keep CodeGraph indexes local and outside formal state, artifacts, events, checkpoints, manifests, and archives.
+
+## Mock System
+
+Use the standalone project Microcks Mock System when a Prototype or UI Acceptance scope needs protocol exchanges. Run `ai-delivery mock setup <workspace>` and `ai-delivery mock start <workspace>`, and register every entry with explicit External Dependency Mock or Product Backend Mock kind, owner, approved contract, replacement condition, operation/channel, and stable scenario identity in its isolated catalog. Review `ai-delivery mock sync <workspace> --dry-run`; that dry-run must validate every named scenario and dispatcher input before `ai-delivery mock sync <workspace>` may run. Export each actual managed UI OpenAPI/AsyncAPI definition into `mock-admin-exports/`, bind its kind, Mock ID, protocol, relative path, and SHA-256 in `mock-admin-export.yaml`, and require freeze to protocol-validate every mapped scenario against those bytes. Prohibit production traffic recording/credentials/unsanitized personal data, require sanitization evidence for explicit imports, and map every active Review Scene exactly once. Run `ai-delivery mock freeze ... --dry-run`, obtain explicit human confirmation of the candidate checksum, freeze, and formally register the exact immutable Mock Scenario Pack before treating it as authoritative. A Product Backend Mock may drive UI scenes, but the real backend is not proven and end-to-end acceptance is not satisfied by mock success. Runtime databases, logs, traffic, and port state are disposable and never enter formal state.
+
+## Prototype-First Frontend Guard
+
+For any production frontend change, keep the sequence fixed: update the isolated Prototype, obtain the user's Page approval through Workflow Manager P12/P13, freeze the revision with checksummed `frontend-change-scope.yaml` and UI Mapping, then modify production code. Require `ai-delivery frontend-guard check-file` immediately before each UI path is written. Before merge, Candidate Assurance, or another formal handoff, require `ai-delivery frontend-guard verify-diff` from a fixed base to candidate head so an independent Git diff rechecks the revision, receipts, and mapping without trusting the local Hook. A business-logic reason to add or remove a Page returns to experience design and user confirmation first; there is no emergency, copy-only, style-only, accessibility, responsive, or defect-fix exception.
+
+Inside `05-candidate-assurance`, every UI-bearing immutable candidate runs `ai-delivery ui-acceptance plan` and `verify` against its pinned Prototype revision, current Page receipts, UI Mapping, Scenario Pack, approved test strategy, and exact Playwright environment. UI Acceptance is part of Candidate Assurance, not a new formal node. Reject incomplete Scene/viewport coverage, visual ratios above policy, interaction/accessibility/responsive/recovery/protocol failures, stale bindings, or Product Backend Mock presented as real backend evidence. A candidate checksum change always returns to `04-implementation` and starts a new assurance attempt.
+
 ## Artifact Location
 
 Require every workflow document to be written under project `.workflow/`. Use `.workflow/delivery/` for workflow control, `.workflow/standards/` for standards, `.workflow/product/`, `.workflow/architecture/`, and `.workflow/experience/` for reusable baselines, and `.workflow/iterations/<iteration-id>/<node-id>/` for version-scoped node outputs. Keep source code, automated test source, repository configuration, and non-document build artifacts in their native locations.
@@ -18,22 +32,28 @@ Require every workflow document to be written under project `.workflow/`. Use `.
 ## Task State
 
 1. Invoke `$ai-delivery-bootstrap` in read-only inspect mode when the current session has not classified project state. Do this before checkpoint recovery because an empty or partially initialized project may not have a valid runtime store.
-2. After iteration planning, persist the ordered known-task plan and initialize every known task snapshot as `queued` with `sequence` and `depends_on`. When a node derives dynamic tasks, append and register the complete derived group before executing its first task.
-3. For a complete workflow, first read Bootstrap's `next_action_owner`. Only for `agent`, invoke `$ai-delivery-checkpoint-task recover --iteration-id <iteration-id>` before preflight. Recovery must rebuild local state from the latest Git-tracked shared checkpoint when local runtime is absent. Continue the returned `recommended_task_id`; never choose the next task from chat memory. For `user` or `external`, stop at the zero-mutation wait boundary in step 7.
-4. Activate the recommended task before project mutation. If no task is recommended, reconcile missing or unsatisfied task-plan entries before continuing.
-5. Checkpoint after every meaningful artifact, gate, validation, merge, deployment action, or other external milestone, and before compaction or interruption.
-6. Before returning, finish the snapshot as `completed`, `blocked`, `failed`, or `interrupted`, with actual outputs, evidence, blockers, and one idempotent next action. A Hook event alone never proves completion.
+2. After iteration planning, persist the ordered known-task plan and initialize every known task snapshot as `queued` with `sequence`, `depends_on`, `--scope`, `--acceptance`, and `--responsibility`. Keep one task ID while iteration, node, skill, goal, scope, responsibility, dependencies, and acceptance remain unchanged; the CLI rejects the same contract under another ID. A material contract change requires a new task ID linked with `--derived-from` or `--supersedes`; planning, review, triage, repair, test, and version rounds are not new tasks. When a node derives dynamic tasks, append and register the complete derived group before executing its first task.
+3. For a complete workflow, first read Bootstrap's `next_action_owner`. Only for `agent`, invoke `$ai-delivery-checkpoint-task recover --iteration-id <iteration-id>` before preflight. Recovery must rebuild local state from the latest Git-tracked shared checkpoint when local runtime is absent. Continue the returned `recommended_task_id`; when its status is `failed`, explicitly activate it with `--new-attempt --phase repair`. Never choose the next task from chat memory. For `user` or `external`, stop at the zero-mutation wait boundary in step 7.
+4. Run `task-state.mjs inspect --task-id <task-id>` for read-only diagnosis, then activate the recommended task with its structured `--phase` before project mutation, checkpoint, or finish. Initialize new tasks only as queued; activation is the only path that starts an attempt and checks dependencies. Never override derived phase status with `--phase-status`. If no task is recommended, reconcile missing or unsatisfied task-plan entries before continuing.
+5. Checkpoint after every meaningful artifact, gate, validation, merge, deployment action, or other external milestone, and before compaction or interruption. Finding history is append-only. Record resolution only for an existing open finding, in repair/test/verification, with evidence and one approved `change_set_id`; record paired time categories when measured.
+6. Before returning, finish the snapshot as `completed`, `blocked`, `failed`, or `interrupted`, with actual outputs, evidence, blockers, and one idempotent next action. Completion is refused while a task-level current blocking finding remains open. A failed task remains retryable work and never satisfies dependencies; retry an unchanged logical task only with explicit `activate --new-attempt --phase repair`. A Hook event alone never proves completion.
 7. Persist `next_action_owner` as `agent`, `user`, or `external`. A user- or external-owned next action is a zero-mutation wait state: on restart or a generic “continue”, return only the recorded question or wait condition. Do not recover, activate, checkpoint, mutate artifacts, or change Git state until the required input arrives and ownership is explicitly transferred to `agent` with a new idempotent next action through the task CLI.
 
 ## Formal State
 
+The installed producer route is `development-seven-node`: `00-bootstrap -> 01-product-shaping -> 02-solution-design -> 03-delivery-readiness -> 04-implementation -> 05-candidate-assurance -> 06-version-closeout`. Producer Skills and installed guidance use only these development node IDs. `development-legacy-13` is read-only compatibility: inspect, verify, rebuild, and explicit migration may consume historical state, while every new legacy task, artifact, transition, candidate, closeout, or Gate write is rejected. Release nodes `R00-release-request` through `R10-release-archive` remain writable.
+
+When Bootstrap reports legacy compatibility or a premature archive, use the packaged top-level CLI before normal orchestration. Run `ai-delivery migrate <project> --dry-run` and require a reviewed report with schemas, semantic task groups, ambiguities, conflicts, verified anchors, and exact file changes. A legacy root migration copies workflow material into `.workflow/`; flat task shards gain explicit attempts without changing their lifecycle status or scope. Resolve every ambiguity through a source-checksum-bound `--decisions` document with a `human:` actor and rationale, then rerun dry-run. Apply migration only when `can_apply` is true; its manifest and backups must preserve source bytes, task lifecycle facts, scope, formal views, and legacy event bytes. Resolve an incorrect archive only through `ai-delivery repair <project> --invalidate-archive <iteration-id>` with an explicit human actor, reason, RCA evidence, and recovery evidence. The resulting forward transaction invalidates current eligibility while the original archive remains byte-identical. Use rollback only before any post-migration schema 2 transaction or migrated-byte drift; afterward use forward repair. Compaction is never part of migration: run `ai-delivery compact <project> --dry-run` only after a trusted anchor exists, review its exact coverage and byte report, and apply only on explicit operator intent.
+
 1. Use `node .workflow/tools/state/state.mjs inspect` to read schema 2 formal state: independent `development_state` and `release_state` scopes, the top-level workflow audit revision, and the artifact-registry revision.
-2. Register every formal artifact with `artifact register`; change its lifecycle only with `artifact status`; create a new artifact ID and `--supersedes` instead of overwriting a registered version.
+2. Keep `draft` and `review-draft` files mutable and outside the formal registry. Register only immutable semantic revisions such as `submitted`, `rejected`, `approved`, `frozen`, or `failed`; every later decision uses a new artifact ID and `--supersedes`. `artifact status` exists only to migrate a legacy registered working draft once and must not mutate a formal revision.
 3. Start development with `iteration-started`; start release only after explicit user intent with `release-started`. Record node, candidate, closeout, and archive changes with `transition`. Record human or contract Gates with `gate request` and `gate decide`.
-4. Pass the current stream revision through `--expected-revision` for every mutation. On a conflict, inspect again and reconcile; never retry blindly.
-5. Run `verify` before handoff, node completion, version closeout, and after recovery. Let the CLI enforce graph prerequisites, successful completion evidence, current-attempt mandatory Gates, and scope identity. Release nodes independently require verification at every release handoff. Stop on checksum, schema, audit, identity, or state-invariant failure.
-6. Never directly edit controlled formal state, shared task/checkpoint shards, or runtime task state. Treat global workflow and artifact indexes as deterministic views over authoritative shards where available. If either state script fails, repair the input or script problem rather than bypassing it.
-7. When the user clearly expresses a workflow improvement, invoke `$ai-delivery-evolve-workflow feedback record` and report the feedback ID. Do not save ordinary discussion, full conversation text, secrets, or AI reasoning. Evaluate pending evidence only after a task, version closeout, or explicit evolution review.
+4. At Delivery Readiness, run `scope freeze` to enable `scope_contract_version: 1` and bind approved Slices, requirements, acceptance, tasks, and artifacts. Afterward, only a human-approved `scope amend` may change scope. Use `scope warn` for a budget overrun; it must remain `warn-only` with `reslice_performed: false` and must not automatically replan or reslice.
+5. Read `inspect.derived_node_states` instead of assigning formal node status from narration. The projection uses task facts and blocking findings, Gates, artifacts, candidate identity, the current scope manifest, and completion receipts. A governed node may complete only from `ready-to-complete`; completion writes a receipt bound to those facts. Historical scopes without `scope_contract_version` retain legacy compatibility.
+6. Pass `artifact_registry.revision` through `--expected-revision` for artifact mutations. For scope, transition, and Gate mutations, pass the owning `development_state.revision` or `release_state.revision` through `--expected-scope-revision`; the top-level workflow revision form remains compatibility-only. A transition or Gate that consumes evidence records an artifact handoff in the same transaction and advances the artifact-registry revision, so inspect again before the next artifact mutation. On a conflict, inspect again and reconcile; never retry blindly.
+7. Run routine `verify` before handoff, node completion, and after recovery. It validates current formal views without traversing historical shards or decompressing archives. At ordinary task safe points, run `snapshot create --reason configured-interval`; the command is a no-op until the configured event interval is reached. Run `verify --history --since-anchor` after an anchor exists. `artifact compact` and `artifact prune` default to zero-write plans. Compact preserves original legacy shards in a checksummed gzip bundle and removes loose files only after full replay reproduces the anchored registry checksum; afterward `verify --history` reports `compacted-history`. Only explicit `artifact prune --apply` may replace covered shards with a retention receipt; afterward verification reports `retained-history` and does not claim deleted bytes were re-audited. Let the CLI enforce graph prerequisites, successful completion evidence, current-attempt mandatory Gates, and scope identity. Release nodes independently require routine verification at every release handoff. Stop on checksum, schema, audit, identity, or state-invariant failure.
+8. Never directly edit controlled formal state, shared task/checkpoint shards, or runtime task state. Treat global workflow and artifact indexes as deterministic views over authoritative shards where available. If either state script fails, repair the input or script problem rather than bypassing it.
+9. When the user clearly expresses a workflow improvement, invoke `$ai-delivery-evolve-workflow feedback record` and report the feedback ID. Do not save ordinary discussion, full conversation text, secrets, or AI reasoning. Evaluate pending evidence only after a task, version closeout, or explicit evolution review.
 
 ## Preflight
 
@@ -47,22 +67,16 @@ Require every workflow document to be written under project `.workflow/`. Use `.
 
 ## Route The Workflow
 
-Use this first-release order:
-
-1. `$ai-delivery-bootstrap`: classify state, initialize missing project context, or route checkpoint recovery.
-2. `$ai-delivery-define-product`: discovery Gate A, then product baseline Gate B.
-3. `$ai-delivery-design-architecture`: initial mode and human approval of major decisions.
-4. Start `$ai-delivery-prepare-platform` as a parallel stream.
-5. `$ai-delivery-design-experience`: obtain one human authoring-tool selection per prototype member; create an executable low-fidelity prototype; pass human Gate `UX-LF`; define visual direction, design tokens, component states, and select a compatible UI framework; pass human Gate `UX-VS`; create a runnable formal UI; pass human Gate `UX-UI`; record every review adjustment and upstream impact.
-6. `$ai-delivery-define-product` in prototype-reconciliation mode: after all formal UI candidates are approved, reconcile the complete adjustment set bidirectionally with product requirements through `product-prototype-reconciliation.yaml`. Rebaseline and repeat affected experience Gates until the decision is `aligned`.
-7. `$ai-delivery-design-architecture`: reconcile mode, prototype architecture receipt, `ready-for-development` experience changes, and final architecture baseline.
-8. `$ai-delivery-plan-iteration`.
-9. `$ai-delivery-design-tests`: prototype test receipt and public test contract.
-10. `$ai-delivery-develop-iteration`, including independent change review.
-11. Join the candidate and delivery-platform streams in a reproducible test environment.
-12. `$ai-delivery-verify-candidate` with `scope: iteration`; route failures upstream.
-13. `$ai-delivery-close-version`; create the immutable `version-ready` tag, advance `line/<product-id>`, mark the version `release-ready`, move closed shared task/checkpoint shards to `.workflow/control/archives/versions/<version-id>/`, and remove them from active recovery collections.
-14. Stop. Continue the next cumulative planned version from the latest line head, or wait for explicit user intent.
+Use this producer order:
+
+1. `00-bootstrap`: `$ai-delivery-bootstrap` classifies state, initializes missing project context, or routes checkpoint recovery.
+2. `01-product-shaping`: `$ai-delivery-define-product` owns discovery `GATE-A`, product-baseline `GATE-B`, and prototype reconciliation. Reuse an unaffected approved product baseline by exact artifact identity and checksum instead of replaying its interviews or Gates.
+3. `02-solution-design`: `$ai-delivery-design-architecture` and `$ai-delivery-design-experience` coordinate initial architecture, `UX-VS`, `UX-UI`, product reconciliation, and final architecture. Reuse unaffected approved architecture or experience baselines by exact identity and checksum.
+4. `03-delivery-readiness`: `$ai-delivery-prepare-platform`, `$ai-delivery-plan-iteration`, and `$ai-delivery-design-tests` converge on one approved Slice, dependency, acceptance, task, artifact, environment, and public-test contract; then freeze it with `scope freeze`.
+5. `04-implementation`: `$ai-delivery-develop-iteration` coordinates stable logical-task attempts for implementation, package review, triage, repair, and developer tests. It completes only after selecting and retaining one immutable candidate as evidence.
+6. `05-candidate-assurance`: `$ai-delivery-review-change` and `$ai-delivery-verify-candidate` collect review feedback and independently verify the candidate bound when the node attempt starts. Findings are applied only as an approved `change_set_id`; any candidate-changing repair returns through `04-implementation` and creates a new candidate and assurance attempt.
+7. `06-version-closeout`: `$ai-delivery-close-version` creates the immutable `version-ready` tag, advances `line/<product-id>`, marks the version `release-ready`, archives closed task/checkpoint shards, and removes them from active recovery collections.
+8. Stop. Continue the next cumulative planned version from the latest line head, or wait for explicit user intent.
 
 At every task and version safe point, route eligible feedback and trial observations through `$ai-delivery-evolve-workflow`. Extension behavior begins with the next task or version and never mutates an in-progress execution.
 
@@ -76,19 +90,23 @@ Pause for humans at:
 
 - discovery Gate A and product baseline Gate B;
 - major architecture decisions;
-- each prototype member's authoring-tool selection before prototype authoring;
-- each visual or interactive prototype member's `UX-LF`, `UX-VS`, and `UX-UI` decisions, repeated until the latest round is approved and every comment is terminal;
+- the Prototype's authoring-tool selection before prototype authoring;
+- each visual or interactive Page revision's `UX-VS` and `UX-UI` decisions, repeated until the latest round is approved and every comment is terminal;
 - production deployment approval;
 - every proposed standard creation, update, deprecation, or exception.
 
 Allow downstream contract validation instead of human approval at ordinary intermediate handoffs.
 
+At either experience Gate, start or reuse `ai-delivery manager serve <workspace>`, report its loopback URL, and route the user to P11 for Visual Standard or P12/P13 for the exact Prototype revision. The Manager must bind the displayed content and every decision to the current checksummed target. A mismatched target, non-loopback origin, or target drift keeps ownership with the agent for repair and must never be presented for human approval.
+
+During `UX-UI`, route each human Page decision through Workflow Manager P13 and report the Page IDs in `pending-review`, `changes-requested`, or `stale`. Do not replace or re-slice the planned work automatically. Only an identical checksum may carry the latest approved Page decision forward; a later changes-requested decision blocks inheritance. When the user approves the final pending Page, require one atomic transaction to write both its immutable Page receipt and the `UX-UI` Gate decision before advancing the formal node. After that Gate is approved, reject further Page writes until a new immutable Prototype revision has a new pending `UX-UI` request.
+
 ## Maintain State
 
 - Give every project, iteration, artifact, feature, story, acceptance criterion, slice, task, test, defect, release item, and deployment a stable ID.
 - Record artifact input IDs and versions; never infer dependencies from filenames.
 - Treat approved baselines and release versions as immutable. Create a new version for changes.
-- Carry the same immutable UI handoff, aligned product reconciliation, experience-change set, prototype-set identity/checksum and relevant member identities, source revisions, review-bundle checksums, tool-selection checksums, page/canvas/file catalog checksums, review/adjustment checksums, and impact-assessment checksums through architecture, planning, test design, development, and verification.
+- Carry the same immutable UI handoff, aligned product reconciliation, experience-change set, exact Prototype revision/checksum, source revision/checksum, review-bundle checksum, UI Mapping and normalized catalog checksums, review/adjustment checksums, and impact-assessment checksum through architecture, planning, test design, development, and verification. Reject missing or conflicting references and never infer relationships from file names or catalog order.
 - Mark downstream artifacts stale after an upstream change and route only the impacted work.
 - Record the standards baseline used by every artifact.
 - Keep one production release transition locked at a time while allowing later cumulative iteration work in parallel.

package/skills/ai-delivery-orchestrate/assets/project-template/.workflow/delivery/project.yaml

@@ -4,3 +4,4 @@ status: active
 created_at: ""
 current_iteration_id: INIT-0001
 production_release_id: null
+formal_state_snapshot_interval: 100

package/skills/ai-delivery-orchestrate/assets/project-template/.workflow/delivery/workflow-state.yaml

@@ -9,6 +9,7 @@ development_state:
   completed_nodes: []
   pending_gates: []
   gate_decisions: []
+  contract_retirement_receipts: []
   node_attempts: {}
   latest_candidate_id: null
   latest_release_id: null
@@ -22,6 +23,7 @@ release_state:
   completed_nodes: []
   pending_gates: []
   gate_decisions: []
+  contract_retirement_receipts: []
   node_attempts: {}
   latest_candidate_id: null
   latest_release_id: null

package/skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/frontend-guard/frontend-guard.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { runFrontendGuardCommand } from "./frontend-guard-runtime.mjs";
+
+function usage() {
+  return [
+    "Usage:",
+    "  frontend-guard <check-file|verify-diff> [project] [--path <file>] [--base <git-ref>] [--head <git-ref>] [--experience <relative-directory>] [--revision <relative-yaml>]",
+  ].join("\n");
+}
+
+function parseArgs(args) {
+  const options = new Map();
+  const positionals = [];
+  const valueOptions = new Set(["--path", "--base", "--head", "--experience", "--revision"]);
+  for (let index = 1; index < args.length; index += 1) {
+    const value = args[index];
+    if (valueOptions.has(value)) {
+      const optionValue = args[index + 1];
+      if (!optionValue || optionValue.startsWith("--")) throw new Error(`Missing value for ${value}`);
+      options.set(value, optionValue);
+      index += 1;
+    } else if (value.startsWith("--")) throw new Error(`Unknown option: ${value}`);
+    else positionals.push(value);
+  }
+  return { options, positionals };
+}
+
+try {
+  const args = process.argv.slice(2);
+  const action = args[0];
+  if (!action || action === "--help" || action === "help") {
+    process.stdout.write(`${usage()}\n`);
+  } else {
+    const { options, positionals } = parseArgs(args);
+    const target = path.resolve(positionals[0] || process.cwd());
+    const report = runFrontendGuardCommand(target, action, {
+      path: options.get("--path"),
+      base: options.get("--base"),
+      head: options.get("--head"),
+      experience: options.get("--experience"),
+      revision: options.get("--revision"),
+    });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  }
+} catch (error) {
+  process.stderr.write(`ai-delivery-frontend-guard: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/hooks/hook-event.mjs

@@ -53,6 +53,96 @@ async function readStdin() {
   return Buffer.concat(chunks).toString("utf8");
 }
 
+function preToolUsePaths(input) {
+  const eventName = String(input.hook_event_name || input.hookEventName || "").toLowerCase();
+  if (eventName !== "pretooluse") return [];
+  const toolName = String(input.tool_name || input.toolName || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, "");
+  const mutatingFileTools = [
+    "applypatch", "edit", "editfile", "multiedit", "write", "writefile",
+    "createfile", "deletefile", "movefile", "renamefile", "replacefile",
+  ];
+  if (!mutatingFileTools.some((name) => toolName === name || toolName.endsWith(name))) return [];
+  const toolInput = input.tool_input && typeof input.tool_input === "object"
+    ? input.tool_input
+    : {};
+  const candidates = [];
+  for (const field of ["file_path", "path", "target_file"]) {
+    if (typeof toolInput[field] === "string") candidates.push(toolInput[field]);
+  }
+  if (Array.isArray(toolInput.edits)) {
+    for (const edit of toolInput.edits) {
+      if (!edit || typeof edit !== "object") continue;
+      for (const field of ["file_path", "path", "target_file"]) {
+        if (typeof edit[field] === "string") candidates.push(edit[field]);
+      }
+    }
+  }
+  for (const field of ["patch", "input"]) {
+    if (typeof toolInput[field] !== "string") continue;
+    for (const line of toolInput[field].split(/\r?\n/)) {
+      const match = line.match(/^\*\*\* (?:Add|Update|Delete) File: (.+)$/)
+        || line.match(/^\*\*\* Move to: (.+)$/);
+      if (match) candidates.push(match[1]);
+    }
+  }
+  return [...new Set(candidates.map((item) => item.trim()).filter(Boolean))];
+}
+
+function owningGitRoot(file) {
+  let current = fs.existsSync(file) && fs.statSync(file).isDirectory() ? file : path.dirname(file);
+  while (!fs.existsSync(current)) {
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+  const result = spawnSync("git", ["-C", current, "rev-parse", "--show-toplevel"], {
+    encoding: "utf8",
+    timeout: 5_000,
+    windowsHide: true,
+  });
+  return result.status === 0 ? path.resolve(result.stdout.trim()) : null;
+}
+
+function samePath(left, right) {
+  const normalize = (value) => process.platform === "win32"
+    ? path.resolve(value).toLowerCase()
+    : path.resolve(value);
+  return normalize(left) === normalize(right);
+}
+
+function enforceFrontendGuard(projectRoot, input) {
+  const changedPaths = preToolUsePaths(input);
+  if (!changedPaths.length) return;
+  const guardCli = path.join(projectRoot, ".workflow", "tools", "frontend-guard", "frontend-guard.mjs");
+  if (!fs.existsSync(guardCli)) {
+    throw new Error(`Frontend guard runtime is missing: ${guardCli}`);
+  }
+  for (const changedPath of changedPaths) {
+    const resolvedChangedPath = path.isAbsolute(changedPath)
+      ? changedPath
+      : path.resolve(process.cwd(), changedPath);
+    const gitRoot = owningGitRoot(resolvedChangedPath);
+    if (gitRoot && samePath(gitRoot, projectRoot)) continue;
+    const guarded = spawnSync(process.execPath, [
+      guardCli, "check-file", projectRoot, "--path", resolvedChangedPath,
+    ], {
+      cwd: projectRoot,
+      encoding: "utf8",
+      timeout: 15_000,
+      windowsHide: true,
+    });
+    if (guarded.error || guarded.status !== 0) {
+      throw new Error(
+        guarded.error?.message
+        || guarded.stderr.trim()
+        || `Frontend guard rejected ${resolvedChangedPath}.`,
+      );
+    }
+  }
+}
+
 try {
   const currentProjectFile = findUp(process.cwd(), path.join(".workflow", "delivery", "project.yaml"));
   const legacyProjectFile = currentProjectFile
@@ -67,6 +157,7 @@ try {
   const marker = fs.existsSync(markerFile) ? JSON.parse(fs.readFileSync(markerFile, "utf8")) : null;
   const raw = await readStdin();
   const input = raw.trim() ? JSON.parse(raw) : {};
+  enforceFrontendGuard(projectRoot, input);
   const taskId = safeId(process.env.AI_DELIVERY_TASK_ID || marker?.task_id || input.turn_id || input.session_id);
   const stateRoot = path.resolve(process.env.AI_DELIVERY_STATE_ROOT || marker?.state_root || projectRoot);
   const workflowRoot = fs.existsSync(path.join(stateRoot, ".workflow", "delivery", "project.yaml"))

package/skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/manager/manager.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import {
+  WorkflowManagerError,
+  renderWorkflowManagerCommandHelp,
+  runWorkflowManagerCommand,
+} from "./workflow-manager-runtime.mjs";
+
+const runtimeRoot = path.dirname(fileURLToPath(import.meta.url));
+const defaultProjectRoot = path.resolve(runtimeRoot, "..", "..", "..");
+
+function option(args, name) {
+  const index = args.indexOf(name);
+  if (index === -1) return null;
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) throw new Error(`Missing value for ${name}`);
+  return value;
+}
+
+try {
+  const args = process.argv.slice(2);
+  const action = args[0];
+  if (!action || action === "help" || action === "--help") {
+    process.stdout.write(`${renderWorkflowManagerCommandHelp(null, { command: "manager" })}\n`);
+  } else if (action === "action" && args.includes("--help")) {
+    process.stdout.write(`${renderWorkflowManagerCommandHelp(args[1], { command: "manager" })}\n`);
+  } else {
+    const actionName = action === "action" ? args[1] : null;
+    const projectIndex = action === "action" ? 2 : 1;
+    const projectArg = args[projectIndex] && !args[projectIndex].startsWith("--")
+      ? args[projectIndex]
+      : defaultProjectRoot;
+    const inputFile = option(args, "--input");
+    const result = await runWorkflowManagerCommand(runtimeRoot, path.resolve(projectArg), action, {
+      port: option(args, "--port"),
+      open: !args.includes("--no-open"),
+      resource: option(args, "--resource"),
+      experience: option(args, "--experience"),
+      revision: option(args, "--revision"),
+      branch: option(args, "--branch"),
+      attachmentId: option(args, "--attachment-id"),
+      expectedChecksum: option(args, "--expected-checksum"),
+      terminalId: option(args, "--terminal-id"),
+      sourceSnapshotId: option(args, "--source-snapshot-id"),
+      sourceRef: option(args, "--source-ref"),
+      pageId: option(args, "--page-id"),
+      reviewSceneId: option(args, "--review-scene-id"),
+      actionName,
+      input: inputFile ? JSON.parse(fs.readFileSync(path.resolve(inputFile), "utf8")) : undefined,
+    });
+    process.stdout.write(`${JSON.stringify(result?.report || result, null, 2)}\n`);
+  }
+} catch (error) {
+  process.stderr.write(`${JSON.stringify({
+    error: {
+      code: error instanceof WorkflowManagerError ? error.code : "invalid-request",
+      message: error?.message || "Workflow Manager request failed",
+    },
+  })}\n`);
+  process.exitCode = 1;
+}

package/skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/manager/start.cmd

@@ -0,0 +1,4 @@
+@echo off
+setlocal
+node "%~dp0manager.mjs" serve %*
+endlocal

package/skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/manager/start.ps1

@@ -0,0 +1,2 @@
+$ErrorActionPreference = "Stop"
+node (Join-Path $PSScriptRoot "manager.mjs") serve @args

package/skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/{viewer → manager}/start.sh

@@ -1,4 +1,4 @@
 #!/usr/bin/env sh
 set -eu
 SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
-exec node "$SCRIPT_DIR/server.mjs" "$@"
+exec node "$SCRIPT_DIR/manager.mjs" serve "$@"

package/skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/mock/mock.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { runMockSystemAction } from "./mock-system.mjs";
+
+function usage() {
+  return [
+    "Usage:",
+    "  mock <setup|start|stop|status|sync> [project] [--dry-run]",
+    "  mock freeze [project] --experience <relative-directory> --scenario-pack <relative-yaml> [--dry-run]",
+  ].join("\n");
+}
+
+function parseArgs(args) {
+  const options = new Map();
+  const positionals = [];
+  for (let index = 1; index < args.length; index += 1) {
+    const value = args[index];
+    if (value === "--dry-run") continue;
+    if (value === "--experience" || value === "--scenario-pack") {
+      const optionValue = args[index + 1];
+      if (!optionValue || optionValue.startsWith("--")) throw new Error(`Missing value for ${value}`);
+      options.set(value, optionValue);
+      index += 1;
+    } else if (value.startsWith("--")) throw new Error(`Unknown option: ${value}`);
+    else positionals.push(value);
+  }
+  return { options, positionals };
+}
+
+try {
+  const args = process.argv.slice(2);
+  const action = args[0];
+  if (!action || action === "--help" || action === "help") {
+    process.stdout.write(`${usage()}\n`);
+  } else {
+    const { options, positionals } = parseArgs(args);
+    const projectArg = positionals[0];
+    const target = path.resolve(projectArg || process.cwd());
+    const result = await runMockSystemAction(target, action, {
+      dryRun: args.includes("--dry-run"),
+      experience: options.get("--experience"),
+      scenarioPack: options.get("--scenario-pack"),
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  }
+} catch (error) {
+  process.stderr.write(`ai-delivery-mock: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/ui-acceptance/ui-acceptance.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { runUiAcceptanceCommand } from "./ui-acceptance-runtime.mjs";
+
+function usage() {
+  return [
+    "Usage:",
+    "  ui-acceptance <plan|verify> [project] --request <relative-yaml> [--results <relative-yaml>]",
+  ].join("\n");
+}
+
+function option(args, name) {
+  const index = args.indexOf(name);
+  if (index === -1) return undefined;
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) throw new Error(`Missing value for ${name}`);
+  return value;
+}
+
+try {
+  const args = process.argv.slice(2);
+  const action = args[0];
+  if (!action || action === "--help" || action === "help") {
+    process.stdout.write(`${usage()}\n`);
+  } else {
+    const projectArg = args[1] && !args[1].startsWith("--") ? args[1] : process.cwd();
+    const report = runUiAcceptanceCommand(path.resolve(projectArg), action, {
+      request: option(args, "--request"),
+      results: option(args, "--results"),
+    });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  }
+} catch (error) {
+  process.stderr.write(`ai-delivery-ui-acceptance: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/skills/ai-delivery-orchestrate/assets/project-template/AGENTS.md

@@ -9,16 +9,39 @@
 - 代码引用必须包含 `repo_id`、`code_commit`、可选 `code_tag`、`source_path` 和 SHA-256。版本发布身份必须同时核验代码 Tag、工作流 Tag 和 Manifest checksum。
 - 根 `.gitattributes` 必须保持安装器写入的工作流 `eol=lf` 规则，避免跨平台 checkout 改变受控物料字节和 checksum；该规则不得扩展到嵌套代码仓。
 
+## 代码智能
+
+- 解析、定位或评估源码影响前，先从 `.workflow/config/workspace.yaml` 的 `code_repository.path` 解析代码仓库；CodeGraph MCP 可用且该代码仓已有索引时，优先调用 `codegraph_explore`，并把代码仓绝对路径作为 `projectPath`。
+- MCP 不可用但 CodeGraph CLI 与索引可用时，运行 `codegraph explore "<query>" --path <code-repository>`；定位结果必须回到具体源码和测试核对。
+- CodeGraph 不可用、未初始化、失败或不支持当前语言时，降级到 Semble，再使用 `rg` 和定点读取；外部代码智能工具缺失不阻断正式工作流。
+- `codegraph affected` 只生成推荐测试建议，不得据此缩减既有必跑测试或正式 Gate。
+- `.codegraph/` 是代码仓内本地可重建缓存，通过代码仓本地 Git exclude 保持未跟踪；它不属于正式状态、artifact registry、事件、checkpoint、安装清单或归档。Windows 与 WSL 共用 checkout 时使用不同的 `CODEGRAPH_DIR`。
+- Agent/MCP 全局安装由用户显式管理；工作流 `init`、`upgrade` 和 CodeGraph setup 只管理项目级工作流资产或代码仓索引。
+
+## Mock System
+
+- Prototype 或 UI Acceptance 需要协议场景时，先运行 `ai-delivery mock setup <workspace>` 与 `ai-delivery mock start <workspace>`；每个 mock 显式登记 External Dependency Mock（`external-dependency`）或 Product Backend Mock（`product-backend`）kind、owner、批准合同、replacement condition、operation/channel 和稳定 scenario identity，并保持两类 catalog 隔离。先审阅 `ai-delivery mock sync <workspace> --dry-run`，确认具名 scenario 和 dispatcher 输入，再运行 `ai-delivery mock sync <workspace>`。
+- 受管 UI 修改必须把每个实际 OpenAPI/AsyncAPI 定义导出到 `mock-admin-exports/`，并由 `mock-admin-export.yaml` 按 kind、Mock ID、protocol、相对路径和 SHA-256 绑定；freeze 必须对每个 active Review Scene 使用的导出 scenario 执行协议校验。禁止生产流量录制、生产凭据和未脱敏个人数据，显式导入仍须通过脱敏检查。每个 active Review Scene 在 `mock-scenario-mappings.csv` 中必须且只能映射一个确定性 scenario。
+- 先运行 `ai-delivery mock freeze <workspace> --experience <relative-directory> --scenario-pack mock-scenario-pack-request.yaml --dry-run`，让用户确认精确 candidate checksum，再冻结并在正式 artifact registry 登记不可变 Mock Scenario Pack。只有该登记 Pack 可供 Prototype revision 和 UI Acceptance 共用。
+- Product Backend Mock 只能驱动 UI 场景，不能证明真实产品后端功能或端到端验收；真实后端满足 replacement condition 后停用对应 mock。
+- Microcks 只绑定 loopback；数据库、日志、流量和端口状态可丢弃，不得进入正式状态、artifact registry、事件、checkpoint 或 Gate evidence。
+
 开始工作前：
 
 1. 只使用安装在 `.agents/skills/` 下的项目级 Skill，不得在全局安装或更新本工作流。
 1.1 用户说“开始”“继续”“下一步”“现在做到哪了”、直接描述需求或明确提出发布，都属于有效自然语言入口。AI 必须自主规划并调用所需 Skill 和项目内 CLI，不得要求用户输入 Skill 名称或执行工作流命令；只向用户询问业务事实、物料确认、人工 Gate 或外部副作用授权。
 2. 首次进入项目或重启会话时，先使用 `$ai-delivery-bootstrap`，并在项目根运行 `node .workflow/tools/bootstrap/bootstrap.mjs inspect` 只读识别状态。空项目进入需求发现，存量代码项目生成草稿上下文，中断任务进入 checkpoint 恢复，不一致状态停止并报告。
-2.1 已完成 `init` 且没有正式交付物和 task shard 时，先运行项目内 `bootstrap` 入口生成上下文，再以 `INIT-0001` 建立 `TASK-INIT-0001-00`（Bootstrap）和依赖它的 `TASK-INIT-0001-01`（产品发现）。首次业务问题之前必须已有合法任务身份；不得从聊天记忆临时编造下一任务。
-3. 修改代码或交付物前，先读取 Bootstrap 返回的 `runtime.next_action_owner`。仅当责任方为 `agent` 时，运行 `$ai-delivery-checkpoint-task recover --iteration-id <iteration-id>`，只继续返回的 `recommended_task_id`，并通过 `task-state.mjs activate` 激活任务。责任方为 `user` 时，只原样询问记录的单个业务问题，禁止 recover、activate、checkpoint、正式状态、物料或 Git 写入；责任方为 `external` 时，只报告等待条件。收到所需输入后，必须通过 `activate` 同时提供 `--next-action-owner agent` 和新的幂等 `--next-action`，由 CLI 在需要时从共享 shard 原子恢复本机 runtime 并转交责任方。
+2.1 已完成 `init` 且没有正式交付物和 task shard 时，先运行项目内 `bootstrap` 入口生成上下文，再以 `INIT-0001` 建立 `TASK-INIT-0001-00`（Bootstrap）和依赖它的 `TASK-INIT-0001-01`（Product Shaping）。首次业务问题之前必须已有合法任务身份；不得从聊天记忆临时编造下一任务。
+3. 修改代码或交付物前，先读取 Bootstrap 返回的 `runtime.next_action_owner`。仅当责任方为 `agent` 时，运行 `$ai-delivery-checkpoint-task recover --iteration-id <iteration-id>`，只继续返回的 `recommended_task_id`；先用 `task-state.mjs inspect --task-id <task-id>` 只读核对，再通过带 `--phase` 的 `activate` 激活任务。推荐状态为 `failed` 时必须使用 `activate --new-attempt --phase repair`。责任方为 `user` 时，只原样询问记录的单个业务问题，禁止 recover、activate、checkpoint、正式状态、物料或 Git 写入；责任方为 `external` 时，只报告等待条件。收到所需输入后，必须通过 `activate` 同时提供 `--next-action-owner agent` 和新的幂等 `--next-action`，由 CLI 在需要时从共享 shard 原子恢复本机 runtime 并转交责任方。
 4. 任务、checkpoint、恢复状态、活动任务标记和版本归档只能由 `.agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs` 修改。
 5. 正式流程、物料和 Gate 状态只能由 `node .workflow/tools/state/state.mjs ...` 修改。禁止直接编辑 `.workflow/delivery/workflow-state.yaml`、`.workflow/delivery/artifact-registry.yaml` 和 `.workflow/delivery/state-events.jsonl`。
 5.1 研发 scope 使用 `iteration-started`，发布 scope 仅在用户明确发布后使用 `release-started`；两者可并行且不得互相重置。节点必须满足流程图前置条件、成功证据和当前尝试的强制 Gate。
+5.1.1 当前研发生产路线是 `development-seven-node`：`00-bootstrap -> 01-product-shaping -> 02-solution-design -> 03-delivery-readiness -> 04-implementation -> 05-candidate-assurance -> 06-version-closeout`。生产 Skill 只能为新任务、物料和正式 transition 使用这些研发节点 ID。`development-legacy-13` 仅提供只读兼容：`inspect`、`verify`、`rebuild` 和显式迁移可以读取历史状态；新任务、物料登记、transition、candidate、版本收尾和 Gate 写入全部拒绝。发布节点 `R00-release-request` 至 `R10-release-archive` 继续允许写入。
+5.1.2 Bootstrap 报告旧 schema、任务分组歧义或错误归档时，先运行发行包 `migrate --dry-run` 审阅 schema、分组、冲突、已验证 anchor 和文件变化。旧根布局会复制到 `.workflow/`，平铺 task 增加显式 attempts；分组歧义只能用绑定 dry-run source checksum、`human:` actor 和 rationale 的 `--decisions` 文件解除。结构迁移保持源字节、task lifecycle、scope、正式视图和旧事件字节不变；错误归档只通过带人工 actor、原因、RCA 与恢复 evidence 的独立 `repair --invalidate-archive` 前向事务失效，原归档不得改写。迁移后出现 schema 2 事务或迁移目标字节漂移即关闭回滚窗口。compact 与迁移分离：可信 anchor 建立后先运行 `ai-delivery compact <project> --dry-run` 审阅 coverage、root digest 和字节计划，只有人工明确要求才应用。
+5.1.3 Prototype 迁移的 dry-run 必须报告旧 set 中声明、有效和无效成员数量，并据此区分零成员、单成员和多成员；同一份 decisions 文件必须同时包含 `decisions` 与 `prototype_decisions`。完整性或 checksum 冲突只能修复源证据，人工决定不得覆盖；旧 member/set、关闭或归档记录、Gate 和事件保持原字节。迁移后的唯一 descriptor 状态为 `migration-pending-ux-ui`，必须先建立并校验完整的新 Prototype revision，再执行全新的 `UX-UI`；原型查看与审核统一由工作流管理器承担。
+5.2 Delivery Readiness 使用 `scope freeze` 冻结带 checksum 的 Slice、需求、验收、任务和物料集合并启用 `scope_contract_version: 1`。冻结后只有带明确人工批准和 `--supersedes` 的 `scope amend` 可以改变范围；预算超限仅用 `scope warn` 登记 `warn-only` 与 `reslice_performed: false`，不得自动重新切片或改变验收。历史 scope 未启用该字段时保持旧契约兼容。
+5.3 从 `inspect.derived_node_states` 读取 `pending | active | waiting | blocked | ready-to-complete | completed`，不得根据聊天或单一任务状态直接写正式节点状态。投影必须综合 task、最新 blocking finding、Gate、artifact、candidate、当前 scope manifest 和 completion receipt；受新契约治理的节点仅能从 `ready-to-complete` 完成，并写入绑定这些事实的 completion receipt。
+5.4 `draft/review-draft` 是 registry 外的可变 working file。提交、拒绝、批准、冻结、失败等语义决定使用新 artifact ID 登记为不可变 revision；后续决定通过 `--supersedes` 创建新 revision，不得用 `artifact status` 原地改写。`artifact status` 只兼容迁移升级前已登记的 draft。`artifact compact` 默认零写入；apply 必须先把 anchor 覆盖的 legacy shard 原字节写入 checksummed gzip bundle，并从包内完整 replay 到锚定 registry checksum，验证失败不得移除 loose history；成功后的模式是 `compacted-history`。`artifact prune` 同样默认零写入，只有显式 `--apply` 才能删除 artifact shard 并写 retention receipt；其模式是 `retained-history`，不得声称重审已删除字节。
 6. 状态脚本失败时必须停止并修复输入、revision 冲突或脚本问题，不得手工修改受控文件绕过失败。
 7. 每次状态变更前运行 `inspect` 获取当前 revision；每次节点交接、版本收尾、生产审批、部署和发布归档前运行 `verify`。
 8. 读取 `.workflow/standards/index.yaml`，只加载适用于当前任务且状态为 `approved` 的规范。
@@ -26,16 +49,21 @@
 10. 应用 `STD-ARTIFACT-PATH-001`：研发流程文档写入 `.workflow/`；计划版本产物写入 `.workflow/iterations/<version-id>/<node-id>/`；独立发布产物写入 `.workflow/releases/<release-id>/<release-node>/`；不得忽略整个 `.workflow/`。
 11. 应用 `STD-TEST-LOCATION-001`：应用测试使用代码仓库既有框架和原生测试位置，不写入 `.workflow/`；临时测试输出按代码仓库规则忽略，不得登记为正式交付物。
 12. 每个交付物记录实际应用的规范 ID 和版本。已登记物料发生变更时创建新 ID，并使用 `--supersedes` 关联旧版本，不得覆盖旧版本。
-13. 一个任务组开始前，将全部已知任务按 `sequence` 和 `depends_on` 登记为 `queued`。每个任务用 `next_action_owner: agent | user | external` 明确下一动作责任方；重复 evidence 必须保持唯一。激活推荐任务后，在有意义的里程碑写入 checkpoint，并在交还控制权前结束当前任务状态。
+13. 一个任务组开始前，将全部已知任务按 `sequence` 和 `depends_on` 登记为 `queued`，并用 `--scope`、`--acceptance`、`--responsibility` 固定逻辑契约。init 只允许 queued；只有 activate 能创建 attempt 并检查依赖，queued 必须 activate 后才能 checkpoint/finish。phase 状态由 task transition 推导且不得使用 `--phase-status` 覆盖。iteration、node、skill、goal、scope、责任、依赖和 acceptance 未变化时复用同一 task ID；相同契约不得换 ID，契约实质变化才创建新 task，并用 `--derived-from` 或 `--supersedes` 关联。进入 review phase 时 CLI 固定 `review_subject_baseline`；评审必须针对该对象完整收集全部反馈，期间不得修改代码，批准时若 Git 已变化则拒绝。随后通过 `--change-set-json` 提供批准人、理由、全部 open finding IDs、允许文件、预期证据、`review_axes` 和 `collection_decision`，CLI 自动固化代码修复基线、规范反馈集和 collection checksum。实现者在 repair/test/verification phase 集中应用同一个批准集；随后使用同一个 `change_set_id` 集中复审，把 finding 标为 resolved，并声明与批准后真实 Git 变化完全一致的 `changed_files`。评审、分诊、修复、测试等轮次记录为同一 task 的 phase/finding，finding 记录只追加；resolved 必须引用已有 open finding。task 级最新结论仍有 open blocking finding 时不得 completed。failed 不满足依赖但仍是待恢复工作，原契约重试必须显式使用 `activate --new-attempt --phase repair`。每个任务用 `next_action_owner: agent | user | external` 明确下一动作责任方；重复 evidence 必须保持唯一。激活推荐任务后，在有意义的里程碑写入 checkpoint，并在交还控制权前结束当前任务状态。
 13.1 `task-state.mjs` 会从权威 `.workflow/config/workspace.yaml` 解析嵌套代码仓并写入 `code_branch`、`code_commit`；不得从安装清单副本推断代码路径，也不得把工作流分支或工作流提交作为代码身份。`blockers` 只保存当前未解决阻塞，解除阻塞后必须通过脚本切换状态并清空当前列表。
 14. Hook 日志只用于脱敏审计和心跳，不得作为任务完成、Gate 批准或正式交付物的替代品，也不得修改正式或 runtime 状态。
-15. 研发流程在 `12-version-closeout` 结束。登记 `release-ready` 收尾物料、完成节点并验证不可变身份后，必须通过正式状态 CLI 的 `version-closed` 事件更新累计研发版本，再归档任务上下文；不得直接编辑状态文件，也不得因为版本完成而自动发布。
-16. 后续计划版本必须从最新 `line/<product-id>` 开始；`main` 始终表示当前生产验证成功历史。
-17. 只有用户明确提出发布并选择截止版本时，才使用 `$ai-delivery-orchestrate-release`。系统必须计算从当前生产版本到目标版本的连续闭包。
-18. 同版本重新发布必须创建新 release ID，并重新执行环境快照、验证和生产审批。R09 只向 R10 交付已验证生产身份；R10 登记 `released` 归档物料并完成节点后，必须通过 `release-archived` 事件更新生产版本和 release ID。历史版本恢复通过旧镜像 digest，不创建 rollback 分支。
+14.1 任何正式前端修改必须先更新隔离 Prototype 并取得用户 Page approval，再冻结 checksummed `frontend-change-scope.yaml` 与 UI Mapping。首次写入每个 UI 路径前运行 `ai-delivery frontend-guard check-file <workspace> --path <path>`；合并、Candidate Assurance 和正式交接前从固定 refs 运行 `ai-delivery frontend-guard verify-diff <workspace> --base <base> --head <head>`，由 independent Git diff 复核。Hook 只做前置防误改，不能替代后者。文案、样式、响应式、无障碍、Page/route 增删和缺陷修复均无例外。
+14.2 UI-bearing candidate 必须在 `05-candidate-assurance` 内运行 `ai-delivery ui-acceptance plan` 和 `verify`，绑定 active attempt、immutable candidate、Prototype revision、Visual Standard、Page receipts、UI Mapping、Scenario Pack 与 pinned Playwright environment。UI Acceptance 不是新节点。Product Backend Mock 不得充当真实后端验收；candidate checksum 改变时返回 `04-implementation` 并创建新 attempt。
+15. 当前研发生产路线在 `06-version-closeout` 结束。登记 `release-ready` 收尾物料、完成节点并验证不可变身份后，必须通过正式状态 CLI 的 `version-closed` 事件更新累计研发版本，再归档任务上下文；不得直接编辑状态文件，也不得因为版本完成而自动发布。
+16. `product-id` 是首次 bootstrap 时冻结的稳定产品研发线身份，不是仓库、版本或 release 名称。该产品首次开始计划版本时，从当时 `main` 创建一次 `line/<product-id>`；后续计划版本必须从最新 line 开始，不能在每次迭代或发布时重新从 `main` 拉线。`main` 始终表示当前生产验证成功历史。
+17. 只有用户明确提出发布并选择截止版本时，才使用 `$ai-delivery-orchestrate-release`。R00 必须同时记录当时受保护 `main` 的精确 `expected_main`，系统必须计算从当前生产版本到目标版本的连续闭包。增量发布要求该快照仍是 main 且为目标 `version-ready` Tag 的祖先；同版本重发要求目标 Tag 已经可由该快照到达。
+18. R04 只能通过包内 `.agents/skills/ai-delivery-manage-git/scripts/release-git.mjs create-candidate --release-id <id> --release-branch <branch> --expected-main <r00-sha> --source-tag <tag> --source-commit <tag-sha> --receipt <path> --apply` 从该快照创建 release 分支。增量发布以 `--no-ff` 合入一个目标 Tag，结果 `candidate_commit` 是唯一可验证、审批、部署和冻结 release Tag 的身份；同版本重发不新增合并，候选就是 `expected_main`。中间版本 Tag 仅用于闭包和物料追溯。main 漂移或候选不一致时必须标为 `stale`、保留证据并创建新 R00 请求，不得调整旧候选基线。
+18.1 同版本重新发布必须创建新 release ID，并重新执行环境快照、验证和生产审批。R09 先写入机器可读 `production-verification.json`（`schema_version: 1`、`operation: production-verification-decision`、精确 `release_id`、`decision: released`、R00 `expected_main_commit`、以及相等的 `verified_release_commit`/`deployed_commit`），再只向 R10 交付已验证生产身份；生产验证为 `released` 后，使用 `release-git.mjs promote --release-id <id> --release-branch <branch> --expected-main <r00-sha> --verified-release-commit <candidate-sha> --production-verification <R09-json> --receipt <path> --apply` 精确快进 main。R10 登记 `released` 归档物料并完成节点后，必须通过 `release-archived` 事件更新生产版本和 release ID。历史版本恢复通过旧镜像 digest，不创建 rollback 分支。
+18.2 `release-fix/<release-id>/<defect-id>` 只从活动候选创建。修复候选生产验证成功后、R10 归档前，冻结 schema 2 的产品线级 `candidate-inventory.json`：根部为 `scope: product-line`、`product_id`、`line_branch` 和 active candidate；每个候选保留自己的 `candidate_id`、`release_id`、commit 与 status，根部不得写 `release_id`。然后使用 `release-git.mjs sync-release-fix --release-id <id> --source-ref <branch> --source-commit <sha> --verified-release-commit <candidate-sha> --line-branch <line> --expected-line <line-sha> --production-verification <R09-json> --candidate-inventory <predecessor-R10-json> --successor-candidate-inventory <new-R10-json> --receipt <path> --apply` 受控同步到 `line/<product-id>`。successor 路径必须与前代库存和 receipt 不同，脚本只创建不可变 successor，不得改写输入库存；脚本从整个产品线库存派生 `stale_candidate_ids` 和带 `release_id` 的 `candidate_status_updates`，调用方不得传入 stale 列表。若已存在于 line，仍须登记 `status: idempotent` receipt 且只能复用字节完全一致的 successor。所有未包含已成功修复的可选候选均为 `stale`；旧 active 失效时 successor 把 active 指针推进到已验证候选。不得改写历史 version-ready Tag、版本 Manifest 或 release Tag。
 19. 不得绕过流程 Gate、修改已批准基线、推断缺失批准，或在恢复后自动重放生产动作。
-20. 版本任务归档的权威位置是 `.workflow/control/archives/versions/<version-id>/`。归档完成后不得把对应任务或 checkpoint 留在活动集合，普通恢复不得加载归档详情。
-21. 需要人工浏览工作流和物料时，在项目根目录运行 `.\.workflow\tools\viewer\start.cmd`（Windows）或 `sh ./.workflow/tools/viewer/start.sh`（macOS/Linux）。查看器是可删除、可由 `init` 重装的只读工具，其缺失不影响工作流运行。
+20. 版本任务归档的权威位置是 `.workflow/control/archives/versions/<version-id>/`。归档前必须由正式状态 CLI 的 `snapshot references` 在最新可信 anchor 中投影目标 scope manifest、candidate、Gate decision 与 history anchor；任何缺失都必须在写归档前失败，不得产生 nullable formal reference。`version-manifest.json` 以相对路径和 checksum 引用 task summary、attempt receipt（checksum 覆盖 ref 指向的完整 attempt 值）和这些正式记录，不重复内嵌正式记录。归档完成后不得把对应任务或 checkpoint 留在活动集合，普通恢复不得加载归档详情。
+21. 需要人工管理工作流、查看物料或审核原型时，在项目根目录运行 `.\.workflow\tools\manager\start.cmd`（Windows）或 `sh ./.workflow/tools/manager/start.sh`（macOS/Linux）。工作流管理器是唯一受支持的项目控制界面；所有写操作仍必须经过其治理动作、并发校验、Receipt 和不可变 Event。
+21.1 读取、审核、配置或操作 Workflow Manager 时，先读取 `.workflow/tools/manager/AGENT-INTERFACE.md`，通过 `contracts` 资源发现动作 Schema，并遵循其中的并发、幂等、plan/apply、Receipt/Event、Outbox 和恢复流程。
 ## 项目级工作流自进化
 
 - 用户明确提出工作流意见或建议时，使用 `$ai-delivery-evolve-workflow` 记录脱敏反馈并返回反馈 ID；普通讨论和 AI 推测不得冒充用户反馈。

package/skills/ai-delivery-orchestrate/assets/project-template/gitignore.template

@@ -0,0 +1 @@
+.workflow/delivery/runtime/