@zhchxiao123/dsh-devflow 0.2.0 → 0.4.0-dev.0

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.
@@ -45,12 +70,17 @@ function DevflowCardId(value) {
 * 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"],
+	developing: ["reviewing", "designing"],
 	reviewing: [
 		"testing",
 		"developing",
@@ -64,32 +94,61 @@ const FLOW = {
 	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 a move from `reviewing` or `testing` back to
-*   `developing` or `designing`.
+*   `developing` or `designing`, and for `developing` back to `designing`.
 */
 function isReworkEdge(from, to) {
-	return (to === "developing" || to === "designing") && (from === "reviewing" || from === "testing");
+	if (to === "designing") return from === "developing" || from === "reviewing" || from === "testing";
+	return to === "developing" && (from === "reviewing" || from === "testing");
 }
 //#endregion
 //#region packages/devflow/src/journal.ts
@@ -122,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\"");
@@ -149,6 +209,15 @@ function decodeJournalEntry(value) {
 				...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");
 			return {
@@ -158,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)})`);
 	}
 }
 /**
@@ -167,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.
@@ -177,6 +247,7 @@ function foldJournal(entries) {
 	const state = {
 		stage: "draft",
 		revision: 0,
+		serviceClass: DEFAULT_SERVICE_CLASS,
 		artifacts: []
 	};
 	for (const [index, entry] of entries.entries()) {
@@ -184,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":
@@ -204,6 +277,10 @@ 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;
 		}
 	}
@@ -271,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 {};
@@ -458,6 +541,6 @@ function rootOfCwd(cwd) {
 	return cwd === void 0 ? void 0 : join(cwd, ".devflow");
 }
 //#endregion
-export { ARTIFACT_RECORD_SCHEMA, ARTIFACT_TRANSITION_INSPECTION_SCHEMA, DEV_STAGES, DevflowCardId, DevflowStore, DevflowStore as default, decodeJournalEntry, foldArtifactRecords, 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,9 +7,10 @@
  * @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 { 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. */
@@ -237,6 +238,22 @@ export declare abstract class DevflowStore extends Service {
      * @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

package/lib/types/index.js

@@ -9,7 +9,7 @@
 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 { DEFAULT_SERVICE_CLASS, DEV_STAGES, DevflowCardId, SERVICE_CLASSES, isCardLocation, isDevStage, isLegalTransition, isReworkEdge, isServiceClass } from "./stages.js";
 export { decodeJournalEntry, foldArtifactRecords, foldJournal } from "./journal.js";
 /** JSON Schema for the Definition-owned artifact registration record. */
 export const ARTIFACT_RECORD_SCHEMA = {

package/lib/types/journal.d.ts

@@ -6,7 +6,7 @@
  * @module @zhchxiao123/dsh-devflow/src/journal
  */
 import { DevflowCardId } from './stages.ts';
-import type { ArtifactRecord, CardLocation, DevStage, DevflowJournalEntry } from './types.ts';
+import type { ArtifactRecord, CardLocation, DevStage, DevflowJournalEntry, ServiceClass } from './types.ts';
 /** Card state derived by {@link foldJournal}; the read-side authority. */
 export interface JournalFoldState {
     /** Current location after the last entry. */
@@ -17,6 +17,17 @@ export interface JournalFoldState {
     blockedFrom?: DevStage;
     /** The card this one decomposes, from the `created` entry; absent for a top-level card. */
     parent?: DevflowCardId;
+    /**
+     * The card's service class, from the `created` entry. Always set: an entry
+     * that states none is a {@link DEFAULT_SERVICE_CLASS} card, so no read-side
+     * consumer branches on absence.
+     */
+    serviceClass: ServiceClass;
+    /**
+     * Set once the card was abandoned. Terminal: no entry may follow, and the
+     * card is off the active board even while its directory awaits archiving.
+     */
+    abandoned?: true;
     /** Artifact paths in registration order. */
     artifacts: string[];
 }
@@ -37,7 +48,8 @@ export declare function decodeJournalEntry(value: unknown): DevflowJournalEntry;
  * 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.

package/lib/types/journal.js

@@ -5,7 +5,7 @@
  * entries through this module so every consumer derives identical state.
  * @module @zhchxiao123/dsh-devflow/src/journal
  */
-import { DEV_STAGES, DevflowCardId, isCardLocation, isDevStage } from "./stages.js";
+import { DEFAULT_SERVICE_CLASS, DEV_STAGES, DevflowCardId, SERVICE_CLASSES, isCardLocation, isDevStage, isServiceClass } from "./stages.js";
 /**
  * Decode one parsed journal value into a {@link DevflowJournalEntry}.
  *
@@ -36,6 +36,7 @@ export function decodeJournalEntry(value) {
                 type: 'created',
                 by: decodeActor(entry.by),
                 ...decodeOptionalCardId(entry, 'parent'),
+                ...decodeOptionalServiceClass(entry),
             };
         case 'transition': {
             if (!isCardLocation(entry.from))
@@ -70,6 +71,18 @@ export function decodeJournalEntry(value) {
                 ...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 === undefined) {
                 throw new Error('claim-expired field "previousOwner" is required');
@@ -83,7 +96,7 @@ export function decodeJournalEntry(value) {
             };
         }
         default:
-            throw new Error(`journal entry field "type" must be created, transition, artifact, or claim-expired (got ${JSON.stringify(entry.type)})`);
+            throw new Error(`journal entry field "type" must be created, transition, artifact, abandoned, or claim-expired (got ${JSON.stringify(entry.type)})`);
     }
 }
 /**
@@ -92,7 +105,8 @@ export 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.
@@ -100,7 +114,7 @@ export function decodeJournalEntry(value) {
 export function foldJournal(entries) {
     if (entries.length === 0)
         throw new Error('journal is empty; every card starts with a "created" entry');
-    const state = { stage: 'draft', revision: 0, artifacts: [] };
+    const state = { stage: 'draft', revision: 0, serviceClass: DEFAULT_SERVICE_CLASS, artifacts: [] };
     for (const [index, entry] of entries.entries()) {
         if (entry.rev !== index + 1) {
             throw new Error(`journal entry ${index + 1} carries rev ${entry.rev}; revisions must be contiguous from 1`);
@@ -110,9 +124,14 @@ export function foldJournal(entries) {
                 throw new Error('journal entry 1 must be "created"');
             if (entry.parent !== undefined)
                 state.parent = entry.parent;
+            if (entry.serviceClass !== undefined)
+                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"`);
@@ -142,6 +161,10 @@ export 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;
                 break;
