@loomhelm/multi-task-flow 0.0.0-stage → 0.2.1

package/toolkit/skills/multi-task-flow/web/view-state.ts

@@ -0,0 +1,185 @@
+export type DashboardTab = "graph" | "planned" | "actual";
+export type TaskLayout = "board" | "grid";
+export type Selection = { kind: "task" | "group" | "milestone"; id: string };
+
+export type ViewState = {
+  tab: DashboardTab;
+  layout: TaskLayout;
+  query: string;
+  group: string;
+  state: string;
+  kind: string;
+  plan: string | null;
+  selected: Selection | null;
+  atom: string | null;
+  detail: boolean;
+  zoom: number;
+  plannedStart: string | null;
+  plannedEnd: string | null;
+  actualStart: string | null;
+  actualEnd: string | null;
+};
+
+export const DEFAULT_VIEW_STATE: ViewState = {
+  tab: "graph", layout: "board", query: "", group: "", state: "", kind: "", plan: null,
+  selected: null, atom: null, detail: false, zoom: 1, plannedStart: null, plannedEnd: null,
+  actualStart: null, actualEnd: null,
+};
+
+const idPattern = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+const tabs = new Set<DashboardTab>(["graph", "planned", "actual"]);
+const taskLayouts = new Set<TaskLayout>(["board", "grid"]);
+
+export function defaultTaskLayout(groupCount: number): TaskLayout {
+  return groupCount === 1 ? "grid" : "board";
+}
+
+export function hasValidLayoutParam(search: string): boolean {
+  return taskLayouts.has(new URLSearchParams(search).get("layout") as TaskLayout);
+}
+const zoomBounds = { min: 0.2, max: 2.5 };
+export const MAX_TIMELINE_SPAN_MS = 10_000 * 365.25 * 24 * 60 * 60 * 1000;
+
+export type ViewStateValidation = {
+  groups?: ReadonlySet<string>;
+  states?: ReadonlySet<string>;
+  kinds?: ReadonlySet<string>;
+  plans?: ReadonlySet<string>;
+  tasks?: ReadonlySet<string>;
+  milestones?: ReadonlySet<string>;
+};
+
+export type ViewStateHistory = {
+  replaceState: (data: unknown, unused: string, url?: string | URL | null) => void;
+};
+
+function validId(value: string | null): string | null {
+  return value && idPattern.test(value) ? value : null;
+}
+
+function validValue(value: string | null, allowed?: ReadonlySet<string>): string {
+  if (!value || !validId(value)) return "";
+  return allowed && !allowed.has(value) ? "" : value;
+}
+
+function validDate(value: string | null): string | null {
+  if (!value || value.length > 64 || Number.isNaN(Date.parse(value))) return null;
+  return new Date(value).toISOString();
+}
+
+function validDateRange(start: string | null, end: string | null): [string | null, string | null] {
+  const normalizedStart = validDate(start);
+  const normalizedEnd = validDate(end);
+  if (!normalizedStart || !normalizedEnd || Date.parse(normalizedStart) >= Date.parse(normalizedEnd) || Date.parse(normalizedEnd) - Date.parse(normalizedStart) > MAX_TIMELINE_SPAN_MS) return [null, null];
+  return [normalizedStart, normalizedEnd];
+}
+
+function parseSelection(value: string | null, validation: ViewStateValidation): Selection | null {
+  if (!value) return null;
+  const match = /^(task|group|milestone):([A-Za-z0-9][A-Za-z0-9_.-]{0,127})$/.exec(value);
+  if (!match) return null;
+  const id = validId(match[2] ?? null);
+  if (!id) return null;
+  if (match[1] === "task" && validation.tasks && !validation.tasks.has(id)) return null;
+  if (match[1] === "group" && validation.groups && !validation.groups.has(id)) return null;
+  if (match[1] === "milestone" && validation.milestones && !validation.milestones.has(id)) return null;
+  return { kind: match[1] as Selection["kind"], id };
+}
+
+export function parseViewState(search: string, validation: ViewStateValidation = {}): ViewState {
+  const params = new URLSearchParams(search.startsWith("?") ? search.slice(1) : search);
+  const rawZoom = Number(params.get("zoom"));
+  const zoom = Number.isFinite(rawZoom) && rawZoom >= zoomBounds.min && rawZoom <= zoomBounds.max ? Math.round(rawZoom * 100) / 100 : DEFAULT_VIEW_STATE.zoom;
+  const tab = tabs.has(params.get("tab") as DashboardTab) ? params.get("tab") as DashboardTab : DEFAULT_VIEW_STATE.tab;
+  const layout = taskLayouts.has(params.get("layout") as TaskLayout) ? params.get("layout") as TaskLayout : defaultTaskLayout(validation.groups?.size ?? 0);
+  const selected = parseSelection(params.get("selected"), validation);
+  const [plannedStart, plannedEnd] = validDateRange(params.get("plannedStart"), params.get("plannedEnd"));
+  const [actualStart, actualEnd] = validDateRange(params.get("actualStart"), params.get("actualEnd"));
+  return {
+    tab,
+    layout,
+    query: (params.get("q") ?? "").slice(0, 200),
+    group: validValue(params.get("group"), validation.groups),
+    state: validValue(params.get("state"), validation.states),
+    kind: validValue(params.get("kind"), validation.kinds),
+    plan: validValue(params.get("plan"), validation.plans) || null,
+    selected,
+    atom: validId(params.get("atom")),
+    detail: ["1", "true"].includes(params.get("detail") ?? "") && selected !== null,
+    zoom,
+    plannedStart,
+    plannedEnd,
+    actualStart,
+    actualEnd,
+  };
+}
+
+export function restoreViewState(search: string, validation: ViewStateValidation = {}, phase: "planning" | "execution" | null = null): ViewState {
+  const state = parseViewState(search, validation);
+  return !hasValidTabParam(search) && phase === "execution" ? { ...state, tab: "actual" } : state;
+}
+
+export function hasValidTabParam(search: string): boolean {
+  const params = new URLSearchParams(search.startsWith("?") ? search.slice(1) : search);
+  return tabs.has(params.get("tab") as DashboardTab);
+}
+
+export function restoreViewStateForNavigation(search: string, validation: ViewStateValidation = {}, phase: "planning" | "execution" | null = null): { state: ViewState; hasExplicitTab: boolean } {
+  return { state: restoreViewState(search, validation, phase), hasExplicitTab: hasValidTabParam(search) };
+}
+
+export function sanitizeViewState(state: ViewState, validation: ViewStateValidation): ViewState {
+  const selected = state.selected && parseSelection(`${state.selected.kind}:${state.selected.id}`, validation);
+  return {
+    ...state,
+    layout: taskLayouts.has(state.layout) ? state.layout : DEFAULT_VIEW_STATE.layout,
+    group: validValue(state.group, validation.groups),
+    state: validValue(state.state, validation.states),
+    kind: validValue(state.kind, validation.kinds),
+    plan: validValue(state.plan, validation.plans) || null,
+    selected,
+    atom: validId(state.atom),
+    detail: state.detail && selected !== null,
+  };
+}
+
+export function serializeViewState(state: ViewState, defaultPlan: string | null = null, defaultTab: DashboardTab = DEFAULT_VIEW_STATE.tab, defaultLayout: TaskLayout = DEFAULT_VIEW_STATE.layout): string {
+  const params = new URLSearchParams();
+  if (state.tab !== defaultTab) params.set("tab", state.tab);
+  if (state.layout !== defaultLayout) params.set("layout", state.layout);
+  if (state.query) params.set("q", state.query);
+  if (state.group) params.set("group", state.group);
+  if (state.state) params.set("state", state.state);
+  if (state.kind) params.set("kind", state.kind);
+  if (state.plan && state.plan !== defaultPlan) params.set("plan", state.plan);
+  if (state.selected) params.set("selected", `${state.selected.kind}:${state.selected.id}`);
+  if (state.atom) params.set("atom", state.atom);
+  if (state.detail && state.selected) params.set("detail", "1");
+  if (state.plannedStart) params.set("plannedStart", state.plannedStart);
+  if (state.plannedEnd) params.set("plannedEnd", state.plannedEnd);
+  if (state.actualStart) params.set("actualStart", state.actualStart);
+  if (state.actualEnd) params.set("actualEnd", state.actualEnd);
+  return params.toString();
+}
+
+export function canonicalViewUrl(currentUrl: string, state: ViewState, defaultPlan: string | null = null, defaultTab: DashboardTab = DEFAULT_VIEW_STATE.tab, defaultLayout: TaskLayout = DEFAULT_VIEW_STATE.layout): string {
+  const url = new URL(currentUrl);
+  const query = serializeViewState(state, defaultPlan, defaultTab, defaultLayout);
+  url.search = query ? `?${query}` : "";
+  url.username = "";
+  url.password = "";
+  url.hash = "";
+  return url.toString();
+}
+
+export function replaceViewStateOn(history: ViewStateHistory, currentUrl: string, state: ViewState, defaultPlan: string | null = null, defaultTab: DashboardTab = DEFAULT_VIEW_STATE.tab, defaultLayout: TaskLayout = DEFAULT_VIEW_STATE.layout): string {
+  const nextUrl = canonicalViewUrl(currentUrl, state, defaultPlan, defaultTab, defaultLayout);
+  history.replaceState(null, "", nextUrl);
+  return nextUrl;
+}
+
+export function replaceViewState(state: ViewState, defaultPlan: string | null = null, defaultTab: DashboardTab = DEFAULT_VIEW_STATE.tab, defaultLayout: TaskLayout = DEFAULT_VIEW_STATE.layout): void {
+  replaceViewStateOn(window.history, window.location.href, state, defaultPlan, defaultTab, defaultLayout);
+}
+
+export function selectionFromState(state: ViewState): Selection | null { return state.selected; }

