@chenguangyao/devflow-kit 0.1.43

package/src/cli/commands/deploy.js

@@ -0,0 +1,504 @@
+'use strict';
+const fsSync = require('fs');
+const path = require('path');
+const cp = require('child_process');
+const readline = require('readline');
+const log = require('../../utils/log.js');
+const change = require('../../core/change.js');
+const state = require('../../core/state.js');
+const projects = require('../../core/projects.js');
+const providers = require('../../providers/loader.js');
+const aggregate = require('../../reports/aggregate.js');
+
+async function run({ sub, flags = {}, positional = [], cwd, _providers, _exec, _confirmMerge } = {}) {
+  const root = cwd || process.cwd();
+  const env = sub || positional[0] || flags.env || flags.environment || 'test';
+  const projectName = flags.project || positional[1];
+  const project = await projects.findProject(projectName);
+  if (!project) {
+    log.error(`deploy blocked: project not found: ${projectName || '(missing)'}`);
+    process.exitCode = 1;
+    return;
+  }
+  const job = project.jenkins && project.jenkins[env];
+  if (!job) {
+    log.error(`deploy blocked: no Jenkins job configured for project=${project.name || projectName} env=${env}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const ci = _providers && _providers.ci ? _providers.ci : await providers.load(root, { type: 'ci' });
+  const params = buildParams({ env, projectName: project.name || projectName, project, job, flags });
+  const exec = _exec || spawn;
+  const prep = await prepareDeployment({
+    root,
+    env,
+    project,
+    projectName: project.name || projectName,
+    flags,
+    exec,
+    confirmMerge: _confirmMerge || confirmMerge,
+  });
+  if (prep.status === 'fail') {
+    log.error(`deploy blocked: ${prep.error}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = await ci.trigger(job, params);
+  let status = { status: 'triggered', url: result.url };
+  if (flags.wait === true || flags.wait === 'true') {
+    status = await ci.status(result.runId || result.url);
+  }
+
+  const slug = flags.slug || await change.getCurrent(root);
+  if (slug) {
+    await writeDeployReport({ root, slug, env, projectName: project.name || projectName, job, params, result, status, prep });
+    const updateSelfTest = flags.updateSelfTest === true || flags['update-self-test'] === true;
+    if (updateSelfTest) {
+      await writeSelfTestReport({ root, slug, env, projectName: project.name || projectName, status, result });
+    }
+    const st = await state.read(root, slug).catch(() => null);
+    if (st) {
+      st.deployments = st.deployments || [];
+      st.deployments.push({
+        env,
+        project: project.name || projectName,
+        job,
+        runId: result.runId || null,
+        url: result.url || null,
+        status: status.status,
+        branchPrepared: prep.branch && prep.branch.status === 'done',
+        preflight: prep.preflight && prep.preflight.status,
+        ts: new Date().toISOString(),
+      });
+      state.logEvent(st, 'deploy.trigger', { env, project: project.name || projectName, runId: result.runId || null });
+      await state.write(root, slug, st);
+    }
+  }
+
+  log.ok(`deploy ${env}: ${project.name || projectName} -> ${result.url || result.runId || 'triggered'}`);
+  log.dim(`next: devflow test smoke --project=${project.name || projectName} --env=${env}`);
+  log.dim('deployment evidence: reports/test-report.md#deploy; add --update-self-test only when you want to refresh self-test section');
+  log.dim('next: devflow verify finalize');
+  if (isFailureStatus(status.status)) process.exitCode = 1;
+}
+
+function buildParams({ env, projectName, project, job, flags }) {
+  const configuredParams = configuredDeployParams(project, env);
+  const explicitParams = parseCliParams(flags.param || flags.params || flags.parameter);
+  const hasExplicitJenkinsParams =
+    isUrl(job) ||
+    hasParameterizedEndpoint(job) ||
+    Object.keys(configuredParams).length > 0 ||
+    Object.keys(explicitParams).length > 0;
+  const includeDefaults = resolveIncludeDefaultParams(project, env, flags, !hasExplicitJenkinsParams);
+  const params = {};
+  if (includeDefaults) {
+    params.env = env;
+    params.project = projectName;
+  }
+  Object.assign(params, configuredParams);
+  if (flags.branch) params.branch = flags.branch;
+  if (flags.tag) params.tag = flags.tag;
+  if (flags.commit) params.commit = flags.commit;
+  if (flags.ref) params.ref = flags.ref;
+  Object.assign(params, explicitParams);
+  return params;
+}
+
+function configuredDeployParams(project, env) {
+  const raw = envConfig(project, env, 'params') || envConfig(project, env, 'parameters');
+  return normalizeParams(raw);
+}
+
+function normalizeParams(raw) {
+  if (!raw) return {};
+  if (typeof raw === 'object' && !Array.isArray(raw)) return { ...raw };
+  return parseParamString(raw);
+}
+
+function parseCliParams(raw) {
+  if (Array.isArray(raw)) {
+    return raw.reduce((acc, item) => ({ ...acc, ...parseParamString(item) }), {});
+  }
+  return parseParamString(raw);
+}
+
+function parseParamString(raw) {
+  if (!raw || raw === true) return {};
+  const text = String(raw).trim();
+  if (!text) return {};
+  if (text.startsWith('{')) {
+    try {
+      const parsed = JSON.parse(text);
+      return normalizeParams(parsed);
+    } catch {
+      return {};
+    }
+  }
+  const out = {};
+  for (const part of text.split(/[,&]/)) {
+    const eq = part.indexOf('=');
+    if (eq === -1) continue;
+    const key = part.slice(0, eq).trim();
+    const value = part.slice(eq + 1).trim();
+    if (key) out[key] = value;
+  }
+  return out;
+}
+
+function resolveIncludeDefaultParams(project, env, flags, fallback) {
+  const raw = flags.includeDefaultParams !== undefined
+    ? flags.includeDefaultParams
+    : flags.defaultParams !== undefined
+      ? flags.defaultParams
+      : envConfig(project, env, 'includeDefaultParams') !== undefined
+        ? envConfig(project, env, 'includeDefaultParams')
+        : envConfig(project, env, 'defaultParams');
+  if (raw === undefined) return fallback;
+  return !(raw === false || raw === 'false' || raw === '0' || raw === 'no');
+}
+
+function hasParameterizedEndpoint(job) {
+  if (!isUrl(job)) return false;
+  try {
+    const u = new URL(String(job));
+    return /\/buildWithParameters\/?$/i.test(u.pathname);
+  } catch {
+    return /\/buildWithParameters(?:\?|$)/i.test(String(job || ''));
+  }
+}
+
+function isUrl(value) {
+  return /^https?:\/\//i.test(String(value || ''));
+}
+
+async function prepareDeployment({ root, env, project, projectName, flags, exec, confirmMerge }) {
+  const repoDir = path.resolve(flags.repo || flags.repoDir || flags['repo-dir'] || project.localPath || project.worktreePath || root);
+  const out = { status: 'ok', repoDir, branch: null, preflight: null };
+
+  const explicitMergeTo = flags['merge-to'] || flags.mergeTo || envConfig(project, env, 'mergeTo') || envConfig(project, env, 'branch');
+  const defaultTarget = env === 'test' ? 'test' : null;
+  const mergeTo = explicitMergeTo || defaultTarget;
+  if (mergeTo) {
+    const sourceBranch = flags.branch || flags.sourceBranch || currentBranch(repoDir, exec);
+    if (!sourceBranch) {
+      if (explicitMergeTo) return { ...out, status: 'fail', error: 'cannot determine source branch for --merge-to' };
+    } else if (sourceBranch === String(mergeTo)) {
+      out.branch = { status: 'already_on_target', source: sourceBranch, target: String(mergeTo), push: false };
+    } else if (!explicitMergeTo) {
+      const ok = await confirmMerge({
+        projectName,
+        env,
+        repoDir,
+        sourceBranch,
+        targetBranch: String(mergeTo),
+      });
+      if (!ok) {
+        return {
+          ...out,
+          status: 'fail',
+          error: `current branch is ${sourceBranch}; merge to ${mergeTo} was not confirmed`,
+          branch: { status: 'declined', source: sourceBranch, target: String(mergeTo), push: false },
+        };
+      }
+      out.branch = runMergeCommands({ repoDir, sourceBranch, mergeTo, flags, exec });
+      if (out.branch.status === 'fail') return { ...out, status: 'fail', error: out.branch.error };
+    } else {
+      out.branch = runMergeCommands({ repoDir, sourceBranch, mergeTo, flags, exec });
+      if (out.branch.status === 'fail') return { ...out, status: 'fail', error: out.branch.error };
+    }
+  }
+
+  const preflight = resolvePreflightCommand(project, env, flags, repoDir);
+  if (preflight) {
+    const r = exec('sh', ['-c', preflight], { cwd: repoDir, encoding: 'utf8', shell: false });
+    out.preflight = {
+      status: r.status === 0 ? 'pass' : 'fail',
+      command: preflight,
+      output: truncate(((r.stdout || '') + (r.stderr || '')).trim(), 4000),
+    };
+    if (r.status !== 0) {
+      return {
+        ...out,
+        status: 'fail',
+        error: `preflight failed: ${preflight}`,
+      };
+    }
+  }
+
+  return out;
+}
+
+function runMergeCommands({ repoDir, sourceBranch, mergeTo, flags, exec }) {
+  const pushEnabled = !(flags['no-push'] === true || flags.noPush === true || flags.push === false || flags.push === 'false');
+  const commands = [
+    ['git', ['fetch', 'origin']],
+    ['git', ['checkout', String(mergeTo)]],
+    ['git', ['pull', 'origin', String(mergeTo)]],
+    ['git', ['merge', String(sourceBranch), '--no-edit']],
+  ];
+  if (pushEnabled) commands.push(['git', ['push', 'origin', String(mergeTo)]]);
+  commands.push(['git', ['checkout', String(sourceBranch)]]);
+  for (const [cmd, args] of commands) {
+    const r = exec(cmd, args, { cwd: repoDir, encoding: 'utf8' });
+    if (r.status !== 0) {
+      return {
+        status: 'fail',
+        error: `${cmd} ${args.join(' ')} failed${r.stderr ? `: ${String(r.stderr).trim()}` : ''}`,
+        source: sourceBranch,
+        target: String(mergeTo),
+        push: pushEnabled,
+      };
+    }
+  }
+  return { status: 'done', source: sourceBranch, target: String(mergeTo), push: pushEnabled };
+}
+
+function spawn(cmd, args, opts = {}) {
+  return cp.spawnSync(cmd, args, { encoding: 'utf8', ...opts });
+}
+
+function envConfig(project, env, key) {
+  const deploy = project && project.deploy;
+  if (!deploy) return undefined;
+  if (deploy[env] && deploy[env][key] !== undefined) return deploy[env][key];
+  return deploy[key];
+}
+
+function currentBranch(repoDir, exec) {
+  const r = exec('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: repoDir, encoding: 'utf8' });
+  if (r.status !== 0) return null;
+  const branch = String(r.stdout || '').trim();
+  return branch && branch !== 'HEAD' ? branch : null;
+}
+
+async function confirmMerge({ projectName, env, repoDir, sourceBranch, targetBranch }) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY || process.env.CI) {
+    log.error(`deploy ${env}: current branch is ${sourceBranch}, Jenkins target branch is ${targetBranch}.`);
+    log.dim(`rerun with: devflow deploy ${env} --project=${projectName} --merge-to=${targetBranch}`);
+    return false;
+  }
+  log.warn(`current branch is ${sourceBranch}; Jenkins deploy should use ${targetBranch}.`);
+  log.dim(`repo: ${repoDir}`);
+  const answer = await ask(`merge ${sourceBranch} -> ${targetBranch}, push, then trigger Jenkins? [Y/n] `, 'Y');
+  const lc = answer.trim().toLowerCase();
+  return lc === '' || lc === 'y' || lc === 'yes';
+}
+
+function ask(q, def = '') {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(q, (answer) => {
+      rl.close();
+      resolve(answer || def);
+    });
+  });
+}
+
+function resolvePreflightCommand(project, env, flags, repoDir) {
+  if (flags['skip-preflight'] === true || flags.skipPreflight === true) return null;
+  if (flags.preflight && flags.preflight !== true) return String(flags.preflight);
+  if (flags['preflight-cmd']) return String(flags['preflight-cmd']);
+  const configured = envConfig(project, env, 'preflight') || envConfig(project, env, 'preflightCommand');
+  if (configured) return String(configured);
+  if (flags.preflight === true || flags.preflight === 'true') return autoPreflightCommand(repoDir);
+  return null;
+}
+
+function autoPreflightCommand(repoDir) {
+  if (fsSync.existsSync(path.join(repoDir, 'go.mod'))) return 'go build ./...';
+  if (fsSync.existsSync(path.join(repoDir, 'pom.xml'))) return 'mvn compile -q -DskipTests';
+  if (fsSync.existsSync(path.join(repoDir, 'setup.py')) || fsSync.existsSync(path.join(repoDir, 'pyproject.toml'))) return 'python -m compileall .';
+  const pkg = path.join(repoDir, 'package.json');
+  if (fsSync.existsSync(pkg)) {
+    try {
+      const json = JSON.parse(fsSync.readFileSync(pkg, 'utf8'));
+      if (json.scripts && json.scripts.build) return 'npm run build';
+    } catch { /* ignore */ }
+  }
+  return null;
+}
+
+async function writeDeployReport({ root, slug, env, projectName, job, params, result, status, prep }) {
+  const reportsDir = await change.ensureSubdir(root, slug, 'reports');
+  const body = [
+    '---',
+    `slug: ${slug}`,
+    'kind: deploy',
+    `env: ${env}`,
+    `project: ${projectName}`,
+    `status: ${status.status || 'triggered'}`,
+    `ts: ${new Date().toISOString()}`,
+    '---',
+    '',
+    `# 部署报告(${env})`,
+    '',
+    '| 项 | 值 |',
+    '| --- | --- |',
+    `| 项目 | ${projectName} |`,
+    `| 环境 | ${env} |`,
+    `| Jenkins job | ${job} |`,
+    `| runId | ${result.runId || '-'} |`,
+    `| URL | ${result.url || '-'} |`,
+    `| 状态 | ${status.status || 'triggered'} |`,
+    `| 代码库 | ${(prep && prep.repoDir) || '-'} |`,
+    '',
+    '## 参数',
+    '',
+    '```json',
+    JSON.stringify(params, null, 2),
+    '```',
+    '',
+    '## 分支准备',
+    '',
+    renderBranchPrep(prep),
+    '',
+    '## 本地编译预检',
+    '',
+    renderPreflight(prep),
+    '',
+  ].join('\n');
+  await aggregate.upsertReport({
+    reportsDir,
+    slug,
+    title: slug,
+    kind: 'deploy',
+    body,
+    meta: { status: normalizeDeployStatus(status.status) },
+  });
+}
+
+async function writeSelfTestReport({ root, slug, env, projectName, status, result }) {
+  const reportsDir = await change.ensureSubdir(root, slug, 'reports');
+  const deployReport = 'reports/test-report.md#deploy';
+  const reportStatus = {
+    unit: readReportStatus(reportsDir, 'unit-test.md'),
+    integration: readReportStatus(reportsDir, 'integration-test.md'),
+    e2e: readReportStatus(reportsDir, 'e2e-test.md'),
+    joint: readReportStatus(reportsDir, 'joint-test.md'),
+    remote: readReportStatus(reportsDir, 'remote-test.md'),
+    smoke: readReportStatus(reportsDir, 'smoke-test.md'),
+  };
+  const selfStatus = deploymentSelfTestStatus(status.status, reportStatus.smoke);
+  const body = [
+    '---',
+    `slug: ${slug}`,
+    'kind: self-test',
+    `status: ${selfStatus}`,
+    `env: ${env}`,
+    `project: ${projectName}`,
+    `ts: ${new Date().toISOString()}`,
+    '---',
+    '',
+    `# 提测自测报告 - ${projectName}`,
+    '',
+    '## 部署证据',
+    '',
+    '| 项 | 值 |',
+    '| --- | --- |',
+    `| 环境 | ${env} |`,
+    `| 部署报告 | ${deployReport} |`,
+    `| Jenkins | ${result.url || result.runId || '-'} |`,
+    `| 部署状态 | ${status.status || 'triggered'} |`,
+    '',
+    '## 测试覆盖',
+    '',
+    '| 类型 | 报告 | 状态 |',
+    '| --- | --- | --- |',
+    `| 单元测试 | reports/test-report.md#unit | ${reportStatus.unit} |`,
+    `| 集成测试 | reports/test-report.md#integration | ${reportStatus.integration} |`,
+    `| 端到端测试 | reports/test-report.md#e2e | ${reportStatus.e2e} |`,
+    `| 联调测试 | reports/test-report.md#joint | ${reportStatus.joint} |`,
+    `| 远程 API | reports/test-report.md#remote | ${reportStatus.remote} |`,
+    `| 冒烟测试 | reports/test-report.md#smoke | ${reportStatus.smoke} |`,
+    '',
+    '## 结论',
+    '',
+    selfStatus === 'pass'
+      ? '- 已完成部署并通过部署后自测证据，可提测。'
+      : '- 部署后自测证据未完全通过，请补齐 smoke/API/联调报告后再提测。',
+    '',
+  ].join('\n');
+  await aggregate.upsertReport({
+    reportsDir,
+    slug,
+    title: slug,
+    kind: 'self-test',
+    body,
+    meta: { status: selfStatus },
+  });
+}
+
+function renderBranchPrep(prep) {
+  if (!prep || !prep.branch) return '- 未启用。使用 `--merge-to=<branch>` 或项目 deploy 配置开启。';
+  const b = prep.branch;
+  return [
+    `- 状态: ${b.status}`,
+    `- 分支: ${b.source} -> ${b.target}`,
+    `- 是否推送: ${b.push ? '是' : '否'}`,
+  ].join('\n');
+}
+
+function renderPreflight(prep) {
+  if (!prep || !prep.preflight) return '- 未启用。使用 `--preflight`、`--preflight-cmd` 或项目 deploy 配置开启。';
+  return [
+    `- 状态: ${prep.preflight.status}`,
+    `- 命令: \`${prep.preflight.command}\``,
+    '',
+    '```',
+    prep.preflight.output || '',
+    '```',
+  ].join('\n');
+}
+
+function readReportStatus(reportsDir, name) {
+  const file = path.join(reportsDir, name);
+  if (!fsSync.existsSync(file)) {
+    const agg = aggregate.readAggregate(reportsDir);
+    const kind = name.replace(/-test\.md$/, '');
+    const found = agg.reports.find((r) => r.kind === kind);
+    return found ? found.status : 'missing';
+  }
+  const content = fsSync.readFileSync(file, 'utf8');
+  const m = content.match(/^status:\s*([^\s]+)/m);
+  return m ? m[1] : 'present';
+}
+
+function deploymentSelfTestStatus(deployStatus, smokeStatus) {
+  if (isFailureStatus(deployStatus) || smokeStatus === 'fail') return 'fail';
+  if (isSuccessStatus(deployStatus) && smokeStatus === 'pass') return 'pass';
+  return 'draft';
+}
+
+function normalizeDeployStatus(status) {
+  if (isFailureStatus(status)) return 'fail';
+  if (status === 'success' || status === 'pass' || status === 'completed') return 'pass';
+  return 'pending';
+}
+
+function isSuccessStatus(s) {
+  return ['success', 'succeeded', 'pass', 'passed', 'completed', 'done'].includes(String(s || '').toLowerCase());
+}
+
+function isFailureStatus(s) {
+  return ['fail', 'failed', 'failure', 'error', 'aborted', 'cancelled', 'canceled'].includes(String(s || '').toLowerCase());
+}
+
+function truncate(s, max) {
+  const text = String(s || '');
+  return text.length > max ? text.slice(0, max) + `\n... [${text.length - max} bytes truncated]` : text;
+}
+
+module.exports = {
+  run,
+  _internals: {
+    buildParams,
+    prepareDeployment,
+    writeDeployReport,
+    writeSelfTestReport,
+    deploymentSelfTestStatus,
+    autoPreflightCommand,
+  },
+};

