@zhchxiao123/dsh-devflow 0.1.0 → 0.2.0

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/devflow/devflow/README.md
-README.md: 81a9147155d182c5fea6e7b2aebc3c6dd1cf1b9c
-README.zh.md: 8613bd2b93adf3b35f59ef39b4e61be1d1927813
+README.md: 93ad295689a8ebb5071ee844f29db6770ed1e5fa
+README.zh.md: ef5e88a7ecbd690af7fb2346a51de078b3a37d21

package/README.md

@@ -19,24 +19,26 @@ Every operation carries an explicit **devflow root** dimension: reads take an op
 | `resolveCreate(request)` | Explicit defaulting: turns a caller `CreateRequest` (title, Markdown body, optional slug, actor, optional parent, optional root) into the fully specified `CreateSpec` — the slug derived from the title when omitted, the root resolved, plus the creation timestamp. |
 | `create(spec)` | Creates one card: parent validation → sequence-number allocation (continuing past archived cards, so an id is never reissued) → exclusive directory creation → the journal's first `created` entry (the only commit point) → projection write → `devflow/card-created`. Domain rejections resolve `ok: false` with a stable code (`empty-title`, `invalid-slug`, `exists`, `unknown-parent`, `nested-parent`, `parent-settled`); only infrastructure failures reject. |
 | `resolve(request)` | Explicit defaulting: turns a caller `TransitionRequest` into the fully specified `TransitionSpec` with its resolved root and commit timestamp. |
-| `transition(spec)` | Commits one move: revision CAS → edge check → `devflow/transition` waterfall → journal append (the only commit point) → projection rewrite → `devflow/stage-changed`. Domain rejections resolve `ok: false` with a stable code (`revision-mismatch`, `illegal-edge`, `reason-required`, `vetoed`); only infrastructure failures reject. |
-| `claim(id, owner, options?)` | Takes the card's exclusive lease; a held lease resolves with the current holder, unless `options.staleAfterMs` marks its heartbeat lapsed — then the lease is taken over with a journaled `claim-expired` entry. |
-| `attachArtifact(request)` | Registers a stage deliverable in the journal against the current stage; rejected while `blocked` or `done`, with the same revision check as `transition`. |
+| `transition(spec)` | Commits one move: revision CAS → edge check → `devflow/transition` waterfall → cross-process commit lock and journal append (the only commit point) → projection rewrite → `devflow/stage-changed`. Domain rejections resolve `ok: false` with a stable code (`revision-mismatch`, `illegal-edge`, `reason-required`, `vetoed`, `write-contended`); only infrastructure failures reject. |
+| `claim(id, owner, options?)` | Takes the card's exclusive lease; a held lease resolves with the current holder, unless `options.staleAfterMs` marks its heartbeat lapsed — then one concurrent caller journals `claim-expired` and replaces the lease under the commit lock. Lock contention leaves the observed holder in place. |
+| `attachArtifact(request)` | Registers a stage deliverable in the journal against the current stage, in one of two mutually exclusive forms: the reference form records a `path` the caller already wrote under the card directory, and the store-written form hands over `kind` plus `content` for the implementation to write `artifacts/<rev>-<kind>.md` itself before the journal append — still the only commit point, so a lost commit registers nothing and its unreferenced file is overwritten by a same-revision retry. Registrations are immutable: the newest record of one kind is that kind's current content. Rejected while `blocked` or `done`, with `revision-mismatch`, `illegal-edge`, `invalid-kind`, or `write-contended`; the outcome carries the registered `ArtifactRecord`. |
 | `archiveDone(root?)` | Moves every archivable `done` card of one root out of the active set into that root's archive, keyed by the month of its last journal entry; a decomposed requirement archives as one family (a done child waits for its parent, then joins the parent's month bucket). Archived cards leave `list` but keep their complete journal. Returns the archived ids in id order. |
 
-Current state always comes from journal replay; a card file's frontmatter is a rebuildable projection. Implementations must fail a read loudly on a structurally invalid journal (naming file and line), warn-and-override on projection drift, and publish state and notifications only after the journal committed. Legal edges (`isLegalTransition`): the pipeline order, rework from `reviewing`/`testing` back to `developing`, `blocked` entry from any non-terminal location, and recovery only to the exact interrupted stage. A rework edge (`isReworkEdge`) without a `reason` is rejected `reason-required`, so the next holder always learns what to fix.
+Current state always comes from journal replay; a card file's frontmatter is a rebuildable projection. Implementations must fail a read loudly on a structurally invalid journal (naming file and line), warn-and-override on projection drift, and publish state and notifications only after the journal committed. Legal edges (`isLegalTransition`): the pipeline order, rework from `reviewing`/`testing` back to whichever stage owns the fault — `developing` for the implementation, `designing` for the design — `blocked` entry from any non-terminal location, and recovery only to the exact interrupted stage. `done` is terminal in both directions: a delivered card is not reopened, because its history may already have been archived and the seam has no operation that reads the archive. A rework edge (`isReworkEdge`) without a `reason` is rejected `reason-required`, so the next holder always learns what to fix.
 
 ## Stages and journal
 
 `DevStage` is the closed union `draft | designing | ready | developing | reviewing | testing | done`; `blocked` is a bypass location that remembers the stage it interrupted (`CardLocation = DevStage | 'blocked'`). The journal entry union is `created | transition | artifact | claim-expired`, decoded by `decodeJournalEntry` (the durable-boundary validator) and folded by `foldJournal`, which enforces: contiguous revisions from 1, `created` first and only first, transitions departing the current location, and blocked recovery returning exactly to the remembered stage.
 
