@zhchxiao123/dsh-devflow 0.1.1 → 0.3.0

package/lib/types/types.d.ts

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

package/package.json

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