package/toolkit/skills/node_modules/@xyflow/react/index.js

@@ -0,0 +1,3 @@
+import * as packageExports from "../../../../../node_modules/@xyflow/react/dist/esm/index.js";
+export default packageExports.default;
+export * from "../../../../../node_modules/@xyflow/react/dist/esm/index.js";

package/toolkit/skills/node_modules/@xyflow/react/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@xyflow/react",
+  "version": "12.12.1",
+  "type": "module",
+  "private": true
+}

package/toolkit/skills/node_modules/elkjs/index.js

@@ -0,0 +1,3 @@
+import * as packageExports from "../../../../node_modules/elkjs/lib/main.js";
+export default packageExports.default;
+export * from "../../../../node_modules/elkjs/lib/main.js";

package/toolkit/skills/node_modules/elkjs/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "elkjs",
+  "version": "0.12.1",
+  "type": "module",
+  "private": true
+}

package/toolkit/skills/node_modules/lucide/index.js

@@ -0,0 +1,3 @@
+import * as packageExports from "../../../../node_modules/lucide/dist/esm/lucide.mjs";
+export default packageExports.default;
+export * from "../../../../node_modules/lucide/dist/esm/lucide.mjs";

package/toolkit/skills/node_modules/lucide/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "lucide",
+  "version": "1.65.0",
+  "type": "module",
+  "private": true
+}