@@ -215,6 +238,15 @@ function decodeActor(value) {
             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 === undefined)
+        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 === undefined)

package/lib/types/stages.d.ts

@@ -5,7 +5,7 @@
  * @module @zhchxiao123/dsh-devflow/src/stages
  */
 import type { Branded } from '@deepseek-ai/dsh-brand';
-import type { CardLocation, DevStage } from './types.ts';
+import type { CardLocation, DevStage, ServiceClass } from './types.ts';
 /** Opaque id of one task card; equals the card's directory name and never changes. */
 export type DevflowCardId = Branded<'DevflowCardId'>;
 /** The pipeline stages in flow order; `blocked` is a bypass, not a member. */
@@ -22,6 +22,25 @@ export declare function isDevStage(value: unknown): value is DevStage;
  * @returns `true` when `value` is a stage or the `blocked` bypass.
  */
 export declare function isCardLocation(value: unknown): value is CardLocation;
+/**
+ * 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.
+ */
+export declare const SERVICE_CLASSES: readonly ["standard", "express", "emergency"];
+/** The class of a card that declares none, on disk and in memory. */
+export declare const DEFAULT_SERVICE_CLASS: ServiceClass;
+/**
+ * Narrow an unknown value to a service class.
+ * @param value - the candidate value.
+ * @returns `true` when `value` is one of {@link SERVICE_CLASSES}.
+ */
+export declare function isServiceClass(value: unknown): value is ServiceClass;
 /**
  * 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.
@@ -29,25 +48,41 @@ export declare function isCardLocation(value: unknown): value is CardLocation;
  * @returns the branded id.
  */
 export declare function DevflowCardId(value: string): DevflowCardId;
