@zhchxiao123/dsh-devflow 0.1.1 → 0.3.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

@@ -28,6 +28,31 @@ function isCardLocation(value) {
 	return value === "blocked" || isDevStage(value);
 }
 /**
+* The service classes, in ascending order of what they skip.
+*
+* Closed vocabulary rather than a plugin `Config` field, on the same grounds as
+* {@link DEV_STAGES}: the board, both language documents, and the agent's
+* prompts all reference these names, and a deployment-defined class would make
+* every one of those references local. Letting a deployment mint its own
+* shorter class is also precisely the failure mode this vocabulary exists to
+* prevent — see the service-class Agent Note.
+*/
+const SERVICE_CLASSES = [
+	"standard",
+	"express",
+	"emergency"
+];
+/** The class of a card that declares none, on disk and in memory. */
+const DEFAULT_SERVICE_CLASS = "standard";
+/**
+* Narrow an unknown value to a service class.
+* @param value - the candidate value.
+* @returns `true` when `value` is one of {@link SERVICE_CLASSES}.
+*/
+function isServiceClass(value) {
+	return typeof value === "string" && SERVICE_CLASSES.includes(value);
+}
+/**
 * Brand a raw string as a {@link DevflowCardId}. The id equals the card's
 * directory name; construction lives here because this package owns the brand.
 * @param value - the card directory name.
@@ -36,41 +61,93 @@ 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.
+*
+* `developing` reaches `designing` for the same reason, from the stage that
+* finds such faults most often. Its absence left `developing → reviewing →
+* designing` as the only route back, which records a review that never
+* happened in the authoritative journal to reach the stage owning the fault.
+*/
 const FLOW = {
 	draft: ["designing"],
 	designing: ["ready"],
 	ready: ["developing"],
-	developing: ["reviewing"],
-	reviewing: ["testing", "developing"],
-	testing: ["done", "developing"],
+	developing: ["reviewing", "designing"],
+	reviewing: [
+		"testing",
+		"developing",
+		"designing"
+	],
+	testing: [
+		"done",
+		"developing",
+		"designing"
+	],
 	done: []
 };
 /**
+* Edges each service class adds to {@link FLOW}, and the only place a class
+* differs from another. Stated as additions rather than as one whole graph per
+* class so "every class is a superset of `standard`" is a property of the code
+* instead of a convention: a class cannot remove an edge, and therefore cannot
+* make a journal that replays today stop replaying.
+*/
+const CLASS_EXTRA = {
+	standard: {},
+	express: {
+		draft: ["developing"],
+		reviewing: ["done"]
+	},
+	emergency: {
+		draft: ["developing"],
+		developing: ["done"]
+	}
+};
+/**
 * Whether one stage move is a legal edge of the state machine.
 *
 * Main flow follows the pipeline order; `reviewing` and `testing` may rework
-* to `developing`; any non-terminal location may enter `blocked`; a blocked
-* card may only recover to the exact stage it interrupted.
+* to `developing` or `designing` and `developing` may rework to `designing`;
+* any non-terminal location may enter `blocked`; a blocked card may only
+* recover to the exact stage it interrupted. A card's service class adds the
+* shortcuts in {@link CLASS_EXTRA} and takes nothing away.
+*
+* `blocked` legality does not vary by class: a shortcut is about which stages
+* a card may skip, not about how it pauses.
 * @param from - the card's current location.
 * @param to - the requested target location.
-* @param blockedFrom - the remembered origin stage while `from` is `blocked`.
+* @param card - the moving card's own context; omitted reads as a `standard`
+*   card that is not blocked.
 * @returns `true` when the move is a legal edge.
 */