+An `artifact` entry may carry a `kind` naming the deliverable of a store-written registration; entries without one decode and fold exactly as before. `foldArtifactRecords` derives every registration as an `ArtifactRecord` (path, optional kind, journal revision, registering stage), surfaced as `DevCard.artifactRecords` with `DevCard.artifacts` remaining its path projection. A `transition` entry's `gate` records what permitted the move: the human approval signature (`approvedBy`) and/or the gate verdicts (`checks`) a policy listener attached to its permitting waterfall decision — both fields optional, so existing `{ approvedBy }` entries decode unchanged.
+
 A requirement too big for one card becomes a **parent card plus one child card per slice**. The edge is the `created` entry's `parent`, so it is fixed at creation, replayable, and never re-pointed; `foldJournal` surfaces it as `DevCard.parent` and the frontmatter `parent:` is its projection. The breakdown is one level deep — a card carrying `parent` is never itself a parent — and parent and children always share a root. Which cards may take children is the provider's creation-time decision (`unknown-parent`, `nested-parent`, `parent-settled`); the seam holds no rule about how a parent's own stage relates to its children's.
 
 ## Events
 
 | Event | Mode | Meaning |
 |---|---|---|
-| `devflow/transition` | `waterfall` | Single-decision pipeline before the commit, dispatched with the complete `TransitionAttempt` (spec plus departure); a policy listener that owns the decision returns `{ allowed: false, reason }` without calling `next()`. [`dsh-devflow-gates`](../devflow-gates/README.md) runs command policies here. |
+| `devflow/transition` | `waterfall` | Single-decision pipeline before the commit, dispatched with the complete `TransitionAttempt` (spec plus departure); a policy listener that owns the decision returns `{ allowed: false, reason }` without calling `next()`, and a permitting decision may carry `approvedBy` and `checks`, recorded as the committed entry's `gate`. [`dsh-devflow-gates`](../devflow-gates/README.md) runs command policies here. |
 | `devflow/card-created` | `emit` | A new card entered the active set: its journal committed the first `created` entry. |
 | `devflow/stage-changed` | `emit` | A card settled at a new location after a committed transition. |
 

package/README.zh.md

@@ -19,24 +19,26 @@
 | `resolveCreate(request)` | 显式默认值补全：把调用方的 `CreateRequest`（标题、Markdown 正文、可选 slug、actor、可选 parent、可选 root）变成完全确定的 `CreateSpec`——slug 省略时由标题推导，root 解析定型，并盖上创建时间戳。 |
 | `create(spec)` | 创建一张卡：父卡校验 → 顺序号分配（越过归档卡续排，id 永不复用）→ 独占目录创建 → journal 首条 `created`（唯一提交点）→ 投影写入 → `devflow/card-created`。领域拒绝以稳定 code（`empty-title`、`invalid-slug`、`exists`、`unknown-parent`、`nested-parent`、`parent-settled`）解析为 `ok: false`；仅基础设施故障才 reject。 |
 | `resolve(request)` | 显式默认值补全：把调用方的 `TransitionRequest` 变成完全确定的 `TransitionSpec`，带已解析的 root 与提交时间戳。 |
-| `transition(spec)` | 提交一次移动：revision CAS → 边合法性 → `devflow/transition` waterfall → journal 追加（唯一提交点）→ 投影重写 → `devflow/stage-changed`。领域拒绝以稳定 code（`revision-mismatch`、`illegal-edge`、`reason-required`、`vetoed`）解析为 `ok: false`；仅基础设施故障才 reject。 |
-| `claim(id, owner, options?)` | 取得卡片的独占租约；租约已被持有时解析出当前持有者——除非 `options.staleAfterMs` 判定其心跳已过期，此时接管租约并以 `claim-expired` 条目入 journal。 |
-| `attachArtifact(request)` | 按当前阶段在 journal 登记一个阶段产物；`blocked` 或 `done` 时拒绝，revision 检查与 `transition` 相同。 |
+| `transition(spec)` | 提交一次移动：revision CAS → 边合法性 → `devflow/transition` waterfall → 跨进程 commit lock 与 journal 追加（唯一提交点）→ 投影重写 → `devflow/stage-changed`。领域拒绝以稳定 code（`revision-mismatch`、`illegal-edge`、`reason-required`、`vetoed`、`write-contended`）解析为 `ok: false`；仅基础设施故障才 reject。 |
+| `claim(id, owner, options?)` | 取得卡片的独占租约；租约已被持有时解析出当前持有者——除非 `options.staleAfterMs` 判定其心跳已过期，此时一个并发调用者在 commit lock 下写入 `claim-expired` 并替换租约。锁竞争让观察到的持有者保持原位。 |
+| `attachArtifact(request)` | 按当前阶段在 journal 登记一个阶段产物，两种互斥形式二选一：引用形式登记调用方已写在卡目录下的 `path`；代写形式交出 `kind` 与 `content`，由实现在 journal 追加之前自行写入 `artifacts/<rev>-<kind>.md`——追加仍是唯一提交点，输掉提交则什么也没登记，其无引用文件会被同 revision 的重试覆盖。登记不可变：同一 kind 最新的记录就是该 kind 的当前内容。`blocked` 或 `done` 时拒绝，并可能返回 `revision-mismatch`、`illegal-edge`、`invalid-kind` 或 `write-contended`；结果携带登记的 `ArtifactRecord`。 |
 | `archiveDone(root?)` | 把一个根中每张可归档的 `done` 卡按其最后一条 journal 的月份移出活跃集合、归入该根的档案；拆分需求以族为单位归档（已完成的子卡等待父卡，随后并入父卡的月份桶）。归档卡从 `list` 消失但保留完整 journal。按 id 顺序返回归档的 id。 |
 
