@godv61/dsh-task-engine 0.23.9 → 0.25.0

package/lib/skill-audit.js

@@ -36,18 +36,85 @@ export function obligationStages(state, workflow) {
         && !workflow.transitions.some(edge => edge.from === t.to)).map(t => t.to);
     return [...new Set([state.stage, ...terminalTargets])];
 }
-/** Core skills use their native artifact/verification/commit gates; additions require a command receipt. */
-export function needsSkillReceipt(name) {
+/**
+ * Whether a skill must supply a command receipt, given what it declared.
+ *
+ * A binding may declare how it proves execution. A requirement or design skill
+ * produces a document, and demanding a "real validation command" from it forced an
+ * irrelevant command to satisfy a gate — the evidence existed, just in another
+ * form. Core skills keep their exemption because their native artifact,
+ * verification, review and commit gates already carry the proof.
+ * @param name - the bound skill's name.
+ * @param evidence - the declared evidence kind, if the binding named one.
+ * @returns true when a command receipt is what this binding owes.
+ */
+export function needsSkillReceipt(name, evidence) {
+    if (evidence === 'none' || evidence === 'artifact' || evidence === 'review' || evidence === 'manual')
+        return false;
+    if (evidence === 'command')
+        return true;
     return !CORE_SKILLS.has(name);
 }
+/**
+ * Whether a skill's declared evidence is present for this stage.
+ *
+ * Each kind is satisfied by the record that actually carries that proof, so a
+ * document-producing skill is checked against a recorded artifact and a judging
+ * skill against a review verdict, rather than all of them against a shell receipt.
+ * @param kind - the declared evidence kind.
+ * @param state - the task state.
+ * @param stage - the stage being checked.
+ * @param name - the skill name, which keys `skill_results`.
+ * @param workflow - the effective workflow, for artifact declarations.
+ * @returns the blocker text when the evidence is absent, or an empty array.
+ */
+function evidenceBlockers(kind, state, stage, name, workflow) {
+    switch (kind) {
+        case 'none':
+            return [];
+        case 'artifact': {
+            // Any artifact recorded at this stage proves the skill produced its document.
+            // Requiring a specific id would guess which one, and the workflow already
+            // declares what each stage must record.
+            const declared = workflow.artifacts.filter(artifact => artifact.stage === stage);
+            if (declared.length === 0)
+                return [];
+            const recorded = state.artifacts ?? {};
+            const present = declared.some(artifact => recorded[artifact.id] !== undefined);
+            return present ? [] : [`${stage}: "${name}" declares artifact evidence, but no artifact is recorded at this stage`];
+        }
+        case 'review':
+            return state.review?.outcome === 'pass'
+                ? []
+                : [`${stage}: "${name}" declares review evidence, but no passing review is recorded`];
+        case 'manual':
+            // A human statement is recorded as evidence text on the skill_result; the
+            // engine cannot verify the judgement itself, only that it was made explicitly.
+            return (state.skill_results?.[stage]?.[name]?.evidence ?? []).some(value => value.trim() !== '')
+                ? []
+                : [`${stage}: "${name}" declares manual evidence and needs an explicit recorded statement`];
+        case 'command':
+            return [];
+    }
+}
 export function skillBlockers(state, workflow, session) {
     if (state.execution_version !== 1)
         return [];
     const loaded = loadedSkills(session);
-    return obligationStages(state, workflow).flatMap(stage => (workflow.stage_bindings?.[stage]?.skills ?? []).flatMap(name => {
+    return obligationStages(state, workflow).flatMap(stage => (workflow.stage_bindings?.[stage]?.skills ?? []).flatMap(entry => {
+        // A binding names its skill with a source layer; the loaded set and the
+        // skill_result keys are keyed by name, because DSH's skill tool is addressed
+        // by name. The source decides which layer to resolve, not which key to use.
+        const name = entry.skill.name;
         if (!loaded.has(name))
             return [`${stage}: load skill "${name}" with the skill tool before leaving this stage`];
-        if (!needsSkillReceipt(name))
+        // A declared non-command kind is checked against its own record rather than
+        // falling through to the command requirement, which would demand evidence of a
+        // kind this binding never asked for.
+        if (entry.evidence !== undefined && entry.evidence !== 'command') {
+            return evidenceBlockers(entry.evidence, state, stage, name, workflow);
+        }
+        if (!needsSkillReceipt(name, entry.evidence))
             return [];
         const result = state.skill_results?.[stage]?.[name];
         if (!result || !result.receipt || result.receipt.exit_code !== 0 || result.receipt.aborted || result.receipt.timed_out

package/lib/skill-audit.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-audit.js","sourceRoot":"","sources":["../src/skill-audit.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skill-audit.js","sourceRoot":"","sources":["../src/skill-audit.ts"],"names":[],"mappings":"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"}

package/lib/workflows.d.ts

@@ -1,15 +1,19 @@
 /**
- * Built-in engineering workflows. A workflow is a complete, engine-resolved
- * `WorkflowConfig` a project adopts by id: the stage graph, transition guards,
- * artifacts, commit rule, and default skill/rule bindings are all baked in
- * here. A project overrides only its stage bindings by APPENDING skill/rule
- * names to the preset defaults; every guard, artifact, and commit field stays
- * a fixed property of the chosen preset, so a project cannot hand-edit the gate
- * semantics or cancel a core binding.
+ * Built-in workflow SKELETONS.
+ *
+ * A preset states how work MOVES: the stage graph and the guards on each edge.
+ * It deliberately carries nothing about HOW to do the work, because a preset that
+ * also baked in skills, a commit format and artifact fields would make every
+ * project follow the shipped method whether or not that suits it.
+ *
+ * One reasonable engineering setup per skeleton is offered separately as a
+ * {@link FlowRecommendation}, and enters a project only when a user adopts it
+ * explicitly. After adoption those values are the user's own config: edited,
+ * extended or removed, with nothing merged back by a later version.
  *
  * @module dsh-task-engine/workflows
  */
-import type { StageBinding, WorkflowConfig } from './engine.ts';
+import type { ArtifactDef, CommitRule, ReviewDepth, StageBinding, WorkflowConfig } from './engine.ts';
 /** A preset workflow a project can select by id. */
 export interface FlowOption {
     id: string;
@@ -26,6 +30,42 @@ export interface FlowPreset extends FlowOption {
     capabilities: WorkflowCapability[];
     /** The complete engine config this preset resolves to. */
     config: WorkflowConfig;
+    /**
+     * An optional ready-made engineering setup a user may ADOPT into their own
+     * config: stage bindings, commit format and artifact fields reflecting one
+     * reasonable way of working.
+     *
+     * Separate from `config` on purpose. The skeleton states how the work moves;
+     * the recommendation states one opinion about how to do it. A preset that also
+     * imposed its recommendation would make every project follow the shipped method
+     * whether or not that suits it — the opposite of letting the user decide.
+     * Nothing here takes effect until a user adopts it, and once adopted the values
+     * are theirs: edited, extended, or removed like any other config, never
+     * silently merged back.
+     */
+    recommendation?: FlowRecommendation;
+}
+/**
+ * One ready-made engineering setup, offered for explicit adoption.
+ *
+ * Every field is optional because a preset may recommend a commit format without
+ * recommending skills; an adopter receives only what is present.
+ */
+export interface FlowRecommendation {
+    /** Stage bindings to write on adoption. */
+    stage_bindings?: Record<string, StageBinding>;
+    /**
+       * The commit TEXT conventions to write on adoption.
+       *
+       * Partial on purpose: a recommendation supplies only the writing convention —
+       * the message pattern and hint. WHEN a commit gate fires and whether the file
+       * scope is enforced are flow control and stay on the skeleton.
+       */
+    commit?: Partial<CommitRule>;
+    /** Artifact declarations to write on adoption. */
+    artifacts?: ArtifactDef[];
+    /** Per-item review depth to write on adoption. */
+    review_depth?: ReviewDepth;
 }
 /** The selectable preset workflows (shown in the workbench flow picker). */
 export declare const FLOW_OPTIONS: readonly FlowOption[];
@@ -55,6 +95,31 @@ export interface KnownFlow {
     preset: FlowPreset;
 }
 export type FlowResolve = KnownFlow | UnknownFlow;
+/**
+ * Write a preset's recommendation into a config, for a user who asked for it.
+ *
+ * This is the ADOPTION step. It is a deliberate, one-time act: the returned config
+ * is the user's own from then on, and nothing re-applies or re-merges the
+ * recommendation later, so a value the user deletes stays deleted.
+ * @param presetId - the preset whose recommendation to adopt.
+ * @param current - the user's current config, if any values should be kept.
+ * @returns the config with the recommendation applied, or undefined for an unknown preset.
+ */
+export declare function adoptRecommendation(presetId: string, current?: ProjectConfig): ProjectConfig | undefined;
+/**
+ * A project's own configuration, as stored in `.dsh/eng.json`.
+ *
+ * Every field beyond `flow` is optional and is the user's to set. A field that is
+ * absent means "not configured", never "use the built-in value".
+ */
+export interface ProjectConfig {
+    flow: string;
+    stage_bindings?: Record<string, StageBinding>;
+    commit?: CommitRule;
+    artifacts?: ArtifactDef[];
+    review_depth?: ReviewDepth;
+    commit_required?: boolean;
+}
 /**
  * Resolve a preset workflow plus a project's stage-binding additions into the
  * complete engine config. Unknown `flow` ids fail closed with an explicit
@@ -62,8 +127,6 @@ export type FlowResolve = KnownFlow | UnknownFlow;
  * project that names a missing or stale preset stops instead of running the
  * wrong gate.
  * @param flow - workflow id from the project's `.dsh/eng.json`.
- * @param override - optional whole `stage_bindings` map APPENDED to the preset defaults.
+ * @param project - the project's own config, applied verbatim over the skeleton.
  */
-export declare function resolveFlow(flow: string, override?: {
-    stage_bindings?: Record<string, StageBinding>;
-}): FlowResolve;
+export declare function resolveFlow(flow: string, project?: ProjectConfig): FlowResolve;

package/lib/workflows.js

@@ -1,21 +1,47 @@
 /**
- * Built-in engineering workflows. A workflow is a complete, engine-resolved
- * `WorkflowConfig` a project adopts by id: the stage graph, transition guards,
- * artifacts, commit rule, and default skill/rule bindings are all baked in
- * here. A project overrides only its stage bindings by APPENDING skill/rule
- * names to the preset defaults; every guard, artifact, and commit field stays
- * a fixed property of the chosen preset, so a project cannot hand-edit the gate
- * semantics or cancel a core binding.
+ * Built-in workflow SKELETONS.
+ *
+ * A preset states how work MOVES: the stage graph and the guards on each edge.
+ * It deliberately carries nothing about HOW to do the work, because a preset that
+ * also baked in skills, a commit format and artifact fields would make every
+ * project follow the shipped method whether or not that suits it.
+ *
+ * One reasonable engineering setup per skeleton is offered separately as a
+ * {@link FlowRecommendation}, and enters a project only when a user adopts it
+ * explicitly. After adoption those values are the user's own config: edited,
+ * extended or removed, with nothing merged back by a later version.
  *
  * @module dsh-task-engine/workflows
  */
+/**
+ * Build one skill binding from a bare name plus its bundled rules.
+ *
+ * The preset's own bindings are all bundled resources, so the `bundled:` prefix
+ * is applied here rather than repeated at every call site. Project and user
+ * resources enter through a project's config, where their source is explicit.
+ * @param skill - the bundled skill name.
+ * @param rules - bundled rule names that belong to this skill.
+ * @returns the binding.
+ */
+function bundled(skill, ...rules) {
+    const ref = (name) => ({ source: 'bundled', name });
+    return { skill: ref(skill), rules: rules.map(ref) };
+}
 /** The selectable preset workflows (shown in the workbench flow picker). */
 export const FLOW_OPTIONS = [
-    { id: 'standard', label: '标准研发', description: '需求评审 → 设计 → 开发 → 交付 → 代码审核，含产物门 + 确认门' },
-    { id: 'agile', label: '敏捷轻量', description: '需求 → 开发 → 交付 → 审查，四阶段、少产物' },
-    { id: 'minimal', label: '纯代码', description: '开发 → 交付，两阶段，只留提交门禁' },
+    { id: 'standard', label: '完整研发', description: '新功能、架构或跨模块改动、高风险任务：需求确认 → 方案确认 → 实现 → 验证 → 审核 → 提交' },
+    { id: 'agile', label: '日常迭代', description: '目标明确的常规功能与缺陷修复：目标与验收 → 实现 → 验收与审查 → 提交' },
+    { id: 'minimal', label: '快速修改', description: '局部、低风险、方案明确的改动：修改 → 检查与提交' },
 ];
-/** Standard review-gated delivery: the default workflow. */
+/**
+ * Standard review-gated delivery.
+ *
+ * The skeleton states how work MOVES: which stages exist, what may follow what,
+ * and which confirmations or evidence an edge demands. Everything about HOW to do
+ * the work — which skills run, what a commit message must look like, which
+ * artifacts a stage records — lives in {@link STANDARD_RECOMMENDATION} and enters
+ * a project only when the user adopts it.
+ */
 const STANDARD = {
     stages: ['需求评审', '设计', '开发', '交付', '代码审核', '完成'],
     start_stage: '需求评审',
@@ -26,55 +52,92 @@ const STANDARD = {
         { from: '交付', to: '代码审核', requires: ['verified'] },
         { from: '代码审核', to: '完成', requires: ['review_passed', 'artifacts_present'] },
     ],
+    // No artifacts, no commit policy, no skills: the skeleton carries none of them.
+    artifacts: [],
+    commit: { policy: 'task', message_pattern: '', message_hint: '无格式要求', checkpoints: ['代码审核'], file_scope: true },
+    high_risk_requires_verification: true,
+};
+/**
+ * One ready-made setup for the standard flow, offered for explicit adoption.
+ *
+ * This is a recommendation, not a default: it reflects one reasonable way to work
+ * and nothing here takes effect until a user adopts it. After adoption these
+ * values are ordinary user config — edited, extended or removed — and no later
+ * version merges anything back in.
+ */
+const STANDARD_RECOMMENDATION = {
+    commit: {
+        // Only the TEXT conventions. Policy, checkpoints and scope stay on the
+        // skeleton: they decide when a gate fires, not how a message reads.
+        message_pattern: '^【(\\S+)】【(?:TASK|T\\d+)】.+',
+        message_hint: '【<task_id>】【TASK/T1】说明 —— 第一段填本任务 id（如 GREET-001），写结果不写空泛动作',
+    },
     artifacts: [
         { stage: '需求评审', id: 'requirement', name: '需求说明', fields: ['scope', 'acceptance_criteria'] },
         { stage: '设计', id: 'design', name: '设计文档', fields: ['approach', 'risks', 'impact'] },
         { stage: '代码审核', id: 'review', name: '评审记录', fields: ['conclusion', 'issues'] },
     ],
-    commit: {
-        policy: 'task',
-        message_pattern: '^【(\\S+)】【(?:TASK|T\\d+)】.+',
-        message_hint: '【<task_id>】【TASK/T1】说明 —— 第一段填本任务 id（如 GREET-001），写结果不写空泛动作',
-        checkpoints: ['代码审核'],
-        file_scope: true,
-    },
-    high_risk_requires_verification: true,
     stage_bindings: {
-        '需求评审': { skills: ['requirement-analysis'], rules: ['security-redlines'] },
-        '设计': { skills: ['solution-design'] },
-        '开发': { skills: ['code-implement'], rules: ['coding-conventions'] },
-        '交付': { skills: ['code-verify'], rules: ['coding-conventions'] },
-        '代码审核': { skills: ['code-review', 'code-commit'], rules: ['security-redlines', 'commit-conventions'] },
+        '需求评审': { skills: [bundled('requirement-analysis', 'security-redlines')] },
+        '设计': { skills: [bundled('solution-design')] },
+        '开发': { skills: [bundled('code-implement', 'coding-conventions', 'security-redlines')] },
+        '交付': { skills: [bundled('code-verify')] },
+        '代码审核': {
+            skills: [
+                bundled('code-review', 'coding-conventions', 'security-redlines'),
+                bundled('code-commit', 'commit-conventions'),
+            ],
+        },
     },
 };
-/** Lighter four-stage flow with few artifacts, for fast-moving projects. */
+/** Lighter four-stage flow: the skeleton only. */
 const AGILE = {
     stages: ['需求', '开发', '交付', '审查'],
     start_stage: '需求',
     transitions: [
         { from: '需求', to: '开发', requires: ['requirement_confirmation'] },
         { from: '开发', to: '交付', requires: ['todos_done'] },
+        // Entering 审查 is unconditional. A review guard on this edge would be
+        // circular — it would demand the verdict BEFORE the stage that produces it —
+        // and it would also block the commit at 交付, since a commit requires its
+        // stage's outgoing guards. What 审查 requires is declared as completion_guards
+        // instead, because a terminal stage has no outgoing edge to carry it.
         { from: '交付', to: '审查', requires: [] },
     ],
+    artifacts: [],
+    commit: { policy: 'item', message_pattern: '', message_hint: '无格式要求', checkpoints: ['交付'], file_scope: true },
+    high_risk_requires_verification: false,
+    // 审查 is terminal and IS the review, so there is no outgoing edge to carry
+    // the guard. Declaring it here is what makes a blocked review prevent
+    // completion; without it the stage could be reached and finished with the
+    // review failing, which is what the assessment found.
+    completion_guards: ['review_passed'],
+};
+/** One ready-made setup for the agile flow, offered for explicit adoption. */
+const AGILE_RECOMMENDATION = {
+    commit: {
+        // `item` policy emits two label shapes: `T<n>` mid-flow and `TASK` at the
+        // closing checkpoint. The pattern accepts BOTH, so the label the engine hands
+        // the model always satisfies the rule that validates it.
+        message_pattern: '^【(\\S+)】【(?:TASK|T\\d+)】.+',
+        message_hint: '【<task_id>】【TASK/T1】说明 —— 第一段填本任务 id；实施项提交用 T1、T2，收尾提交用 TASK',
+    },
     artifacts: [
         { stage: '需求', id: 'requirement', name: '需求说明', fields: ['scope'] },
+        // The 审查 stage binds code-review, whose instructions write this artifact with
+        // `record artifact=review`. Declaring it keeps that binding executable: the
+        // engine refuses an undeclared artifact, so a bound skill pointing at one would
+        // be a contract the recommendation made impossible to satisfy.
+        { stage: '审查', id: 'review', name: '评审记录', fields: ['conclusion', 'issues'] },
     ],
-    commit: {
-        policy: 'item',
-        message_pattern: '^【(\\S+)】【T\\d+】.+',
-        message_hint: '【<task_id>】【T1】说明 —— 第一段填本任务 id',
-        checkpoints: ['交付'],
-        file_scope: true,
-    },
-    high_risk_requires_verification: false,
     stage_bindings: {
-        '需求': { skills: ['requirement-analysis'] },
-        '开发': { skills: ['code-implement'], rules: ['coding-conventions'] },
-        '交付': { skills: ['code-verify', 'code-commit'], rules: ['commit-conventions'] },
-        '审查': { skills: ['code-review'] },
+        '需求': { skills: [bundled('requirement-analysis', 'security-redlines')] },
+        '开发': { skills: [bundled('code-implement', 'coding-conventions', 'security-redlines')] },
+        '交付': { skills: [bundled('code-verify'), bundled('code-commit', 'commit-conventions')] },
+        '审查': { skills: [bundled('code-review', 'coding-conventions', 'security-redlines')] },
     },
 };
-/** Minimal two-stage flow: only a commit gate, no artifact doors. */
+/** Minimal two-stage flow: the skeleton only. */
 const MINIMAL = {
     stages: ['开发', '交付'],
     start_stage: '开发',
@@ -82,17 +145,18 @@ const MINIMAL = {
         { from: '开发', to: '交付', requires: ['todos_done'] },
     ],
     artifacts: [],
-    commit: {
-        policy: 'task',
-        message_pattern: '',
-        message_hint: '无格式要求',
-        checkpoints: ['交付'],
-        file_scope: false,
-    },
+    commit: { policy: 'task', message_pattern: '', message_hint: '无格式要求', checkpoints: ['交付'], file_scope: false },
     high_risk_requires_verification: false,
+};
+/** One ready-made setup for the minimal flow, offered for explicit adoption. */
+const MINIMAL_RECOMMENDATION = {
+    // A fast-change flow checks each change once, not twice under two headings a
+    // short change rarely distinguishes. The item still has to be reviewed — what
+    // drops is the duplicated verdict, which is where the weight actually was.
+    review_depth: 'single',
     stage_bindings: {
-        '开发': { skills: ['code-implement'] },
-        '交付': { skills: ['code-commit'], rules: ['commit-conventions'] },
+        '开发': { skills: [bundled('code-implement', 'coding-conventions', 'security-redlines')] },
+        '交付': { skills: [bundled('code-commit', 'commit-conventions')] },
     },
 };
 /**
@@ -112,13 +176,27 @@ function deriveCapabilities(config) {
         caps.push('file_scope');
     return caps;
 }
-function preset(id, version, label, description, config) {
-    return { id, version, label, description, capabilities: deriveCapabilities(config), config };
+function preset(id, version, label, description, config, recommendation) {
+    return {
+        id, version, label, description,
+        capabilities: deriveCapabilities(config),
+        config,
+        // exactOptionalPropertyTypes: omit rather than assign undefined.
+        ...(recommendation !== undefined ? { recommendation } : {}),
+    };
 }
 export const FLOW_PRESETS = {
-    standard: preset('standard', 2, '标准研发', '需求评审 → 设计 → 开发 → 交付 → 代码审核，审核后提交', STANDARD),
-    agile: preset('agile', 1, '敏捷轻量', '需求 → 开发 → 交付 → 审查，四阶段、少产物', AGILE),
-    minimal: preset('minimal', 1, '纯代码', '开发 → 交付，两阶段，只留提交门禁', MINIMAL),
+    standard: preset('standard', 3, '完整研发', '新功能、架构或跨模块改动、高风险任务：需求确认 → 方案确认 → 实现 → 验证 → 审核 → 提交', STANDARD, STANDARD_RECOMMENDATION),
+    // Version 4 for agile: 交付 → 审查 now requires review_passed, where it previously
+    // required nothing. That is a gate-semantics change, so a task created before it
+    // keeps its frozen version 3 config and behaves exactly as it did.
+    //
+    // Version 3 across all three: the preset is now a bare skeleton and its former
+    // built-in bindings, commit rule and artifacts are a separate recommendation a
+    // user adopts explicitly. Tasks created before this keep their frozen config and
+    // are unaffected; a project's existing config is likewise left exactly as it is.
+    agile: preset('agile', 4, '日常迭代', '目标明确的常规功能与缺陷修复：目标与验收 → 实现 → 验收与审查 → 提交', AGILE, AGILE_RECOMMENDATION),
+    minimal: preset('minimal', 3, '快速修改', '局部、低风险、方案明确的改动：修改 → 检查与提交，每项一次检查', MINIMAL, MINIMAL_RECOMMENDATION),
 };
 /** Whether `flow` names a built-in workflow. */
 export function isKnownFlow(flow) {
@@ -147,31 +225,88 @@ function dedupe(names) {
     return [...new Set(names)];
 }
 /**
- * Merge a project's stage-binding additions into a preset's defaults without
- * ever removing a core binding. A stage's `skills`/`rules` become the preset
- * defaults followed by the project additions, de-duplicated in order; the seed
- * bindings can therefore never be cancelled by an override, only extended.
+ * Apply a project's own config over a preset skeleton.
+ *
+ * The project's values are taken as given. There is nothing to merge against any
+ * more: the skeleton carries no skills, no commit rule, no artifacts and no
+ * review depth, so whatever the user configured IS the configuration. Earlier
+ * versions merged a project's skills into the preset's built-in set, which had two
+ * consequences this removes — a built-in skill could never be dropped, and an
+ * attempt to give a built-in skill a different rule list was discarded because the
+ * skill reference already existed.
+ *
+ * `stage_bindings` entirely replaces the skeleton's (empty) map; a stage the user
+ * omits simply has no bindings, which is a legitimate state rather than a gap to
+ * be filled from a recommendation.
  */
-function mergeBindings(base, override) {
-    if (override === undefined)
+function applyProjectConfig(base, project) {
+    if (project === undefined)
         return base;
-    let changed = false;
-    const merged = { ...base.stage_bindings };
-    for (const [stage, addition] of Object.entries(override)) {
-        const existing = merged[stage];
-        const skills = dedupe([...(existing?.skills ?? []), ...(addition.skills ?? [])]);
-        const rules = dedupe([...(existing?.rules ?? []), ...(addition.rules ?? [])]);
-        const binding = {};
-        if (skills.length > 0)
-            binding.skills = skills;
-        if (rules.length > 0)
-            binding.rules = rules;
-        merged[stage] = binding;
-        changed = true;
+    const next = { ...base };
+    if (project.stage_bindings !== undefined) {
+        const bindings = {};
+        for (const [stage, binding] of Object.entries(project.stage_bindings)) {
+            const entry = {};
+            if ((binding.skills ?? []).length > 0)
+                entry.skills = [...binding.skills];
+            const legacy = dedupe(binding.legacy_rules ?? []);
+            if (legacy.length > 0)
+                entry.legacy_rules = legacy;
+            bindings[stage] = entry;
+        }
+        next.stage_bindings = bindings;
     }
-    if (!changed)
-        return base;
-    return { ...base, stage_bindings: merged };
+    if (project.commit !== undefined)
+        next.commit = project.commit;
+    if (project.artifacts !== undefined)
+        next.artifacts = project.artifacts;
+    if (project.review_depth !== undefined)
+        next.review_depth = project.review_depth;
+    if (project.commit_required !== undefined)
+        next.commit_required = project.commit_required;
+    return next;
+}
+/**
+ * Write a preset's recommendation into a config, for a user who asked for it.
+ *
+ * This is the ADOPTION step. It is a deliberate, one-time act: the returned config
+ * is the user's own from then on, and nothing re-applies or re-merges the
+ * recommendation later, so a value the user deletes stays deleted.
+ * @param presetId - the preset whose recommendation to adopt.
+ * @param current - the user's current config, if any values should be kept.
+ * @returns the config with the recommendation applied, or undefined for an unknown preset.
+ */
+export function adoptRecommendation(presetId, current) {
+    const preset = FLOW_PRESETS[presetId];
+    if (preset === undefined)
+        return undefined;
+    const rec = preset.recommendation;
+    if (rec === undefined)
+        return { flow: presetId, ...current };
+    // The recommendation supplies a starting point; anything the user already set
+    // wins, so adopting never overwrites an existing decision.
+    //
+    // The commit rule is assembled from BOTH halves, because they live in different
+    // places by design: the skeleton owns when a gate fires and whether the scope is
+    // protected, the recommendation owns how a message reads. Writing the
+    // recommendation's half alone would produce a config with no checkpoints and no
+    // scope protection — the flow control would silently disappear on adoption.
+    const commit = {
+        ...preset.config.commit,
+        ...(rec.commit ?? {}),
+        ...(current?.commit ?? {}),
+    };
+    const config = {
+        flow: presetId,
+        stage_bindings: current?.stage_bindings ?? rec.stage_bindings ?? {},
+        commit,
+        artifacts: current?.artifacts ?? rec.artifacts ?? preset.config.artifacts,
+        ...(current?.review_depth !== undefined
+            ? { review_depth: current.review_depth }
+            : (rec.review_depth !== undefined ? { review_depth: rec.review_depth } : {})),
+        ...(current?.commit_required !== undefined ? { commit_required: current.commit_required } : {}),
+    };
+    return config;
 }
 /**
  * Resolve a preset workflow plus a project's stage-binding additions into the
@@ -180,13 +315,14 @@ function mergeBindings(base, override) {
  * project that names a missing or stale preset stops instead of running the
  * wrong gate.
  * @param flow - workflow id from the project's `.dsh/eng.json`.
- * @param override - optional whole `stage_bindings` map APPENDED to the preset defaults.
+ * @param project - the project's own config, applied verbatim over the skeleton.
  */
-export function resolveFlow(flow, override) {
+export function resolveFlow(flow, project) {
     const preset = FLOW_PRESETS[flow];
     if (preset === undefined) {
         return { ok: false, code: 'UNKNOWN_FLOW', flow, knownFlows: Object.keys(FLOW_PRESETS) };
     }
-    return { ok: true, config: mergeBindings(preset.config, override?.stage_bindings), preset };
+    const { flow: _ignored, ...rest } = project ?? { flow };
+    return { ok: true, config: applyProjectConfig(preset.config, { flow, ...rest }), preset };
 }
 //# sourceMappingURL=workflows.js.map