-function isLegalTransition(from, to, blockedFrom) {
+function isLegalTransition(from, to, card) {
 	if (from === to) return false;
-	if (from === "blocked") return to === blockedFrom;
+	if (from === "blocked") return to === card?.blockedFrom;
 	if (to === "blocked") return from !== "done";
-	return FLOW[from].includes(to);
+	if (FLOW[from].includes(to)) return true;
+	return (CLASS_EXTRA[card?.serviceClass ?? "standard"][from] ?? []).includes(to);
 }
 /**
 * Whether a legal edge moves the card backwards (a rework). Rework edges
-* require a recorded `reason` so the next holder knows what to fix.
+* require a recorded `reason` so the next holder knows what to fix — on
+* `developing -> designing` that reason is what implementing the design
+* revealed about it, which is the whole point of routing the card back rather
+* than redesigning in place.
 * @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`, and for `developing` back to `designing`.
 */
 function isReworkEdge(from, to) {
+	if (to === "designing") return from === "developing" || from === "reviewing" || from === "testing";
 	return to === "developing" && (from === "reviewing" || from === "testing");
 }
 //#endregion
@@ -104,7 +181,8 @@ function decodeJournalEntry(value) {
 			at: entry.at,
 			type: "created",
 			by: decodeActor(entry.by),
-			...decodeOptionalCardId(entry, "parent")
+			...decodeOptionalCardId(entry, "parent"),
+			...decodeOptionalServiceClass(entry)
 		};
 		case "transition":
 			if (!isCardLocation(entry.from)) throw new Error("transition field \"from\" must be a stage or \"blocked\"");
@@ -128,7 +206,17 @@ 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 "abandoned":
+			if (typeof entry.reason !== "string" || entry.reason.trim().length === 0) throw new Error("abandoned field \"reason\" must be a non-empty string; a card leaving the board without one loses the decision");
+			return {
+				rev,
+				at: entry.at,
+				type: "abandoned",
+				by: decodeActor(entry.by),
+				reason: entry.reason
 			};
 		case "claim-expired":
 			if (entry.previousOwner === void 0) throw new Error("claim-expired field \"previousOwner\" is required");
@@ -139,7 +227,7 @@ function decodeJournalEntry(value) {
 				previousOwner: decodeActor(entry.previousOwner),
 				by: decodeActor(entry.by)
 			};
-		default: throw new Error(`journal entry field "type" must be created, transition, artifact, or claim-expired (got ${JSON.stringify(entry.type)})`);
+		default: throw new Error(`journal entry field "type" must be created, transition, artifact, abandoned, or claim-expired (got ${JSON.stringify(entry.type)})`);
 	}
 }
 /**
@@ -148,7 +236,8 @@ function decodeJournalEntry(value) {
 * Validates the structural invariants of the durable stream: revisions are the
 * contiguous sequence 1..n, the first entry is `created`, every transition
 * departs from the current location, a move to `blocked` remembers its origin,
-* and the matching recovery returns exactly there.
+* the matching recovery returns exactly there, and nothing follows an
+* `abandoned` entry.
 * @param entries - decoded entries in file order.
 * @returns the folded card state.
 * @throws {Error} naming the first violated invariant and its entry revision.
@@ -158,6 +247,7 @@ function foldJournal(entries) {
 	const state = {
 		stage: "draft",
 		revision: 0,
+		serviceClass: DEFAULT_SERVICE_CLASS,
 		artifacts: []
 	};
 	for (const [index, entry] of entries.entries()) {
@@ -165,9 +255,11 @@ function foldJournal(entries) {
 		if (index === 0) {
 			if (entry.type !== "created") throw new Error("journal entry 1 must be \"created\"");
 			if (entry.parent !== void 0) state.parent = entry.parent;
+			if (entry.serviceClass !== void 0) state.serviceClass = entry.serviceClass;
 			state.revision = entry.rev;
 			continue;
 		}
+		if (state.abandoned === true) throw new Error(`journal entry rev ${entry.rev} follows an abandoned card; abandoning is terminal`);
 		switch (entry.type) {
 			case "created": throw new Error(`journal entry rev ${entry.rev} repeats "created"`);
 			case "transition":
@@ -185,16 +277,57 @@ function foldJournal(entries) {
 				state.artifacts.push(entry.path);
 				state.revision = entry.rev;
 				break;
+			case "abandoned":
+				state.abandoned = true;
+				state.revision = entry.rev;
+				break;
 			case "claim-expired": state.revision = entry.rev;
 		}
 	}
 	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");
@@ -215,6 +348,12 @@ function decodeActor(value) {
 		default: throw new Error(`actor field "kind" must be human, agent, or command (got ${JSON.stringify(actor.kind)})`);
 	}
 }
+function decodeOptionalServiceClass(record) {
+	const value = record.serviceClass;
+	if (value === void 0) return {};
+	if (!isServiceClass(value)) throw new Error(`created field "serviceClass" must be one of ${SERVICE_CLASSES.join(", ")} when present`);
+	return { serviceClass: value };
+}
 function decodeOptionalCardId(record, key) {
 	const value = record[key];
 	if (value === void 0) return {};
@@ -237,6 +376,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 +541,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, DEFAULT_SERVICE_CLASS, DEV_STAGES, DevflowCardId, DevflowStore, DevflowStore as default, SERVICE_CLASSES, decodeJournalEntry, foldArtifactRecords, foldJournal, isCardLocation, isDevStage, isLegalTransition, isReworkEdge, isServiceClass };
 
 //# sourceMappingURL=index.js.map

package/lib/types/index.d.ts

@@ -7,11 +7,119 @@
  * @module @zhchxiao123/dsh-devflow
  */
 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';
+import type { AbandonRequest, AbandonResult, 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 { DEFAULT_SERVICE_CLASS, DEV_STAGES, DevflowCardId, SERVICE_CLASSES, isCardLocation, isDevStage, isLegalTransition, isReworkEdge, isServiceClass } from './stages.ts';
+export type { TransitionContext } from './stages.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,27 +199,61 @@ 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>;
+    /**
+     * Record that a card's work stops and take it off the active board.
+     *
+     * The journal append is the commit point; the card's directory then joins
+     * the archive. A crash between the two leaves an abandoned card under
+     * `tasks/`, so {@link list} must exclude it by its folded state rather than
+     * by where its directory sits.
+     *
+     * The reason is required — a card that disappears without one loses the
+     * decision it exists to record — and a `done` card is refused: a delivered
+     * outcome is settled by {@link archiveDone}, not overwritten by a decision
+     * not to deliver it.
+     * @param request - card, expected revision, actor, and the reason.
+     * @returns the outcome; domain rejections resolve with `ok: false`.
+     */
+    abstract abandon(request: AbandonRequest): Promise<AbandonResult>;
     /**
      * Move every `done` card of one root out of the active set into that root's
      * archive, keyed by the month of its last journal entry. Archived cards