-当前状态永远来自 journal 回放；卡片文件的 frontmatter 是可重建的投影。实现必须在 journal 结构非法时读取即失败（指明文件与行号），在投影漂移时告警并覆盖，且只在 journal 提交之后发布状态与通知。合法边（`isLegalTransition`）：流水线顺序、`reviewing`/`testing` 打回 `developing`、任意非终态进入 `blocked`、且只能恢复到被打断的那个阶段。无 `reason` 的打回边（`isReworkEdge`）以 `reason-required` 拒绝，下一个持有者永远知道要修什么。
+当前状态永远来自 journal 回放；卡片文件的 frontmatter 是可重建的投影。实现必须在 journal 结构非法时读取即失败（指明文件与行号），在投影漂移时告警并覆盖，且只在 journal 提交之后发布状态与通知。合法边（`isLegalTransition`）：流水线顺序、`reviewing`/`testing` 打回实际拥有缺陷的阶段——实现问题回 `developing`，设计问题回 `designing`——任意非终态进入 `blocked`、且只能恢复到被打断的那个阶段。`done` 双向都是终态：已交付卡片可能已经归档，而缝没有读取归档的操作。无 `reason` 的打回边（`isReworkEdge`）以 `reason-required` 拒绝，下一个持有者永远知道要修什么。
 
 ## 阶段与 journal
 
 `DevStage` 是闭合联合 `draft | designing | ready | developing | reviewing | testing | done`；`blocked` 是记住被打断阶段的旁路位置（`CardLocation = DevStage | 'blocked'`）。journal 条目联合为 `created | transition | artifact | claim-expired`，由 `decodeJournalEntry`（持久化边界校验器）解码、`foldJournal` 折叠，后者强制：revision 从 1 连续、`created` 必须且只能是首条、transition 必须从当前位置出发、blocked 恢复必须回到被记住的阶段。
 
+`artifact` 条目可以携带 `kind`，指名一次代写登记的产物种类；不带 kind 的条目解码与折叠与从前完全一致。`foldArtifactRecords` 把每次登记折出为一条 `ArtifactRecord`（路径、可选 kind、journal revision、登记阶段），以 `DevCard.artifactRecords` 呈现，`DevCard.artifacts` 仍是其路径投影。`transition` 条目的 `gate` 记录放行这次移动的事实：策略监听器附在放行的 waterfall 决策上的人工审批签名（`approvedBy`）与/或门禁裁决（`checks`）——两个字段皆可选，既有的 `{ approvedBy }` 条目解码不变。
+
 一张卡装不下的大需求拆成**一张父卡加每个切片一张子卡**。这条边就是 `created` 条目的 `parent`，因此创建时即固定、可回放、永不改指；`foldJournal` 把它折出为 `DevCard.parent`，frontmatter 的 `parent:` 是其投影。拆分只有一层——带 `parent` 的卡自身永远不会成为父卡——父卡与子卡始终同根。哪些卡可以接子卡是 provider 的创建期决策（`unknown-parent`、`nested-parent`、`parent-settled`）；缝本身不持有"父卡阶段与子卡阶段如何关联"的任何规则。
 
 ## 事件
 
 | 事件 | 模式 | 含义 |
 |---|---|---|
-| `devflow/transition` | `waterfall` | 提交前的单决策管线，以完整 `TransitionAttempt`（spec 加出发位置）分发；拥有决策的策略监听器不调 `next()` 直接返回 `{ allowed: false, reason }`。[`dsh-devflow-gates`](../devflow-gates/README.zh.md) 在此运行命令策略。 |
+| `devflow/transition` | `waterfall` | 提交前的单决策管线，以完整 `TransitionAttempt`（spec 加出发位置）分发；拥有决策的策略监听器不调 `next()` 直接返回 `{ allowed: false, reason }`，放行的决策可携带 `approvedBy` 与 `checks`，记入已提交条目的 `gate`。[`dsh-devflow-gates`](../devflow-gates/README.zh.md) 在此运行命令策略。 |
 | `devflow/card-created` | `emit` | 一张新卡进入活跃集合：其 journal 提交了首条 `created`。 |
 | `devflow/stage-changed` | `emit` | 一次已提交的流转后，卡片落在新位置。 |
 

package/lib/index.js

@@ -36,14 +36,31 @@ function isCardLocation(value) {
 function DevflowCardId(value) {
 	return value;
 }
-/** Forward and rework edges of the pipeline; `blocked` legality lives in {@link isLegalTransition}. */
+/**
+* Forward and rework edges of the pipeline; `blocked` legality lives in
+* {@link isLegalTransition}.
+*
+* Review and verification send a card back to whichever stage owns the fault:
+* `developing` when the implementation is wrong, `designing` when the design
+* is. Without the second, design rework happens on a card labelled
+* `developing`, and the board stops answering the one question it exists to
+* answer.
+*/
 const FLOW = {
 	draft: ["designing"],
 	designing: ["ready"],
 	ready: ["developing"],
 	developing: ["reviewing"],
-	reviewing: ["testing", "developing"],
-	testing: ["done", "developing"],
+	reviewing: [
+		"testing",
+		"developing",
+		"designing"
+	],
+	testing: [
+		"done",
+		"developing",
+		"designing"
+	],
 	done: []
 };
 /**
@@ -68,10 +85,11 @@ function isLegalTransition(from, to, blockedFrom) {
 * require a recorded `reason` so the next holder knows what to fix.
 * @param from - the departing location.
 * @param to - the target location.
-* @returns `true` for `reviewing -> developing` and `testing -> developing`.
+* @returns `true` for a move from `reviewing` or `testing` back to
+*   `developing` or `designing`.
 */
 function isReworkEdge(from, to) {
-	return to === "developing" && (from === "reviewing" || from === "testing");
+	return (to === "developing" || to === "designing") && (from === "reviewing" || from === "testing");
 }
 //#endregion
 //#region packages/devflow/src/journal.ts
@@ -128,7 +146,8 @@ function decodeJournalEntry(value) {
 				type: "artifact",
 				path: entry.path,
 				stage: entry.stage,
-				...entry.by !== void 0 ? { by: decodeActor(entry.by) } : {}
+				...entry.by !== void 0 ? { by: decodeActor(entry.by) } : {},
+				...decodeOptionalString(entry, "kind")
 			};
 		case "claim-expired":
 			if (entry.previousOwner === void 0) throw new Error("claim-expired field \"previousOwner\" is required");
@@ -190,11 +209,48 @@ function foldJournal(entries) {
 	}
 	return state;
 }