package/toolkit/skills/node_modules/moment/index.js

@@ -0,0 +1,3 @@
+import * as packageExports from "../../../../node_modules/moment/moment.js";
+export default packageExports.default;
+export * from "../../../../node_modules/moment/moment.js";

package/toolkit/skills/node_modules/moment/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "moment",
+  "version": "2.31.0",
+  "type": "module",
+  "private": true
+}

package/toolkit/skills/node_modules/playwright/index.js

@@ -0,0 +1,3 @@
+import * as packageExports from "../../../../node_modules/playwright/index.js";
+export default packageExports.default;
+export * from "../../../../node_modules/playwright/index.js";

package/toolkit/skills/node_modules/playwright/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "playwright",
+  "version": "1.64.1",
+  "type": "module",
+  "private": true
+}

package/toolkit/skills/node_modules/react/index.js

@@ -0,0 +1,3 @@
+import * as packageExports from "../../../../node_modules/react/index.js";
+export default packageExports.default;
+export * from "../../../../node_modules/react/index.js";

package/toolkit/skills/node_modules/react/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "react",
+  "version": "19.3.1",
+  "type": "module",
+  "private": true
+}

package/toolkit/skills/node_modules/react-dom/index.js

@@ -0,0 +1,3 @@
+import * as packageExports from "../../../../node_modules/react-dom/index.js";
+export default packageExports.default;
+export * from "../../../../node_modules/react-dom/index.js";

package/toolkit/skills/node_modules/react-dom/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "react-dom",
+  "version": "19.3.1",
+  "type": "module",
+  "private": true
+}

package/toolkit/skills/node_modules/sharp/index.js

@@ -0,0 +1,3 @@
+import * as packageExports from "../../../../node_modules/sharp/dist/index.mjs";
+export default packageExports.default;
+export * from "../../../../node_modules/sharp/dist/index.mjs";

package/toolkit/skills/node_modules/sharp/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "sharp",
+  "version": "0.35.5",
+  "type": "module",
+  "private": true
+}

package/toolkit/skills/node_modules/vis-data/index.js

@@ -0,0 +1,3 @@
+import * as packageExports from "../../../../node_modules/vis-data/peer/esm/vis-data.mjs";
+export default packageExports.default;
+export * from "../../../../node_modules/vis-data/peer/esm/vis-data.mjs";

package/toolkit/skills/node_modules/vis-data/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "vis-data",
+  "version": "8.0.6",
+  "type": "module",
+  "private": true
+}

package/toolkit/skills/node_modules/vis-timeline/index.js

@@ -0,0 +1,3 @@
+import * as packageExports from "../../../../node_modules/vis-timeline/peer/esm/vis-timeline-graph2d.mjs";
+export default packageExports.default;
+export * from "../../../../node_modules/vis-timeline/peer/esm/vis-timeline-graph2d.mjs";

package/toolkit/skills/node_modules/vis-timeline/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "vis-timeline",
+  "version": "8.5.6",
+  "type": "module",
+  "private": true
+}

package/toolkit/skills/node_modules/zod/index.js

@@ -0,0 +1,3 @@
+import * as packageExports from "../../../../node_modules/zod/index.js";
+export default packageExports.default;
+export * from "../../../../node_modules/zod/index.js";

package/toolkit/skills/node_modules/zod/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "zod",
+  "version": "4.6.7",
+  "type": "module",
+  "private": true
+}

