@zhchxiao123/dsh-devflow 0.1.1 → 0.3.0

package/lib/types/index.js

@@ -8,8 +8,52 @@
  */
 import { join } from 'node:path';
 import { Service } from '@deepseek-ai/cordis';
-export { DEV_STAGES, DevflowCardId, isCardLocation, isDevStage, isLegalTransition, isReworkEdge } from "./stages.js";
-export { decodeJournalEntry, foldJournal } from "./journal.js";
+import { DEV_STAGES } 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 = {
+    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, 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,10 +48,20 @@ 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.
  */
 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

@@ -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))
@@ -67,6 +68,19 @@ export function decodeJournalEntry(value) {
                 path: entry.path,
                 stage: entry.stage,
                 ...entry.by !== undefined ? { 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': {
@@ -82,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)})`);
     }
 }
 /**
@@ -91,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.
@@ -99,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`);
@@ -109,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"`);
@@ -141,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;
@@ -148,15 +172,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)) {
@@ -174,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,24 +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 `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`.
  */
 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.
@@ -39,44 +60,84 @@ 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.
+ *
+ * `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.
  */
-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 `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`.
  */
 export function isReworkEdge(from, to) {
+    if (to === 'designing')
+        return from === 'developing' || from === 'reviewing' || from === 'testing';
     return to === 'developing' && (from === 'reviewing' || from === 'testing');
 }
 //# sourceMappingURL=stages.js.map