+/**
+* Derive the artifact registrations of a decoded journal, in registration
+* order. Kept beside {@link foldJournal} — whose `artifacts` is this list's
+* path projection — so every consumer derives identical records; an entry
+* without a `kind` yields a record without one.
+* @param entries - decoded entries in file order.
+* @returns the artifact records, oldest first.
+*/
+function foldArtifactRecords(entries) {
+	const records = [];
+	for (const entry of entries) {
+		if (entry.type !== "artifact") continue;
+		records.push({
+			path: entry.path,
+			...entry.kind !== void 0 ? { kind: entry.kind } : {},
+			rev: entry.rev,
+			stage: entry.stage
+		});
+	}
+	return records;
+}
 function decodeGate(value) {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("transition field \"gate\" must be a JSON object");
 	const gate = value;
-	if (gate.approvedBy === void 0) throw new Error("transition field \"gate\" requires \"approvedBy\"");
-	return { approvedBy: decodeActor(gate.approvedBy) };
+	if (gate.approvedBy === void 0 && gate.checks === void 0) throw new Error("transition field \"gate\" requires \"approvedBy\" or \"checks\"");
+	return {
+		...gate.approvedBy !== void 0 ? { approvedBy: decodeActor(gate.approvedBy) } : {},
+		...gate.checks !== void 0 ? { checks: decodeGateChecks(gate.checks) } : {}
+	};
+}
+function decodeGateChecks(value) {
+	if (!Array.isArray(value)) throw new Error("transition field \"gate.checks\" must be an array");
+	return value.map((check) => {
+		if (typeof check !== "object" || check === null || Array.isArray(check)) throw new Error("gate check must be a JSON object");
+		const record = check;
+		if (record.verdict !== "allowed") throw new Error(`gate check field "verdict" must be "allowed" (got ${JSON.stringify(record.verdict)})`);
+		return {
+			by: decodeActor(record.by),
+			verdict: "allowed",
+			...decodeOptionalString(record, "summary")
+		};
+	});
 }
 function decodeActor(value) {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("actor must be a JSON object");
@@ -237,6 +293,88 @@ function decodeOptionalString(record, key) {
 * model-facing tools belong to `@zhchxiao123/dsh-devflow-tool`.
 * @module @zhchxiao123/dsh-devflow
 */
+/** JSON Schema for the Definition-owned artifact registration record. */
+const ARTIFACT_RECORD_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		path: {
+			type: "string",
+			required: true
+		},
+		kind: { type: "string" },
+		rev: {
+			type: "integer",
+			required: true
+		},
+		stage: {
+			type: "string",
+			required: true,
+			enum: [...DEV_STAGES]
+		}
+	}
+};
+/** JSON Schema for one public artifact transition inspection. */
+const ARTIFACT_TRANSITION_INSPECTION_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		from: {
+			type: "string",
+			required: true,
+			enum: [...DEV_STAGES, "blocked"]
+		},
+		to: {
+			type: "string",
+			required: true,
+			enum: [...DEV_STAGES, "blocked"]
+		},
+		requirements: {
+			type: "array",
+			required: true,
+			items: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					kind: {
+						type: "string",
+						required: true
+					},
+					status: {
+						type: "string",
+						required: true,
+						enum: [
+							"missing",
+							"malformed",
+							"satisfied"
+						]
+					},
+					spec: {
+						type: "object",
+						required: true,
+						additionalProperties: false,
+						properties: {
+							frontmatter: {
+								type: "array",
+								items: { type: "string" }
+							},
+							sections: {
+								type: "array",
+								items: { type: "string" }
+							}
+						}
+					},
+					artifact: ARTIFACT_RECORD_SCHEMA,
+					defects: {
+						type: "array",
+						required: true,
+						items: { type: "string" }
+					}
+				}
+			}
+		}
+	}
+};
 /**
 * Abstract task-card store registered as `ctx.devflow` (one implementation per
 * context; loading a second throws, cordis' standard duplicate-service
@@ -320,6 +458,6 @@ function rootOfCwd(cwd) {
 	return cwd === void 0 ? void 0 : join(cwd, ".devflow");
 }
 //#endregion
-export { DEV_STAGES, DevflowCardId, DevflowStore, DevflowStore as default, decodeJournalEntry, foldJournal, isCardLocation, isDevStage, isLegalTransition, isReworkEdge };
+export { ARTIFACT_RECORD_SCHEMA, ARTIFACT_TRANSITION_INSPECTION_SCHEMA, DEV_STAGES, DevflowCardId, DevflowStore, DevflowStore as default, decodeJournalEntry, foldArtifactRecords, foldJournal, isCardLocation, isDevStage, isLegalTransition, isReworkEdge };
 
 //# sourceMappingURL=index.js.map

package/lib/types/index.d.ts

@@ -10,8 +10,115 @@ import { Context, Service } from '@deepseek-ai/cordis';
 import type { ArtifactRequest, ArtifactResult, CardFilter, ClaimHolder, ClaimOptions, ClaimResult, CreateRequest, CreateResult, CreateSpec, DevActor, DevCard, DevCardDetail, DevflowCardId, DevflowJournalEntry, TransitionRequest, TransitionResult, TransitionSpec } from './types.ts';
 export type * from './types.ts';
 export { DEV_STAGES, DevflowCardId, isCardLocation, isDevStage, isLegalTransition, isReworkEdge } from './stages.ts';
-export { decodeJournalEntry, foldJournal } from './journal.ts';
+export { decodeJournalEntry, foldArtifactRecords, foldJournal } from './journal.ts';
 export type { JournalFoldState } from './journal.ts';
+/** JSON Schema for the Definition-owned artifact registration record. */
+export declare const ARTIFACT_RECORD_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly path: {
+            readonly type: "string";
+            readonly required: true;
+        };
+        readonly kind: {
+            readonly type: "string";
+        };
+        readonly rev: {
+            readonly type: "integer";
+            readonly required: true;
+        };
+        readonly stage: {
+            readonly type: "string";
+            readonly required: true;
+            readonly enum: readonly ["draft", "designing", "ready", "developing", "reviewing", "testing", "done"];
+        };
+    };
+};
+/** JSON Schema for one public artifact transition inspection. */
+export declare const ARTIFACT_TRANSITION_INSPECTION_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly from: {
+            readonly type: "string";
+            readonly required: true;
+            readonly enum: readonly ["draft", "designing", "ready", "developing", "reviewing", "testing", "done", "blocked"];
+        };
+        readonly to: {
+            readonly type: "string";
+            readonly required: true;
+            readonly enum: readonly ["draft", "designing", "ready", "developing", "reviewing", "testing", "done", "blocked"];
+        };
+        readonly requirements: {
+            readonly type: "array";
+            readonly required: true;
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly kind: {
+                        readonly type: "string";
+                        readonly required: true;
+                    };
+                    readonly status: {
+                        readonly type: "string";
+                        readonly required: true;
+                        readonly enum: readonly ["missing", "malformed", "satisfied"];
+                    };
+                    readonly spec: {
+                        readonly type: "object";
+                        readonly required: true;
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly frontmatter: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly sections: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                    };
+                    readonly artifact: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly path: {
+                                readonly type: "string";
+                                readonly required: true;
+                            };
+                            readonly kind: {
+                                readonly type: "string";
+                            };
+                            readonly rev: {
+                                readonly type: "integer";
+                                readonly required: true;
+                            };
+                            readonly stage: {
+                                readonly type: "string";
+                                readonly required: true;
+                                readonly enum: readonly ["draft", "designing", "ready", "developing", "reviewing", "testing", "done"];
+                            };
+                        };
+                    };
+                    readonly defects: {
+                        readonly type: "array";
+                        readonly required: true;
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+            };
+        };
+    };
+};
 declare module '@deepseek-ai/cordis' {
     interface Context {
         devflow: DevflowStore;
@@ -91,25 +198,43 @@ export declare abstract class DevflowStore extends Service {
      * `devflow/transition` waterfall, the journal append (the only commit
      * point), the projection rewrite, then `devflow/stage-changed`. State and
      * notifications publish only after the journal committed.
+     *
+     * The waterfall's gate commands put real time between those checks and the
+     * append, so implementations must re-establish the checked revision at the
+     * append itself, under an exclusion another process observes. A card that
+     * moved in that window resolves `revision-mismatch`; a card whose commit
+     * stayed excluded resolves `write-contended` with nothing written.
      * @param spec - a resolved spec from {@link resolve}, never a raw request.
      * @returns the outcome; domain rejections resolve with `ok: false`.
      */
     abstract transition(spec: TransitionSpec): Promise<TransitionResult>;
     /**
-     * Take the card's exclusive lease.
+     * Take the card's exclusive lease. A stale takeover journals the eviction
+     * under the same cross-process commit exclusion as transitions and artifact
+     * registration, so concurrent takeover attempts grant at most one holder.
      * @param id - the card to claim.
      * @param owner - the prospective holder, recorded in the lease.
      * @param options - staleness takeover policy and root; omitted never takes
      *   over and uses the implementation's default root.
-     * @returns the live handle, or the current holder when the lease is taken.
+     * @returns the live handle, or a holder read from the lease. On journal-commit
+     *   contention that holder was observed before trying the lock, not freshly
+     *   established as the current owner.
      */
     abstract claim(id: DevflowCardId, owner: DevActor, options?: ClaimOptions): Promise<ClaimResult>;
     /**
      * Register a stage deliverable in the card's journal against its current
-     * stage. A blocked card cannot register artifacts, and the revision check
-     * mirrors {@link transition}.
-     * @param request - card, artifact path, expected revision, and actor.
-     * @returns the outcome; domain rejections resolve with `ok: false`.
+     * stage, in one of two mutually exclusive forms: the reference form records
+     * a `path` the caller already wrote under the card directory, and the
+     * store-written form hands over `kind` plus `content` for the
+     * implementation to write `artifacts/<rev>-<kind>.md` itself before the
+     * journal append — which stays the only commit point, so a registration
+     * that loses the commit registers nothing and its unreferenced file is
+     * overwritten by a same-revision retry. Registrations are immutable: the
+     * newest record of one kind is that kind's current content. A blocked or
+     * done card cannot register artifacts, the revision check mirrors
+     * {@link transition}, and an ill-formed kind resolves `invalid-kind`.
+     * @param request - card, expected revision, actor, and the artifact reference or content.
+     * @returns the outcome carrying the registered record; domain rejections resolve with `ok: false`.
      */
     abstract attachArtifact(request: ArtifactRequest): Promise<ArtifactResult>;
     /**

package/lib/types/index.js

@@ -8,8 +8,52 @@
  */
 import { join } from 'node:path';
 import { Service } from '@deepseek-ai/cordis';
+import { DEV_STAGES } from "./stages.js";
 export { DEV_STAGES, DevflowCardId, isCardLocation, isDevStage, isLegalTransition, isReworkEdge } from "./stages.js";
-export { decodeJournalEntry, foldJournal } from "./journal.js";
+export { decodeJournalEntry, foldArtifactRecords, foldJournal } from "./journal.js";
+/** JSON Schema for the Definition-owned artifact registration record. */
+export const ARTIFACT_RECORD_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        path: { type: 'string', required: true },
+        kind: { type: 'string' },
+        rev: { type: 'integer', required: true },
+        stage: { type: 'string', required: true, enum: [...DEV_STAGES] },
+    },
+};
+/** JSON Schema for one public artifact transition inspection. */
+export const ARTIFACT_TRANSITION_INSPECTION_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        from: { type: 'string', required: true, enum: [...DEV_STAGES, 'blocked'] },
+        to: { type: 'string', required: true, enum: [...DEV_STAGES, 'blocked'] },
+        requirements: {
+            type: 'array',
+            required: true,
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    kind: { type: 'string', required: true },
+                    status: { type: 'string', required: true, enum: ['missing', 'malformed', 'satisfied'] },
+                    spec: {
+                        type: 'object',
+                        required: true,
+                        additionalProperties: false,
+                        properties: {
+                            frontmatter: { type: 'array', items: { type: 'string' } },
+                            sections: { type: 'array', items: { type: 'string' } },
+                        },
+                    },
+                    artifact: ARTIFACT_RECORD_SCHEMA,
+                    defects: { type: 'array', required: true, items: { type: 'string' } },
+                },
+            },
+        },
+    },
+};
 /**
  * Abstract task-card store registered as `ctx.devflow` (one implementation per
  * context; loading a second throws, cordis' standard duplicate-service

package/lib/types/invariant.js

@@ -14,7 +14,7 @@ const install = (ctx, fail) => {
     const lastRevision = new Map();
     const children = new Set();
     // Cards from different roots may share an id; the stream relations hold
-    // per root + id, the same key every store and driver book-keeping uses.
+    // per root + id, the same key every store bookkeeping path uses.
     const key = (card) => `${card.root} ${card.id}`;
     ctx.on('devflow/card-created', (card) => {
         if (card.stage !== 'draft' || card.stageRevision !== 1) {

package/lib/types/journal.d.ts

@@ -6,7 +6,7 @@
  * @module @zhchxiao123/dsh-devflow/src/journal
  */
 import { DevflowCardId } from './stages.ts';