package/toolkit/skills/normal-flow/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: normal-flow
+description: "Normal delivery flow ending at local can-open-PR handoff."
+---
+
+# Normal flow
+
+Use only when the owner explicitly selects `normal`.
+
+## Authorization
+
+- Execute local Step 1-4 from `$project-engineering-workflow` without routine confirmation.
+- Local implementation, validation, documentation, and signed-off commits are authorized within scope.
+- Push, PR creation, and PR-stage writable convergence are not authorized.
+
+## Stop condition
+
+Stop only at a real blocker or `Step 4 Ready` (`可开 PR（local）`). Before that handoff, record the Agent's Tier 1..4 review necessity assessment and rationale; there is no categorical rubric. At success report the commits, validation, base sync, review tier, and applicable contract evidence, then state that nothing was pushed and no PR was created.
+
+When the plan declares `empirical_acceptance=required`, Step 4 evidence must include a passed card bound to the current Candidate SHA, acceptance contract, and scenario set. A missing or stale card is a blocker, not an inferred pass. An empirical failure after a comparable pass is diagnosis-only and does not open another Repair Batch or formal review wave.
+
+Step 4 and local review consume only `pre_merge` acceptance evidence bound to the Candidate SHA. `post_merge` evidence waits for a real Merge Receipt and `merge_sha`. `post_deploy` evidence also waits for a structured `deployment_identity` whose source and bound SHA match the Merge Receipt SHA. Local readiness is not Flow Complete, and missing post-merge or deployment identity remains an owner-action blocker.
+
+A later generic continuation may enter the shared workflow PR publication procedure for PR setup, but it does not silently grant writable PR convergence. That requires explicit PR convergence/fast-track intent.

package/toolkit/skills/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@loomhelm/skills",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "bun run --cwd multi-task-flow build",
+    "test": "bun test ./bin/tests ./bin/native-tests",
+    "skills:test": "bun test ./bin/tests ./bin/native-tests",
+    "skills:build": "bun run --cwd multi-task-flow build",
+    "test:core": "bun test ./bin/tests/core",
+    "test:hosting": "bun test ./bin/tests/hosting",
+    "test:flow": "bun test ./bin/tests/flow",
+    "test:plan": "bun test ./bin/tests/plan",
+    "test:docs": "bun test ./bin/tests/docs",
+    "test:workspace": "bun test ./bin/tests/workspace",
+    "test:visual": "bun test ./bin/tests/visual",
+    "test:checks": "bun test ./bin/tests/checks"
+  },
+  "dependencies": {
+    "sharp": "0.35.5",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.4",
+    "typescript": "5.9.3"
+  },
+  "packageManager": "bun@1.4.4",
+  "engines": {
+    "bun": "1.4.4"
+  }
+}

package/toolkit/skills/project-doc-promote/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: project-doc-promote
+description: "Promote stable conclusions from docs/specs or docs/solutions into human-facing project docs."
+---
+
+# Project doc promote
+
+当一次任务已经在 `docs/specs/**` 或 `docs/solutions/**` 中沉淀出稳定结论，且这些结论应该进入**人类项目文档**时使用本 skill。
+
+## 适用场景
+
+- merge-ready 前需要判定 `project_doc_disposition`
+- 某次变更改变了项目级当前真相、结构边界、使用方式或维护方式
+- 同一主题已经被多个碎 spec / solution 反复触碰，应该整理成项目文档
+
+## Inputs（可选）
+
+- `SOURCE_REFS=<spec/solution paths>`
+- `TARGET_HINTS=<现有 docs 路径或章节>`
+- `MODE=check|write`（默认 `write`）
+
+## Hard rules
+
+- 人类项目文档默认优先落在 repo 已建立的人类文档位置：通常是 `docs/**`，但也可以是根 `README.md`、`CONTRIBUTING.md`、`OPERATIONS.md` 等既有入口文档；**目标路径必须尊重项目自身情况**，不要强推统一目录骨架。
+- 优先更新已有项目文档；只有找不到合适承载面时才新建。
+- 只提升稳定项目真相：结构说明、当前行为、维护约定、用户/维护者需要直接理解的结论。
+- 不要把 task log、milestone、review 循环、临时工作上下文原样复制到项目文档。
+- 若本轮确定应该 promotion 但不适合立即落盘，必须返回 `project_doc_disposition=defer`，并附带完整 defer 记录。
+- 历史批量迁移或跨多个来源的集中整理，优先交给 `$docs-migrate MODE=project-docs`；本 skill 更偏单任务收口。
+
+## Workflow
+
+1. **Read source truth**
+   - 读取当前任务相关的 `docs/specs/**`、`docs/solutions/**` 与已有项目文档。
+   - 先判断哪些内容已经是“项目当前真相”，哪些仍只是任务过程。
+
+2. **Choose disposition**
+   - `none`：没有需要进入人类项目文档的新结论。
+   - `update`：已有项目文档需要补充/改写。
+   - `create`：当前没有合适项目文档承载这些稳定结论。
+   - `defer`：已确认需要 promotion，但本轮不能安全落盘；必须写清楚原因、目标与后续动作。
+
+3. **Select target docs**
+   - 优先复用项目现有 overview/reference/architecture/guide/operations 等结构。
+   - 若项目没有清晰入口，选择最小合理目标，并在必要时顺手补一个可发现入口；不要机械创建固定目录。
+
+4. **Write human-facing docs**
+   - 以项目视角重写内容，强调“现在是什么、怎么理解、怎么维护”。
+   - 如需保留工程细节，只保留对人类维护有价值的部分，并在正文中引用 spec / solution 路径而不是复制整段。
+
+5. **Return gate evidence**
+   - `Project文档引用=<paths|none>`
+   - `project_doc_disposition=none|update|create|defer`
+   - `Project文档同步证据=<path@sha|none|未检查>`
+   - `Project文档defer记录=<reason; target; follow_up | none>`
+
+## Promotion heuristics
+
+满足任一条时，默认应 promotion：
+
+- 改变了项目级行为、结构或职责边界
+- 后续人类维护者在不读 spec / solution 的情况下也需要知道
+- 同一主题已经在多个任务里重复出现
+- 当前结论已经稳定，不再只是本次任务的临时上下文
+
+## Output expectations
+
+- 默认返回一句结论 + 紧凑证据块。
+- 若 `MODE=check`，只给 disposition 与建议目标，不写文件。
+- 若 `MODE=write` 且结论为 `update|create`，必须同步写入项目文档并给出 `Project文档同步证据`。

