@godv61/dsh-task-engine 0.23.9 → 0.25.0

package/lib/engine.d.ts

@@ -42,13 +42,107 @@ export interface CommitRule {
     /** When true (default), a commit may only touch files listed in the task's `files`. */
     file_scope: boolean;
 }
-/** Skills and rules a stage pins for progressive disclosure when the task enters it. */
+/**
+ * A resource reference that names where the resource lives.
+ *
+ * A bare name is ambiguous once project and user directories can both hold one:
+ * `coding-conventions` in a project and `coding-conventions` in the user home are
+ * different resources that happen to share a name, and a binding written as a
+ * plain string cannot say which was meant. Every stored reference therefore
+ * carries its source layer, and a legacy bare name is resolved by the documented
+ * precedence and recorded as the layer it resolved to.
+ */
+export interface ResourceRef {
+    /** Source layer the resource belongs to. */
+    source: ResourceSource;
+    /** Resource name within that layer. */
+    name: string;
+}
+/** Where a skill or rule came from. `bundled` ships with the plugin. */
+export type ResourceSource = 'bundled' | 'project' | 'user';
+/** Render a reference as `source:name`, the form used in config and status output. */
+export declare function formatResourceRef(ref: ResourceRef): string;
+/**
+ * Parse a `source:name` reference. Returns undefined for a bare name, which is
+ * the legacy shape and must go through precedence resolution instead.
+ * @param text - the stored reference text.
+ * @returns the parsed reference, or undefined when it carries no source.
+ */
+export declare function parseResourceRef(text: string): ResourceRef | undefined;
+/**
+ * One skill bound to a stage, with the complete list of rules that apply to it.
+ *
+ * Rules belong to the SKILL, not to the stage. A skill has exactly one rule list:
+ * wherever that skill is bound, the same rules come with it. There is no
+ * per-stage rule list, no inheritance from a stage or a preset, and no override
+ * layer, because a stage-level list forced every reader to compute a merge before
+ * knowing what actually applied, and made "which rules is this skill running
+ * under?" unanswerable without inspecting the whole composition.
+ *
+ * To use one skill under two different rule sets, copy it into a distinct skill
+ * and configure that one separately. Explicit duplication is easier to reason
+ * about than an implicit inheritance chain, and it keeps the answer to the
+ * question above local to the skill.
+ */
+export interface SkillBinding {
+    /** The skill, named with its source layer. */
+    skill: ResourceRef;
+    /** Rules this skill follows, each named with its source layer. */
+    rules: ResourceRef[];
+    /**
+     * What kind of evidence proves this skill was actually executed.
+     *
+     * A shell command is one kind of proof, not the only one: a requirement or design
+     * skill produces a document, and demanding a "real validation command" from it
+     * forced an irrelevant command in order to satisfy a gate. Absent means the
+     * historical default (`command`), so existing configs and frozen snapshots keep
+     * behaving exactly as they did.
+     */
+    evidence?: EvidenceKind;
+}
+/**
+ * How a bound skill proves it ran.
+ *
+ * - `command`: a shell command with a captured receipt (the default).
+ * - `artifact`: a recorded artifact body, for skills whose output is a document.
+ * - `review`: a recorded review verdict, for skills that judge rather than build.
+ * - `manual`: an explicit human statement, for work no machine can verify.
+ * - `none`: the skill is advisory and needs no separate proof.
+ *
+ * Naming them lets a flow say what it actually wants, instead of encoding one kind
+ * of evidence as though it were the only kind.
+ */
+export type EvidenceKind = 'command' | 'artifact' | 'review' | 'manual' | 'none';
+/**
+ * What a stage binds for progressive disclosure when the task enters it.
+ *
+ * A stage selects skills only. Its rules are whatever those skills carry.
+ */
 export interface StageBinding {
-    /** Skill names to load for this stage (resolved through the DSH skill registry). */
-    skills?: string[];
-    /** Rule names to read for this stage (resolved under the configured rule roots). */
-    rules?: string[];
+    skills?: SkillBinding[];
+    /**
+     * Stage-level rule names from a pre-migration config, preserved verbatim.
+     *
+     * Rules used to belong to the stage, so a stage with several skills gave no
+     * indication which skill a rule was meant for. Assigning them silently would
+     * invent an answer the config never contained, and dropping them would remove a
+     * constraint the user configured. They are therefore carried here unchanged:
+     * still disclosed, still enforced — so nothing is lost — while the status output
+     * names them as unassigned so a human can decide which skill each belongs to, or
+     * split the skill if the answer differs per stage.
+     */
+    legacy_rules?: string[];
 }