-import type { CardLocation, DevStage, DevflowJournalEntry } from './types.ts';
+import type { ArtifactRecord, CardLocation, DevStage, DevflowJournalEntry } from './types.ts';
 /** Card state derived by {@link foldJournal}; the read-side authority. */
 export interface JournalFoldState {
     /** Current location after the last entry. */
@@ -43,4 +43,13 @@ export declare function decodeJournalEntry(value: unknown): DevflowJournalEntry;
  * @throws {Error} naming the first violated invariant and its entry revision.
  */
 export declare function foldJournal(entries: readonly DevflowJournalEntry[]): JournalFoldState;
+/**
+ * Derive the artifact registrations of a decoded journal, in registration
+ * order. Kept beside {@link foldJournal} — whose `artifacts` is this list's
+ * path projection — so every consumer derives identical records; an entry
+ * without a `kind` yields a record without one.
+ * @param entries - decoded entries in file order.
+ * @returns the artifact records, oldest first.
+ */
+export declare function foldArtifactRecords(entries: readonly DevflowJournalEntry[]): ArtifactRecord[];
 //# sourceMappingURL=journal.d.ts.map

package/lib/types/journal.js

@@ -67,6 +67,7 @@ export function decodeJournalEntry(value) {
                 path: entry.path,
                 stage: entry.stage,
                 ...entry.by !== undefined ? { by: decodeActor(entry.by) } : {},
+                ...decodeOptionalString(entry, 'kind'),
             };
         }
         case 'claim-expired': {
@@ -148,15 +149,55 @@ export function foldJournal(entries) {
     }
     return state;
 }