package/toolkit/skills/project-engineering-workflow/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: project-engineering-workflow
+description: "Single source of truth for software delivery flow."
+---
+
+# Project engineering workflow
+
+This is the deep shared module for the direct stages of `normal`, `fast-track`, and `local-merge`. Flow entry skills provide authorization and stop conditions; this skill owns shared stages. `multi-task-flow` is also an active top-level route, but it enters this module only for a task-local direct PR. The 主 Agent（main Agent） owns the task graph, ledger, parent PR, and delivery-unit closeout.
+
+## Interface
+
+Inputs:
+
+- `flow_type=normal|fast-track|local-merge` for a single worker's direct flow
+- `flow_type=multi-task-flow` for parent coordination; its task-local direct PRs use the normal direct stages above
+- `stop_condition`
+- verified repository, branch, PR, and task facts
+
+Outputs:
+
+- current stage
+- the first unfinished applicable gate
+- terminal, blocked, or flow-defined handoff state
+
+Never infer one flow's authorization from another. Top-level multi-task coordination owns its own task facts; this shared module owns only the direct PR stages and gates for an individual task. Internal review/CI sidecar runs remain read-only.
+
+## Shared contracts
+
+Read a reference only when entering its phase:
+
+- live task ownership: `references/active-long-task-short-contract.md`
+- empirical acceptance: `references/empirical-acceptance-short-contract.md`
+- PR diagnosis: `references/pr-diagnosis-short-contract.md`
+- CI tracking: `references/ci-tracking-short-contract.md`
+- tiered local review proof: `references/review-proof-short-contract.md`
+- optional advisory review: `references/advisory-review-short-contract.md`
+- validation receipts: `references/execution-receipt-short-contract.md`
+- pre-merge release decision: `references/release-planning-short-contract.md`
+- post-merge release: `references/release-tracking-short-contract.md`
+- PR publication operation: `references/pr-publication-procedure.md`
+- PR merge operation: `references/pr-merge-procedure.md`
+
+The release decision reference describes runtime behavior at the Step 5C boundary. It does not add a plan schema: ordinary workflow execution reads the target repository policy and current PR facts, returns the Agent default card, and keeps post-merge release facts owned by their existing contract.
+
+The references own delivery criteria and return cards. `${LOOMHELM_TOOLKIT_ROOT:?set packaged toolkit root}/skills/bin/flow_receipt.ts --repo <candidate>` is validation/lifecycle audit infrastructure; it does not schedule, validate, or gate code review. Callers must not restate the references.
+
+The shared workflow owns formal review directly through the shared review-proof contract. There is no separate review-loop Skill in the delivery path.
+
+## Invariants
+
+- `main-agent` is the sole file writer in a direct flow (`main-agent` 是唯一修复者). Sidecars inspect CI, review, Spec, or Solution state; the Release Tracker's only permitted mutation is the explicitly authorized safe rerun defined by its shared contract.
+- Work proceeds in order. A blocker asks one decision-changing question; milestones alone are not approval gates.
+- Every accepted slice follows implement -> relevant validation -> conventional signed-off commit.
+- Current live facts outrank prior prose. Evidence retains its bound identity; target movement during a review round follows PR diagnosis §3.
+- Evidence placement: freeze tracked source, tests, contracts, and docs before final validation. Keep current-SHA results in active flow evidence or SHA-bound external artifacts; result collection leaves the candidate unchanged and starts no review wave. Prepare repository-required tracked records before freeze, naming the implementation/run described. Real repairs invalidate affected evidence; required CI passes on the live PR head.
+- CI gate semantics are owned by `references/ci-tracking-short-contract.md`: keep `policy_state`, `checks_expected`, `ci_evidence`, and `gate_effect` separate. A confirmed `policy_state=none` may produce `CI_NOT_EXPECTED`; a provider policy observation error remains typed evidence and does not by itself become a required-check blocker or a no-check success. The live PR reducer decides the gate after freshness/conflict precedence.
+- Remote mutation, destructive work, and scope expansion remain inside the caller's authorization.
+- Before the first PR publication mutation, derive the runtime `pre_merge_release_route` from current repository and PR facts. An explicit valid repository contract or adopted project-local Policy Skill may expose managed release-label groups. An absent, unsupported, or non-applicable contract resolves to `no-managed-route` with an empty managed-label set; publication continues and the generic flow does not ask the owner to classify the route.
+- Pre-merge route evidence is routing input only. It does not establish `release_expected`, a version, a release tag, or publication. Step 6 keeps its merge-SHA-bound release contract as the sole source of actual release facts.
+- Acceptance is phase-aware: `pre_merge` consumes only Candidate/PR-head evidence; `post_merge` requires a real Merge Receipt and its `merge_sha`; and `post_deploy` additionally requires a structured `deployment_identity` whose source and bound SHA match that merge SHA. Review Readiness, PR convergence, and Step 5C consume only `pre_merge` items.
+- At Step 5C for `merge-ready`, `merge-only`, and `merge+cleanup`, return a decision card covering publish applicability, components, channel, bump rule, predicted version, target identity, and policy source. `merge-ready` may stop after displaying the card; `merge-only` and `merge+cleanup` require explicit owner confirmation including the version expectation before merge continuation. One clear natural-language owner message may provide that confirmation and the continuation request together; callers must not require a fixed reply format or a second action turn. Missing or conflicting policy/facts are `unknown`/blocked; `no-managed-route` is not a no-release decision.
+- A direct flow records an Agent-chosen Tier 1..4 necessity assessment and concise rationale in its current review evidence before PR convergence or terminal local-merge completion. There is no automatic task-category rubric. Tier 1 has no review gate; Tier 2 permits optional advisory review; Tier 3 and Tier 4 require clear evidence produced by read-only sub-agents.
+- `merge-ready / Step 5C Ready` is a pre-merge stop, never Flow Complete. `merge-only` enters post-merge processing only after owner confirmation and an actual Merge Receipt. Missing publish facts or deployment identity is an owner-action blocker; it is not inferred as `not_required`.
+- Direct review's exact six-profile allowlist, lane-local selection, complete-pair owner override scope, runtime-owned errors, and refresh rules belong to `references/review-proof-short-contract.md`; consult it at Review Readiness.
+- A formal review wave must reach terminal structured results for every required lane before the main Agent writes the candidate. The main Agent then applies the finding disposition in `review-proof-short-contract.md`: only an eligible current-PR `In-Scope Review Finding` that meets the priority-aware repair threshold enters one root-cause Repair Batch; a low-priority finding may be recorded as `repair_not_required_low_priority` and accompany a clear review without blocking delivery. An authorized late deferral follows that contract's Late PR resolution and Authorized follow-up delivery rules. A `Design-Returning Review Finding` stops ordinary convergence, and a `Review Observation` is report-only. Intermediate local commits do not create review work, and only the batch's final candidate is reviewed again. If the affected lane set cannot be proven from the Git delta, refresh every required lane.
+- The initial Formal Review Wave permits an optional P2-only repair. From the second wave onward, a low-priority P2 may enter a Repair Batch only with an eligible P0/P1 finding or a qualifying current-Candidate CI failure; P3 and lower findings remain non-blocking. A qualifying CI failure is attributable to in-scope code, tests, or configuration. CI infrastructure failure, flakiness, cancellation, timeout, missing results, and other unavailable evidence remain CI/evidence blockers and do not authorize opportunistic repair. The main Agent reports accepted low-priority findings at the next owner-facing stop. Safety boundaries, required acceptance, and `Design-Returning` findings retain their own hard gates regardless of priority.
+- Formal review has a Review Readiness gate before any lane launch: approved behavior, acceptance, scope and required contracts are settled, no design decision is unresolved, and current-candidate validation plus applicable visual evidence are complete. Tier and profile recommendations in a plan are runtime guidance, not a reviewer schedule. The initial Tier 3/4 coverage is created fresh for the ready Candidate; later Repair Batches refresh only provably affected lanes; the review-proof contract owns conservative full refresh and review-base adoption.
+- When a direct plan declares `empirical_acceptance=required`, the current Candidate must carry a passed, SHA/contract/scenario-bound evidence card from `references/empirical-acceptance-short-contract.md` before local readiness, formal review, Step 5C, or Step 5L. A missing, stale, failed, or unavailable card blocks the gate without creating a Repair Batch.
+
+## Applicability gates
+
+Determine applicability from current evidence; absent relevance means the gate is omitted, not serialized as `unchecked`:
+
+- Spec: applicable when an existing Spec owns the changed behavior or the work introduces/changes a durable contract. New Specs are slug-only and include all three companion files.
+- ADR: applicable only to a hard-to-reverse, non-obvious architecture or boundary decision with a real tradeoff. An existing accepted decision is linked, a new decision is created, and a semantic decision change creates a successor ADR that supersedes the old one. Editorial corrections may update the existing ADR.
+- Solution: applicable when focused lookup finds related reusable knowledge or the work produces a reusable cross-task lesson.
+- Project Docs: applicable when project structure, usage, maintenance, or other human-facing current truth changes.
+- Visual evidence: applicable only when the candidate changes an owner-visible UI, display, or rendered artifact.
+- Release: applicable only after a remote direct or parent PR merge when repository and live facts identify a release surface.
+
+When applicable, invoke the owning Skill and require its positive evidence before advancing. Do not copy its procedure here.
+
+## Stages
+
+### Step 1: execution context
+
+1. Resolve a concrete development base and delivery target: explicit owner ref, unique open-PR base, explicit integration upstream, otherwise repository mainline. A starting SHA alone does not fix the target.
+2. Establish a non-default topic branch through `$git-branch`; a detached/default-branch clean worktree is preparation, not a blocker.
+3. Inspect dirty state. Preserve unrelated user changes; ambiguity that would move or commit them is a blocker.
+4. Inspect target divergence through `$git-sync ACTION=check`; perform alignment only for an explicit requirement or demonstrated integration need under PR diagnosis §3 and current authorization. Result: `Step 1 Ready`.
+
+### Step 2: durable contracts
+
+1. Set `spec_disposition=link|update|create|supersede|not_needed` from the applicability rule.
+2. When applicable, create/update the canonical Spec before implementation; use `$docs-migrate` when only legacy planning material exists.
+3. Set `adr_disposition=link|create|supersede|not_needed`, `adr_refs=<repo-relative path>@<Git blob SHA>|none`, and `adr_resolution=ready|blocked`.
+4. A qualified but unresolved ADR decision is `adr_resolution=blocked` and must be resolved through `$grill-with-docs` before implementation. ADR and Spec have no automatic precedence: a conflict stays blocked until the affected active Spec is explicitly updated.
+5. Perform focused Solution lookup only when task terms or changed paths match actual solution/legacy knowledge content.
+
+Result: `Step 2 Ready` with every applicable contract executable and `adr_resolution=ready`. The ADR fields are flow facts only; do not add them to `flow_receipt.ts`.
+
+### Step 3: delivery slices
+
+For each atomic slice:
+
+1. implement only approved scope;
+2. run covering validation; establish a small behavioral pass before expanding stateful/concurrent work, following the review-readiness contract;
+3. sync an applicable Spec immediately when its contract changed, otherwise at candidate time;
+4. revalidate the frozen ADR path/blob membership at the candidate state with `ADR_REFS="$adr_refs" bash skills/spec-sync/scripts/spec_drift_check.sh ...`; drift returns the flow to Step 2;
+5. commit a complete, reversible slice with English conventional message and `--signoff`.
+
+Before leaving Step 3, settle applicable Solution and Project Docs work. For owner-visible Web components in repositories that already use Storybook, `$storybook-stories` owns the stable component states. Full-page flows prefer a qualified `ui_demo` when available.
+
+Result: `Step 3 Ready`.
+
+### Step 4: local candidate
+
+1. Resolve canonical `BASE_REF`, `BASE_REMOTE`, and PR-capable `BASE_REPO` from live facts; local-merge may omit `BASE_REPO`.
+2. Synchronize verified same-topic upstream changes when needed; inspect the canonical base through `$git-sync ACTION=check` and apply PR diagnosis §3 before choosing alignment. If HEAD changes, rerun affected validation and applicable Spec checks.
+3. If visual evidence applies and local rendering/testing is possible, complete the relevant local test and run `$ui-visual-evidence`. A `视觉比较=一致` result completes this gate without an owner reply. A `视觉比较=需确认` result must show the current comparison and receive a clear natural-language confirmation before PR publication or reuse. That confirmation only accepts the shown screenshots; it does not authorize delivery. The resulting Task Evidence Set is a Step 4B handoff for the current task; if it is missing on resume, rerun Step 4B instead of inferring paths from a Spec/Plan.
+4. If visual evidence applies but no local render/test source is feasible, record the blocker and use the PR publication procedure with `mode=draft-bootstrap` only under existing or explicit delivery authorization to create or reuse a feedback Draft. The Draft must not bind the receipt, start convergence, formal review, required-CI tracking, or merge. Once remote feedback images exist, `$ui-visual-evidence` compares them before normal continuation.
+5. A changed rendered surface or render input returns the work to the visual comparison loop. A metadata-only evidence-persistence commit can proceed without a new owner response only after a current comparison establishes that the inner UI is unchanged.
+6. Freeze the candidate under the evidence-placement invariant; resolve ambiguous uncommitted files before final validation.
+7. Before PR convergence or Step 5L completion, confirm Review Readiness and record the Agent's tier and rationale. For a PR path, `Step 4 Ready` records readiness, current validation, applicable visual evidence, and any required high-risk `pre-PR local proof`; it does not require completed PR-stage structured findings or dispositions. After the exact live PR base/head is bound, the PR path creates its fresh formal evidence; local-merge still completes formal review before Step 5L. Tier 1/2 require only the assessment; optional advisory review does not create a formal proof record. Do not invent a categorical rubric. This is direct task evidence, not a `flow_receipt.ts` record. If empirical acceptance applies, carry its current evidence card and contract digest into the same Candidate evidence before reporting Step 4 Ready. A changed Candidate invalidates the card and returns to validation.
+
+Result: `Step 4 Ready`, meaning local `can-open-PR`; it does not imply an open or merge-ready PR.
+
+### Step 5L: local merge variant
+
+Only `local-merge` enters this branch. Complete the current local base/head assessment and tiered evidence under `references/review-proof-short-contract.md`, then stop at `Step 5L Ready` for owner approval. After approval, refresh base/head and merge locally with `MODE=merge`; do not rebase/reset/force-push implicitly. Cleanup runs only for explicit `merge+cleanup` through `$git-cleanup MODE=local-merge`.
+
+### Step 5: PR variant
+
+`normal` enters only after continuation; `fast-track` enters automatically. Before the publication procedure pushes, creates, updates, or labels a PR, it must silently derive the current pre-merge release route. A missing or non-applicable route becomes `no-managed-route` and performs no release-label mutation; an explicit route may reconcile only release-label groups owned by the target repository, preserving unrelated labels. Use `references/pr-publication-procedure.md` to create/reuse and converge one PR only after every applicable visual comparison is complete and the current task's Step 4B Task Evidence Set handoff is present. Missing handoff is a blocker that requires rerunning Step 4B; never infer it from Spec/Plan history. Unchanged evidence needs no reply, while changed or unavailable comparisons need the owner's clear screenshot confirmation. A live PR must exist before using `merge-ready` or `Step 5C Ready`. `merge-ready` stops at `Step 5C Ready` after the current decision card is displayed; `merge-only` and `merge+cleanup` continue through `references/pr-merge-procedure.md` only after explicit owner confirmation. The confirmation may be one clear natural-language message that also requests continuation; do not prescribe a response template or ask for a separate action message. Apply `references/pr-diagnosis-short-contract.md` §3 before convergence launch. After the exact live PR base/head is bound, start the CI tracker and fresh PR-stage formal review in the same first round and wait for both to reach terminal state before finding disposition, any Repair Batch, or main-agent write, commit, or push. Handle accumulated target movement at that boundary under PR diagnosis §3. Step 5C requires the current CI classification from `references/ci-tracking-short-contract.md` (a proven `CI_GREEN` or `CI_NOT_EXPECTED`, or a live reducer result that keeps a provider observation explicitly unresolved without treating it as a project blocker), applicable validation, visible repository rules, and tiered evidence under `references/review-proof-short-contract.md`. Empirical regressions enter diagnosis-only handling under `references/empirical-acceptance-short-contract.md`; optional advisory review follows its shared contract.
+
+Draft bootstrap is optional for multi-slice or slow-CI work after one complete tested slice. For UI work it is additionally the only fallback when no local evidence source exists; that Draft remains feedback-only until its remote feedback has completed the same visual comparison gate. It freezes approved Goals, not unfinished implementation, and returns to Step 3.
+
+### Step 6: post-merge
+
+When the source PR carries an authorized late-review handoff, finish its selected merge-scope obligations first, then run the review-proof contract's Authorized follow-up delivery through an independent `$fast-flow` to Step 5C Ready. Keep the source and follow-up identities, budgets and merge approvals distinct; an unmerged source retains its pending handoff at the existing owner gate.
+
+Only merged direct or parent PRs enter. Once live PR facts confirm the merge and actual merge SHA (the Merge Receipt), start merge-SHA target CI tracking and independently evaluate release applicability and begin any authorized preparation that does not depend on CI terminal success. Follow the target repository's gates before dispatch; do not delay either track for unrelated merge-scope cleanup. The ledger's terminal post-merge receipt is recorded later, after CI and release finality; it is not the launch prerequisite. `release_expected` exists only as this post-merge fact. Expected releases must reach actual publication or a reported failed/incomplete state; CI or release-intent snapshots and pre-merge route evidence are not publication proof. Child PRs return their merge facts to their owning coordinator; the parent PR remains the final owner-facing surface.
+
+For a task that owns an Agent VM, invoke `$agent-vm`'s Finish policy after merge to decide whether VM work remains and verify closure when it does not. Release may precede remote-only CI/release waits; continue those waits under their existing contracts. Keep the VM when post-merge work still needs it.
+
+## Recovery and output
+
+- `$flow-continue` restores the locked flow, ownership promise, latest anchor, then live facts, and resumes the first unfinished applicable gate.
+- Owner-facing output starts with the outcome and next action. Machine fields appear only for blockers, non-terminal recovery, or explicit audit.
+- A live long task remains owned until terminal, actionable blocker, owner decision, or its contract's exhausted wait budget.
+- When the task owns an Agent VM, use `$agent-vm`'s Retain and renew policy at phase/readiness handoffs and its Finish policy at actual task completion or cancellation, including work without a PR. These policies govern the current session only; a flow stop or intermediate reply does not itself establish task completion. Report the retention purpose/deadline or observed closure outcome through that Skill.
+
+## Entry map
+
+- `normal`: `$normal-flow`
+- `fast-track`: `$fast-flow`
+- `local-merge`: `$local-merge-flow`
+- resume: `$flow-continue`
+- PR convergence: `references/pr-publication-procedure.md`
+- PR merge: `references/pr-merge-procedure.md`