+/** A card's own contribution to edge legality; {@link DevCard} satisfies it. */
+export interface TransitionContext {
+    /** The remembered origin stage while the card sits at `blocked`. */
+    blockedFrom?: DevStage;
+    /** The card's service class; omitted is {@link DEFAULT_SERVICE_CLASS}. */
+    serviceClass?: ServiceClass;
+}
 /**
  * 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.
  */
-export declare function isLegalTransition(from: CardLocation, to: CardLocation, blockedFrom?: DevStage): boolean;
+export declare function isLegalTransition(from: CardLocation, to: CardLocation, card?: TransitionContext): boolean;
 /**
  * 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 a move from `reviewing` or `testing` back to
- *   `developing` or `designing`.
+ *   `developing` or `designing`, and for `developing` back to `designing`.
  */
 export declare function isReworkEdge(from: CardLocation, to: CardLocation): boolean;
 //# sourceMappingURL=stages.d.ts.map

package/lib/types/stages.js

@@ -30,6 +30,27 @@ export function isDevStage(value) {
 export 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.
+ */
+export const SERVICE_CLASSES = ['standard', 'express', 'emergency'];
+/** The class of a card that declares none, on disk and in memory. */
+export 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}.
+ */
+export 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.
@@ -48,45 +69,75 @@ export function DevflowCardId(value) {
  * 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'],
+    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.
  */
-export function isLegalTransition(from, to, blockedFrom) {
+export function isLegalTransition(from, to, card) {
     if (from === to)
         return false;
     if (from === 'blocked')
-        return to === blockedFrom;
+        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 ?? DEFAULT_SERVICE_CLASS][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 a move from `reviewing` or `testing` back to
- *   `developing` or `designing`.
+ *   `developing` or `designing`, and for `developing` back to `designing`.
  */
 export function isReworkEdge(from, to) {
-    return (to === 'developing' || to === 'designing') && (from === 'reviewing' || from === 'testing');
+    if (to === 'designing')
+        return from === 'developing' || from === 'reviewing' || from === 'testing';
+    return to === 'developing' && (from === 'reviewing' || from === 'testing');
 }
 //# sourceMappingURL=stages.js.map

package/lib/types/types.d.ts

@@ -47,6 +47,20 @@ declare module '@deepseek-ai/cordis' {
 export type DevStage = 'draft' | 'designing' | 'ready' | 'developing' | 'reviewing' | 'testing' | 'done';
 /** Where a card currently sits: a pipeline stage, or the `blocked` bypass. */
 export type CardLocation = DevStage | 'blocked';
+/**
+ * The closed set of service classes a card is created under, each selecting
+ * which edges of the pipeline that card may take. Every class is a superset of
+ * `standard`, so a class only ever adds a shortcut.
+ *
+ * - `standard` — the full pipeline; the class of a card that declares none.
+ * - `express` — reaches `developing` from `draft` and `done` from
+ *   `reviewing`, skipping design, readiness, and independent verification.
+ *   Peer review stays: it is the control worth keeping on cheap work.
+ * - `emergency` — reaches `developing` from `draft` and `done` from
+ *   `developing`. It gives up review too, and the follow-up is an ordinary
+ *   card rather than an obligation encoded in the state machine.
+ */
+export type ServiceClass = 'standard' | 'express' | 'emergency';
 /** Who performed a journal action; `command` marks the human-command intervention plane. */
 export type DevActor = {
     kind: 'human';
@@ -66,6 +80,12 @@ export interface JournalCreated {
     by: DevActor;
     /** The card this one decomposes, fixed here at creation and never changed. */
     parent?: DevflowCardId;
+    /**
+     * The card's service class, fixed here at creation and never changed.
+     * Omitted is `standard`, so a journal written before classes existed reads
+     * as one and a `standard` card's first entry keeps its original bytes.
+     */
+    serviceClass?: ServiceClass;
 }
 /**
  * One recorded gate verdict on a committed transition: which actor allowed the
@@ -115,6 +135,23 @@ export interface JournalArtifact {
      */
     kind?: string;
 }
+/**
+ * The decision to stop: this card will never be finished. Terminal — no entry
+ * may follow it — and the card leaves the active board rather than occupying
+ * a stage nobody is working in.
+ */
+export interface JournalAbandoned {
+    rev: number;
+    at: string;
+    type: 'abandoned';
+    by: DevActor;
+    /**
+     * Why the work stopped. Required, unlike a transition's reason: a transition
+     * leaves the card visible and explicable from where it sits, while this
+     * removes it from the board, so the reason is all that is left of it.
+     */
+    reason: string;
+}
 /** Takeover of a stale lease: the previous holder's heartbeat lapsed. */
 export interface JournalClaimExpired {
     rev: number;
@@ -124,7 +161,7 @@ export interface JournalClaimExpired {
     by: DevActor;
 }
 /** The journal entry union; the discriminant is `type`. */
-export type DevflowJournalEntry = JournalCreated | JournalTransition | JournalArtifact | JournalClaimExpired;
+export type DevflowJournalEntry = JournalCreated | JournalTransition | JournalArtifact | JournalAbandoned | JournalClaimExpired;
 /**
  * Read-side value of one artifact registration: the journal entry's facts
  * without its envelope. Registrations are immutable — the newest record of one
@@ -158,6 +195,16 @@ export interface DevCard {
      * exists, so a card carrying `parent` is never itself a parent.
      */
     parent?: DevflowCardId;
+    /**
+     * The card's service class, selecting which pipeline edges it may take.
+     * Always present: a card whose journal states none is `standard`.
+     */
+    serviceClass: ServiceClass;
+    /**
+     * Set once the card was abandoned: the work stopped and will not resume.
+     * Such a card is off the active board, so `list` never reports one.
+     */
+    abandoned?: true;
     /** Markdown body of the card file below its frontmatter. */
     body: string;
     /** Display path of the card file. */
@@ -215,6 +262,12 @@ export interface CreateRequest {
      * must be an active top-level card of the same root — only one level exists.
      */
     parent?: DevflowCardId;
+    /**
+     * Which pipeline edges the card may take, fixed here and never changed —
+     * escalating live work means a new card, not a mutated one. Omitted is
+     * `standard`, the full pipeline.
+     */
+    serviceClass?: ServiceClass;
     /** Devflow root receiving the card; omitted uses the implementation's default root. */
     root?: string;
 }
@@ -307,6 +360,35 @@ export type TransitionResult = {
     code: TransitionRejectionCode;
     message: string;
 };
+/** Caller view of one abandonment: the decision that this card stops here. */
+export interface AbandonRequest {
+    id: DevflowCardId;
+    /** Optimistic-concurrency token: the `stageRevision` the caller last observed. */
+    expectedRevision: number;
+    by: DevActor;
+    /** Why the work stopped; blank is rejected rather than recorded as nothing. */
+    reason: string;
+    /** Devflow root holding the card; omitted uses the implementation's default root. */
+    root?: string;
+}
+/**
+ * Stable rejection codes of {@link AbandonResult}. `already-done` names the one
+ * card that must not be abandoned: a delivered outcome is not a decision to
+ * stop, and `archiveDone` is what settles it.
+ */
+export type AbandonRejectionCode = 'empty-reason' | 'already-done' | 'revision-mismatch' | 'write-contended';
+/**
+ * Outcome of one abandonment. Domain rejections resolve with a stable code;
+ * only infrastructure failures reject the promise.
+ */
+export type AbandonResult = {
+    ok: true;
+    card: DevCard;
+} | {
+    ok: false;
+    code: AbandonRejectionCode;
+    message: string;
+};
 /** Fields shared by both {@link ArtifactRequest} forms. */
 interface ArtifactRequestBase {
     id: DevflowCardId;

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.2.0",
+  "version": "0.4.0-dev.0",
   "publishConfig": {
     "access": "public"
   },
@@ -46,16 +46,16 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "4.0.1",
-    "@deepseek-ai/dsh-brand": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "0.1.1-rc.2"
+    "@deepseek-ai/cordis": "4.0.2",
+    "@deepseek-ai/dsh-brand": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-invariants": "0.1.2-alpha.3"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.1",
-    "@deepseek-ai/dsh-brand": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-session-persistence": "0.1.1-rc.2"
+    "@deepseek-ai/cordis": "4.0.2",
+    "@deepseek-ai/dsh-brand": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-invariants": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session-persistence": "0.1.2-alpha.3"
   },
   "scripts": {}
 }