+/**
+ * Derive the artifact registrations of a decoded journal, in registration
+ * order. Kept beside {@link foldJournal} — whose `artifacts` is this list's
+ * path projection — so every consumer derives identical records; an entry
+ * without a `kind` yields a record without one.
+ * @param entries - decoded entries in file order.
+ * @returns the artifact records, oldest first.
+ */
+export function foldArtifactRecords(entries) {
+    const records = [];
+    for (const entry of entries) {
+        if (entry.type !== 'artifact')
+            continue;
+        records.push({
+            path: entry.path,
+            ...entry.kind !== undefined ? { kind: entry.kind } : {},
+            rev: entry.rev,
+            stage: entry.stage,
+        });
+    }
+    return records;
+}
 function decodeGate(value) {
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
         throw new Error('transition field "gate" must be a JSON object');
     }
     const gate = value;
-    if (gate.approvedBy === undefined) {
-        throw new Error('transition field "gate" requires "approvedBy"');
+    if (gate.approvedBy === undefined && gate.checks === undefined) {
+        throw new Error('transition field "gate" requires "approvedBy" or "checks"');
+    }
+    return {
+        ...gate.approvedBy !== undefined ? { approvedBy: decodeActor(gate.approvedBy) } : {},
+        ...gate.checks !== undefined ? { checks: decodeGateChecks(gate.checks) } : {},
+    };
+}
+function decodeGateChecks(value) {
+    if (!Array.isArray(value)) {
+        throw new Error('transition field "gate.checks" must be an array');
     }
-    return { approvedBy: decodeActor(gate.approvedBy) };
+    return value.map((check) => {
+        if (typeof check !== 'object' || check === null || Array.isArray(check)) {
+            throw new Error('gate check must be a JSON object');
+        }
+        const record = check;
+        if (record.verdict !== 'allowed') {
+            throw new Error(`gate check field "verdict" must be "allowed" (got ${JSON.stringify(record.verdict)})`);
+        }
+        return { by: decodeActor(record.by), verdict: 'allowed', ...decodeOptionalString(record, 'summary') };
+    });
 }
 function decodeActor(value) {
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {

package/lib/types/stages.d.ts

@@ -46,7 +46,8 @@ export declare function isLegalTransition(from: CardLocation, to: CardLocation,
  * require a recorded `reason` so the next holder knows what to fix.
  * @param from - the departing location.
  * @param to - the target location.
- * @returns `true` for `reviewing -> developing` and `testing -> developing`.
+ * @returns `true` for a move from `reviewing` or `testing` back to
+ *   `developing` or `designing`.
  */
 export declare function isReworkEdge(from: CardLocation, to: CardLocation): boolean;
 //# sourceMappingURL=stages.d.ts.map

package/lib/types/stages.js

@@ -39,14 +39,23 @@ export function isCardLocation(value) {
 export function DevflowCardId(value) {
     return value;
 }
-/** Forward and rework edges of the pipeline; `blocked` legality lives in {@link isLegalTransition}. */
+/**
+ * Forward and rework edges of the pipeline; `blocked` legality lives in
+ * {@link isLegalTransition}.
+ *
+ * Review and verification send a card back to whichever stage owns the fault:
+ * `developing` when the implementation is wrong, `designing` when the design
+ * is. Without the second, design rework happens on a card labelled
+ * `developing`, and the board stops answering the one question it exists to
+ * answer.
+ */
 const FLOW = {
     draft: ['designing'],
     designing: ['ready'],
     ready: ['developing'],
     developing: ['reviewing'],
-    reviewing: ['testing', 'developing'],
-    testing: ['done', 'developing'],
+    reviewing: ['testing', 'developing', 'designing'],
+    testing: ['done', 'developing', 'designing'],
     done: [],
 };
 /**
@@ -74,9 +83,10 @@ export function isLegalTransition(from, to, blockedFrom) {
  * require a recorded `reason` so the next holder knows what to fix.
  * @param from - the departing location.
  * @param to - the target location.
- * @returns `true` for `reviewing -> developing` and `testing -> developing`.
+ * @returns `true` for a move from `reviewing` or `testing` back to
+ *   `developing` or `designing`.
  */
 export function isReworkEdge(from, to) {
-    return to === 'developing' && (from === 'reviewing' || from === 'testing');
+    return (to === 'developing' || to === 'designing') && (from === 'reviewing' || from === 'testing');
 }
 //# sourceMappingURL=stages.js.map

package/lib/types/types.d.ts

@@ -7,6 +7,10 @@
 import type { DevflowCardId } from './stages.ts';
 export type { DevflowCardId } from './stages.ts';
 declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Optional dynamic artifact-contract inspection published by a policy provider. */
+        devflowArtifactContract: ArtifactContract;
+    }
     interface Events {
         /**
          * Single-decision transition pipeline. The store dispatches this after the
@@ -63,6 +67,18 @@ export interface JournalCreated {
     /** The card this one decomposes, fixed here at creation and never changed. */
     parent?: DevflowCardId;
 }
+/**
+ * One recorded gate verdict on a committed transition: which actor allowed the
+ * move and, optionally, what the check covered. Only permitting verdicts
+ * exist — a refusal vetoes the transition instead of being recorded.
+ */
+export interface GateCheck {
+    /** The actor that allowed the move. */
+    by: DevActor;
+    verdict: 'allowed';
+    /** One-line account of what the check covered. */
+    summary?: string;
+}
 /**
  * One stage move. A move to `blocked` remembers `from`; the matching recovery
  * must return to exactly that stage.
@@ -75,9 +91,14 @@ export interface JournalTransition {
     to: CardLocation;
     by?: DevActor;
     reason?: string;
-    /** Gate facts attached by the transition waterfall, e.g. the human approval signature. */
+    /**
+     * Gate facts attached by the transition waterfall: the human approval
+     * signature and/or the recorded gate verdicts. At least one is present —
+     * a move nothing gated carries no `gate` at all.
+     */
     gate?: {
-        approvedBy: DevActor;
+        approvedBy?: DevActor;
+        checks?: GateCheck[];
     };
 }
 /** Registration of a stage deliverable produced under `artifacts/`. */
@@ -88,6 +109,11 @@ export interface JournalArtifact {
     path: string;
     stage: DevStage;
     by?: DevActor;
+    /**
+     * Deliverable kind of a store-written artifact; absent for a path-only
+     * registration and for entries predating kinds.
+     */
+    kind?: string;
 }
 /** Takeover of a stale lease: the previous holder's heartbeat lapsed. */
 export interface JournalClaimExpired {
@@ -99,6 +125,21 @@ export interface JournalClaimExpired {
 }
 /** The journal entry union; the discriminant is `type`. */
 export type DevflowJournalEntry = JournalCreated | JournalTransition | JournalArtifact | JournalClaimExpired;
+/**
+ * Read-side value of one artifact registration: the journal entry's facts
+ * without its envelope. Registrations are immutable — the newest record of one
+ * `kind` (the highest `rev`) is that kind's current content.
+ */
+export interface ArtifactRecord {
+    /** Artifact path relative to the card directory. */
+    path: string;
+    /** Deliverable kind; absent for a path-only registration. */
+    kind?: string;
+    /** Journal revision of the registration; orders records of one kind. */
+    rev: number;
+    /** The stage the deliverable was registered against. */
+    stage: DevStage;
+}
 /** Read-side value of one card, current state derived by journal replay. */
 export interface DevCard {
     id: DevflowCardId;
@@ -121,8 +162,36 @@ export interface DevCard {
     body: string;
     /** Display path of the card file. */
     path: string;
-    /** Artifact paths registered in the journal, in registration order. */
+    /** Artifact paths registered in the journal, in registration order; the path projection of {@link artifactRecords}. */
     artifacts: string[];
+    /** Artifact registrations in registration order, each carrying its journal revision, registering stage, and optional kind. */
+    artifactRecords: ArtifactRecord[];
+}
+/** Immutable normalized artifact shape published through the inspection seam. */
+export interface PublishedArtifactKindSpec {
+    readonly frontmatter?: readonly string[];
+    readonly sections?: readonly string[];
+}
+/** Mechanical state of one required artifact at the inspected card revision. */
+export type ArtifactRequirementStatus = 'missing' | 'malformed' | 'satisfied';
+/** One required kind and the exact evidence the transition policy will judge. */
+export interface ArtifactRequirementInspection {
+    readonly kind: string;
+    readonly status: ArtifactRequirementStatus;
+    readonly spec: PublishedArtifactKindSpec;
+    readonly artifact?: Readonly<ArtifactRecord>;
+    readonly defects: readonly string[];
+}
+/** Artifact requirements of one configured, currently legal outgoing edge. */
+export interface ArtifactTransitionInspection {
+    readonly from: CardLocation;
+    readonly to: CardLocation;
+    readonly requirements: readonly ArtifactRequirementInspection[];
+}
+/** Optional read-only policy seam consumed by model-facing card tools. */
+export interface ArtifactContract {
+    /** Inspect every configured legal edge leaving the card's current location. */
+    inspectOutgoing(card: DevCard): Promise<readonly ArtifactTransitionInspection[]>;
 }
 /** Read filter accepted by {@link import('./index.ts').DevflowStore.list}. */
 export interface CardFilter {
@@ -211,12 +280,19 @@ export type TransitionDecision = {
     allowed: true;
     /** The human signature a policy listener collected; recorded as the journal entry's `gate.approvedBy`. */
     approvedBy?: DevActor;
+    /** Gate verdicts policy listeners collected; recorded as the journal entry's `gate.checks` when non-empty. */
+    checks?: GateCheck[];
 } | {
     allowed: false;
     reason: string;
 };
-/** Stable rejection codes of {@link TransitionResult}; the discriminant is `code`. */
-export type TransitionRejectionCode = 'revision-mismatch' | 'illegal-edge' | 'reason-required' | 'vetoed';
+/**
+ * Stable rejection codes of {@link TransitionResult}; the discriminant is
+ * `code`. `write-contended` is the only one a caller can retry unchanged: it
+ * says another process held the card's commit long enough that this one gave
+ * up, and that nothing was written.
+ */
+export type TransitionRejectionCode = 'revision-mismatch' | 'illegal-edge' | 'reason-required' | 'vetoed' | 'write-contended';
 /**
  * Transition outcome. Domain rejections resolve with `ok: false` and a stable
  * code; only infrastructure failures (unwritable journal, unreadable card)
@@ -231,24 +307,45 @@ export type TransitionResult = {
     code: TransitionRejectionCode;
     message: string;
 };
-/** Caller view of one artifact registration against the card's current stage. */
-export interface ArtifactRequest {
+/** Fields shared by both {@link ArtifactRequest} forms. */
+interface ArtifactRequestBase {
     id: DevflowCardId;
-    /** Artifact path relative to the card directory, e.g. `artifacts/design.md`. */
-    path: string;
     /** Optimistic-concurrency token: the `stageRevision` the caller last observed. */
     expectedRevision: number;
     by: DevActor;
     /** Devflow root holding the card; omitted uses the implementation's default root. */
     root?: string;
 }
+/** Reference form: the caller already wrote the file and registers its path. */
+export interface ArtifactPathRequest extends ArtifactRequestBase {
+    /** Artifact path relative to the card directory, e.g. `artifacts/design.md`. */
+    path: string;
+}
+/**
+ * Store-written form: the implementation writes `artifacts/<rev>-<kind>.md`
+ * itself, before the journal append, and registers that path.
+ */
+export interface ArtifactContentRequest extends ArtifactRequestBase {
+    /** Deliverable kind; the slug grammar, rejected `invalid-kind` otherwise. */
+    kind: string;
+    /** Complete Markdown content the implementation writes. */
+    content: string;
+}
+/**
+ * Caller view of one artifact registration against the card's current stage:
+ * the reference form or the store-written form. The two are mutually
+ * exclusive — the model-facing tool rejects a call carrying both before the
+ * seam is reached.
+ */
+export type ArtifactRequest = ArtifactPathRequest | ArtifactContentRequest;
 /** Artifact-registration outcome; domain rejections resolve like {@link TransitionResult}. */
 export type ArtifactResult = {
     ok: true;
     card: DevCard;
+    record: ArtifactRecord;
 } | {
     ok: false;
-    code: 'revision-mismatch' | 'illegal-edge';
+    code: 'revision-mismatch' | 'illegal-edge' | 'invalid-kind' | 'write-contended';
     message: string;
 };
 /** Current lease facts of one card, read from its claim record. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhchxiao123/dsh-devflow",
   "description": "Service Definition for the ctx.devflow task-card capability seam of the DeepSeek Harness",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public"
   },