+/**
+ * How thoroughly a flow audits each implementation item.
+ *
+ * `two-stage` requires both a specification-conformance and a quality verdict per
+ * item, which suits a full-development flow. `single` requires one combined
+ * verdict, which is what a fast-change flow needs: the work still has to be
+ * checked before it counts as done, but the same change is not re-reviewed twice
+ * under two headings that a short change rarely distinguishes.
+ */
+export type ReviewDepth = 'two-stage' | 'single';
 export interface WorkflowConfig {
     stages: string[];
     start_stage: string;
@@ -60,6 +154,55 @@ export interface WorkflowConfig {
     high_risk_requires_verification: boolean;
     /** Per-stage skill/rule bindings disclosed when the task enters the stage. */
     stage_bindings?: Record<string, StageBinding>;
+    /**
+     * How much per-item review this flow demands before `todos_done` passes.
+     *
+     * The three presets differ in task complexity, not in how seriously they take
+     * safety, so a lighter flow must be able to ask for a lighter audit rather than
+     * inheriting the heaviest one. Omitting the field keeps the historical
+     * behaviour (`two-stage`), so configs and frozen snapshots written before this
+     * field existed read exactly as they did.
+     */
+    review_depth?: ReviewDepth;
+    /**
+     * Whether finishing the task must include a recorded Git commit.
+     *
+     * A Git commit is one delivery mode, not a universal completion condition: a
+     * non-code task or a project outside version control has nothing to commit.
+     * Omitting the field keeps the historical behaviour (`true`), so existing
+     * configs and frozen snapshots are unaffected.
+     */
+    commit_required?: boolean;
+    /**
+     * Guards a flow requires to hold at COMPLETION, for stages that have no way out.
+     *
+     * A guard normally rides an edge: `代码审核 → 完成` requiring `review_passed` is how
+     * the standard flow states that the review must pass before the end. But a flow
+     * whose final stage is where the work happens has no such edge — the agile flow's
+     * `审查` IS the review, and it is terminal. Hanging a review guard on `交付 → 审查`
+     * would be circular (demanding the verdict before the stage that produces it) and
+     * would also block the commit at `交付`, because a commit requires its stage's
+     * outgoing guards.
+     *
+     * Declaring the requirement here lets completion check it directly and keeps the
+     * statement next to the stage it describes, rather than hidden in edge order.
+     */
+    completion_guards?: GuardName[];
+}
+/**
+ * A frozen copy of one resource's body, taken when the task was created.
+ *
+ * Names alone cannot keep an in-flight task stable: editing a skill or rule that
+ * a running task uses would silently change what that task is doing. The body is
+ * copied, and identical bodies are stored once and shared by content hash, so two
+ * tasks using the same rule do not duplicate several kilobytes each.
+ */
+export interface FrozenResource {
+    ref: ResourceRef;
+    /** SHA-256 of the body, which is also the key under which it is stored. */
+    hash: string;
+    /** The body itself, so a deleted or edited source cannot change a running task. */
+    content: string;
 }
 /**
  * A task's frozen workflow: the preset id, its version, and the complete
@@ -74,6 +217,12 @@ export interface FlowSnapshot {
     config: WorkflowConfig;
     /** SHA-256 of the canonical JSON of `config`; a mismatch proves the snapshot was edited after creation. Absent on pre-0.22 records. */
     hash?: string;
+    /**
+     * The skill and rule bodies this task actually resolved, captured at creation.
+     * Absent on records written before resource freezing; those fall back to live
+     * resolution.
+     */
+    resources?: FrozenResource[];
 }
 /** One delegated implementation unit: a subagent fetch plus its two-stage review. */
 export interface ItemDispatch {
@@ -82,6 +231,55 @@ export interface ItemDispatch {
     /** ISO-8601 timestamp when the subagent was dispatched. */
     at: string;
 }
+/**
+ * Explicit task completion, recorded once every configured condition holds.
+ *
+ * Reaching the last configured stage is not the same fact as finishing the work,
+ * and conflating them let a flow whose final stage is also its commit checkpoint
+ * arrive at that stage with no delivery record at all: the "commit before leaving
+ * a checkpoint" rule fires on the way OUT of a stage, and a terminal stage has no
+ * way out. Completion is therefore its own recorded event, checked by the engine,
+ * so every preset ends through the same lifecycle regardless of how few working
+ * stages it has.
+ */
+export interface TaskCompletion {
+    /** ISO-8601 timestamp of the completion call. */
+    at: string;
+    /** The commit recorded at completion, when the flow's delivery mode requires one. */
+    commit_hash?: string;
+}
+/**
+ * A recorded rework: why the task went back, and exactly what that invalidated.
+ *
+ * The graph only has forward edges, but the work does not: a requirement can
+ * change after implementation started, and a defect can be found during review.
+ * Before this existed, the only way back was a hand-edited record, which left
+ * every downstream conclusion nominally intact — a confirmation, verification
+ * receipt or review verdict that described a superseded tree would still read as
+ * passing.
+ *
+ * The invalidated set is computed from the DECLARED kind rather than from a
+ * blanket rule, because the two cases differ: a changed requirement invalidates
+ * the requirement confirmation and everything downstream of it, while fixing a
+ * defect found in review invalidates the verification and review of that work but
+ * leaves the agreed requirement standing. Invalidating everything on every
+ * rework would be simpler and would also throw away conclusions that are still
+ * true, forcing work to be redone for no reason.
+ */
+export interface TaskRevision {
+    /** What kind of change this was; decides the invalidation scope. */
+    kind: 'requirement' | 'solution' | 'defect';
+    /** Why the task went back, in the author's words. */
+    reason: string;
+    /** The stage the task returned to. */
+    to: string;
+    /** The stage it was at when the rework was recorded. */
+    from: string;
+    /** ISO-8601 timestamp. */
+    at: string;
+    /** Conclusion names this rework invalidated, for audit. */
+    invalidated: string[];
+}
 /** Verdict of one review stage over a completed item. */
 export interface ItemReviewStage {
     outcome: 'pass' | 'fail';
@@ -186,6 +384,10 @@ export interface TaskState {
         evidence: string[];
         receipt?: VerificationReceipt;
     }>>;
+    /** Set by the `complete` operation once every configured condition holds. Absent while the task is still open. */
+    completed?: TaskCompletion;
+    /** Rework history, newest last. Absent when the task never went back. */
+    revisions?: TaskRevision[];
 }
 export interface Result {
     ok: boolean;
@@ -216,7 +418,7 @@ export declare function findTransition(from: string, to: string, config: Workflo
  * two-stage review whose both stages passed, so the implementation and its
  * audit trail are completed together.
  */
-export declare function todosBlockers(state: TaskState): string[];
+export declare function todosBlockers(state: TaskState, config?: WorkflowConfig): string[];
 /**
  * Validate an advance from `state.stage` to `targetStage`.
  *
@@ -248,6 +450,44 @@ export interface CommitCheckpoint {
     label?: string;
     reason?: string;
 }
+/**
+ * Whether this task's flow ever demands a passing verification.
+ *
+ * A preset that never guards an edge on `verified` is telling the engine that
+ * verification is not one of its completion conditions, so a downstream stage
+ * must not invent the requirement.
+ * @param config - the frozen workflow config.
+ * @returns true when any configured transition requires `verified`.
+ */
+export declare function flowRequiresVerification(config: WorkflowConfig): boolean;
+/**
+ * Stages where a passing verification must still HOLD, derived from the graph.
+ *
+ * `verified` guards the edge INTO a stage, so the requirement follows the task
+ * past that edge rather than applying from the start: a task sitting at 需求评审
+ * has produced nothing to verify. Once a task has crossed a `verified` edge,
+ * though, the requirement stays with it — that is the case the old code missed,
+ * where re-verifying and failing let the task continue and commit.
+ *
+ * Computed by walking forward from every `verified` edge's target, so it is a
+ * property of the configured graph rather than a hardcoded stage name.
+ * @param config - the frozen workflow config.
+ * @returns the set of stages at or after a verification gate.
+ */
+export declare function verificationHeldStages(config: WorkflowConfig): Set<string>;
+/**
+ * Why the current state fails the flow's verification requirement, if it does.
+ *
+ * Applies only once the task has reached a stage that sits at or after a
+ * verification gate, so it never fires on a task that has not yet had anything
+ * to verify. Completion and commit share this rule, which is what stops a failed
+ * re-verification from being outrun by advancing to a stage whose own outgoing
+ * edge happens not to repeat the guard.
+ * @param state - the task state.
+ * @param config - the frozen workflow config.
+ * @returns human-readable blockers; empty when the requirement does not apply or holds.
+ */
+export declare function verificationBlockers(state: TaskState, config: WorkflowConfig): string[];
 /**
  * Decide whether the current task state permits a commit and with what label.
  *
@@ -257,6 +497,128 @@ export interface CommitCheckpoint {
  * hold, so the engine cannot be asked to commit before its own state is valid.
  */
 export declare function commitCheckpoint(state: TaskState, config: WorkflowConfig): CommitCheckpoint;
+/**
+ * Whether a stage is terminal in the configured graph (no outgoing transition).
+ * @param stage - the stage to test.
+ * @param config - the frozen workflow config.
+ * @returns true when nothing follows this stage.
+ */
+export declare function isTerminalStage(stage: string, config: WorkflowConfig): boolean;
+/**
+ * Whether the delivery mode requires a recorded commit before completion.
+ * @param config - the frozen workflow config.
+ * @returns true when a commit must be recorded (the historical default).
+ */
+export declare function commitRequired(config: WorkflowConfig): boolean;
+/**
+ * Every reason the task may not be marked complete.
+ *
+ * Completion is its own fact, checked here rather than inferred from standing on
+ * the last stage. Three things can hold it back: the task has not reached a
+ * terminal stage, the flow's own `todos_done` conditions are unmet, or the
+ * delivery mode wants a commit that is not recorded. Deliberately NOT included:
+ * a blanket demand for a commit on every flow, because a commit is one delivery
+ * mode rather than a universal finish line.
+ * @param state - the task state.
+ * @param config - the frozen workflow config.
+ * @returns human-readable blockers; empty when the task may complete.
+ */
+/**
+ * Configurations a stage needs but that cannot be resolved.
+ *
+ * Disclosure is not enforcement. `missing_rules` was reported in status and never
+ * blocked anything, so deleting a rule a stage was bound to still let the task
+ * advance — leaving a stage running without the constraints it was configured
+ * with, while the record looked fine.
+ *
+ * This is a pure decision over names, so the tool and the hook reach the same
+ * verdict from the same inputs. It takes the unresolved names rather than reading
+ * anything, because resolution needs a filesystem and this must stay callable from
+ * both planes.
+ * @param unresolved - references that resolved nowhere, as `source:name` or a bare legacy name.
+ * @param stage - the stage whose configuration is being checked.
+ * @returns one blocker per unresolved resource, empty when the stage is complete.
+ */
+export declare function resourceBlockers(unresolved: readonly string[], stage: string): string[];
+/**
+ * The outcomes a flow's FINAL stage is required to have, derived from its guards.
+ *
+ * Completion used to check only standing-on-a-final-stage, unfinished items and
+ * whether a commit existed. A flow that declares `review_passed` or `verified` on
+ * its way into the terminal stage was therefore satisfiable by ARRIVING there: the
+ * agile flow's review verdict and the standard flow's verification could both be
+ * failing while `complete` succeeded.
+ *
+ * Derived rather than hardcoded, because a flow that declares no verification gate
+ * must not be made to demand one — the requirement is whatever the flow said.
+ * @param config - the effective workflow.
+ * @returns the guard names the final stage's incoming edges require.
+ */
+export declare function terminalRequirements(config: WorkflowConfig): GuardName[];
+export declare function completionBlockers(state: TaskState, config: WorkflowConfig): string[];
+/**
+ * Which recorded conclusions a rework of the given kind invalidates.
+ *
+ * Derived from what each kind of change actually supersedes:
+ *
+ * - `requirement`: the agreed requirement changed, so its confirmation no longer
+ *   speaks for the work, and neither does the solution built on it. Verification,
+ *   review and item audits all judged a tree derived from the old requirement.
+ * - `solution`: the requirement stands, but the approach changed. Its confirmation
+ *   falls, along with everything that judged the implementation of the old one.
+ * - `defect`: a defect in the work as specified. The requirement and solution stay
+ *   agreed; what falls is the evidence that the OLD implementation was correct —
+ *   verification, review, and the per-item audits.
+ *
+ * A confirmation is always re-askable rather than silently assumed, because the
+ * human who approved it approved a different thing.
+ * @param kind - the kind of change being recorded.
+ * @returns the conclusion names to clear.
+ */
+export declare function invalidatedBy(kind: TaskRevision['kind']): string[];
+/**
+ * The result of applying one rework to a task record.
+ *
+ * Kept separate from the mutation so the caller can report what changed, and so
+ * the clearing rules above are asserted directly in tests.
+ */
+export interface RevisionOutcome {
+    /** The stage the task now sits at. */
+    stage: string;
+    /** The conclusions that were cleared. */
+    invalidated: string[];
+}
+/**
+ * Apply a rework to a task record, clearing exactly the superseded conclusions.
+ *
+ * Confirmation flags are reset rather than deleted because the engine reads them
+ * as booleans; the other conclusions are cleared by removing the record that
+ * carried them, so `status` reports them as absent instead of stale.
+ * @param state - the task state, mutated in place.
+ * @param revision - the rework to apply.
+ * @returns the stage reached and the conclusions cleared.
+ */
+export declare function applyRevision(state: TaskState, revision: TaskRevision): RevisionOutcome;
+/**
+ * A project's `.dsh/eng.json` as read off disk.
+ *
+ * This describes what a file MAY contain so the resolver can narrow it; declaring
+ * only the fields a valid file is allowed would make an invalid one look valid to
+ * the parser and hide the error until much later.
+ */
+export interface ParsedProjectConfig {
+    flow?: string;
+    /** The project's own stage bindings, taken verbatim. */
+    stage_bindings?: Record<string, StageBinding>;
+    /** The project's own commit policy, replacing any preset default. */
+    commit?: CommitRule;
+    /** The project's own artifact declarations. */
+    artifacts?: ArtifactDef[];
+    /** The project's own per-item review depth. */
+    review_depth?: ReviewDepth;
+    /** Whether a recorded commit is required before completion. */
+    commit_required?: boolean;
+}
 export interface FileScopeResult {
     ok: boolean;
     /** Paths outside the declared scope (present only when the scope is set but violated). */