package/src/cli/commands/design.js

@@ -0,0 +1,158 @@
+'use strict';
+const fs = require('fs/promises');
+const path = require('path');
+const log = require('../../utils/log.js');
+const paths = require('../../core/paths.js');
+const state = require('../../core/state.js');
+const change = require('../../core/change.js');
+const checkpoint = require('../../core/checkpoint.js');
+const helpers = require('./_helpers.js');
+
+async function run({ flags = {}, positional = [], cwd }) {
+  const root = cwd || process.cwd();
+  const slug = await helpers.resolveSlug(root, flags, positional);
+  if (!slug) { process.exitCode = 1; return; }
+  const st = await helpers.loadStateOrFail(root, slug);
+  if (!st) { process.exitCode = 1; return; }
+
+  if (st.mode === 'micro' || st.level === 'L0') {
+    log.error('design skipped: this change is L0 micro mode. Upgrade to L1 before running tech-spec.');
+    log.dim(`run: devflow status set-level L1 --slug=${slug} --reason="micro scope expanded"`);
+    process.exitCode = 1;
+    return;
+  }
+  if (helpers.blockWorkflowStep(root, st, slug, 'design', 'design')) return;
+
+  if (await blockPendingCheckpoint(root, slug, st, flags, ['problem_card', 'project_confirmation'], 'design')) return;
+
+  await helpers.writePhaseArtifact(root, slug, st, 'design.md', 'design.md', {});
+
+  const wantsTests = flags['with-tests'] || flags.withTests || st.level === 'L3';
+  if (wantsTests) {
+    await helpers.writePhaseArtifact(root, slug, st, 'tests.md', 'tests.md', {});
+    st.enabled = st.enabled || {};
+    st.enabled['tests.md'] = true;
+  }
+
+  // Spec delta is useful only when this change updates long-lived capabilities.
+  // Keep it explicit so simple changes do not get an empty delta folder.
+  const wantsSpec = !!(flags['with-spec'] || flags.withSpec);
+  const skipDelta = !!(flags['no-delta'] || flags.noDelta);
+  if (wantsSpec && !skipDelta) {
+    const deltaDir = await change.ensureSubdir(root, slug, 'delta');
+    const sample = path.join(deltaDir, 'sample-capability.md');
+    if (!(await fileExists(sample))) {
+      await fs.writeFile(sample, sampleDelta(slug), 'utf8');
+      log.ok(`delta/sample-capability.md — rename & fill for each changed capability`);
+    }
+    st.enabled = st.enabled || {};
+    st.enabled['delta'] = true;
+  }
+
+  state.setPhase(st, 'requirement', 'completed');
+  state.setPhase(st, 'design', 'in_progress');
+  helpers.completeWorkflowStep(st, 'design');
+  state.logEvent(st, 'design scaffold');
+  await state.write(root, slug, st);
+  log.dim('next: devflow plan');
+}
+
+async function blockPendingCheckpoint(root, slug, st, flags, types, commandName) {
+  const pending = checkpoint.latestPendingByTypes(st, types);
+  if (!pending) return false;
+  if (!flags.force) {
+    log.error(`${commandName} blocked: pending ${pending.type} checkpoint.`);
+    log.raw('');
+    log.raw(checkpoint.renderNextStepCard(pending));
+    log.dim(`override: devflow ${commandName} --force --reason="..."`);
+    process.exitCode = 1;
+    return true;
+  }
+  if (!flags.reason) {
+    log.error(`${commandName} --force requires --reason`);
+    process.exitCode = 2;
+    return true;
+  }
+  state.logEvent(st, `${commandName}.force_bypass_checkpoint`, {
+    checkpoint: pending.id,
+    type: pending.type,
+    reason: flags.reason,
+  });
+  await state.write(root, slug, st);
+  log.warn(`${commandName}: force-bypassed pending ${pending.type} checkpoint`);
+  return false;
+}
+
+async function fileExists(f) { try { await fs.access(f); return true; } catch { return false; } }
+
+function sampleDelta(slug) {
+  return `---
+slug: ${slug}
+capability: <domain>/<capability-name>
+---
+
+# delta: ADDED specs/<domain>/spec.md
+
+> **OpenSpec 风格 delta** — \`devflow archive\` 时按 \`capability\` 的业务域落盘到对应 spec 文件。
+>
+> 使用步骤：
+> 1. 修改 frontmatter \`capability\` 为 \`<业务域>/<能力名>\`
+>    - 例：\`coupon/grant\`  → 落盘到 \`specs/coupon/spec.md\`
+>    - 例：\`order/create\` → 落盘到 \`specs/order/spec.md\`
+> 2. 重命名本文件为 \`<capability-name>.md\`（便于阅读，不影响落盘路径）
+> 3. 填写 ADDED / MODIFIED / REMOVED Requirements（只保留本次涉及的块）
+> 4. MODIFIED / REMOVED 的 \`### heading\` 必须与目标 spec **一字不差**
+
+## ADDED Requirements
+
+### Requirement: <业务能力名>
+
+系统 SHALL <描述该业务能力对外承诺>。
+
+1. 系统 MUST <约束 1>
+2. 系统 MUST <约束 2>
+3. 系统 SHOULD <约束 3>
+
+#### Scenario: <场景名>
+
+- **WHEN** <触发条件>
+- **THEN** 系统 MUST <结果>
+- **AND** <补充断言>
+
+---
+
+## MODIFIED Requirements
+
+<!-- 若本次无修改，删除整块 -->
+### Requirement: <既有业务能力名>
+
+<!-- heading 必须与 specs/<domain>/spec.md 中的 ### 完全一致，否则 archive 会报 delta_conflict -->
+<!-- 改动示例 -->
+- ~~旧描述 / 旧约束~~
+- 新描述 / 新约束
+
+---
+
+## REMOVED Requirements
+
+<!-- 若本次无删除，删除整块 -->
+### Requirement: <废弃业务能力名>
+
+下线原因：...
+下线时间：YYYY-QX
+
+---
+
+## REJECTED Alternatives
+
+<!-- 记录否决的备选方案，帮助后人理解决策背景 -->
+### 备选方案名称
+
+**否决原因**：
+- 理由 1
+- 理由 2
+
+`;
+}
+
+module.exports = { run };

package/src/cli/commands/disable.js

@@ -0,0 +1,21 @@
+'use strict';
+const log = require('../../utils/log.js');
+const state = require('../../core/state.js');
+const helpers = require('./_helpers.js');
+
+async function run({ flags = {}, positional = [], cwd }) {
+  const root = cwd || process.cwd();
+  const feature = positional[0];
+  if (!feature) { log.error('usage: devflow disable <feature>'); process.exitCode = 2; return; }
+  const slug = await helpers.resolveSlug(root, flags, positional.slice(1));
+  if (!slug) { process.exitCode = 1; return; }
+  const st = await helpers.loadStateOrFail(root, slug);
+  if (!st) { process.exitCode = 1; return; }
+  st.enabled = st.enabled || {};
+  st.enabled[feature] = false;
+  state.logEvent(st, `disable ${feature}`);
+  await state.write(root, slug, st);
+  log.ok(`disabled: ${feature}`);
+}
+
+module.exports = { run };