@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/runtime/plan-content.js

@@ -0,0 +1,324 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * Row 134: what a plan says, checked deterministically, beside the task-graph verdict
+ * `planVerdict` makes. Each finding carries a `path:line` locator and a severity:
+ * - `fix`: the plan has a hole the self-review must close (an untraced requirement id, a placeholder);
+ * - `refuses-exit`: the planning stage cannot complete while it stands;
+ * - `advisory`: recorded and reported, never blocking.
+ * Read-only: nothing here writes.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { REPO_ROOT } = require('../helper/repo-root.js');
+
+                                                                                                                                         
+
+/** The visible Markdown of a file: fenced code blanked and HTML comments removed, and inline code
+ * spans too unless `keepCode` is set, so a placeholder quoted as an example, a table left in a
+ * comment or a template's guidance is not read. A fence closes only on its own character, a run at
+ * least as long as its opener and nothing after it (CommonMark; doc_quality_checker.py since row
+ * 132). Line numbers are kept: index i is line i + 1. */
+function proseLines(text        , { keepCode = false }                         = {})           {
+  const out           = [];
+  let fence                = null;
+  let comment = false;
+  for (const raw of text.split(/\r?\n/)) {
+    const run = raw.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+    if (fence === null && run && !(run[1][0] === '`' && run[2].includes('`'))) { fence = run[1]; out.push(''); continue; }
+    if (fence !== null) {
+      if (run && run[1][0] === fence[0] && run[1].length >= fence.length && run[2].trim() === '') fence = null;
+      out.push('');
+      continue;
+    }
+    let line = raw;
+    let kept = '';
+    while (line.length) {
+      if (comment) {
+        const end = line.indexOf('-->');
+        if (end === -1) { line = ''; break; }
+        comment = false;
+        line = line.slice(end + 3);
+      } else {
+        const start = line.indexOf('<!--');
+        if (start === -1) { kept += line; break; }
+        kept += line.slice(0, start);
+        comment = true;
+        line = line.slice(start + 4);
+      }
+    }
+    out.push(keepCode ? kept : kept.replace(/`[^`]*`/g, ''));
+  }
+  return out;
+}
+
+const PLACEHOLDERS = [
+  /\b(?:TBD|TODO|FIXME)\b/,
+  /\bto be (?:decided|determined|defined)\b/i,
+  // "later" only as a placeholder phrasing: "fill in later", or alone as a table cell. Prose such
+  // as "later phases" or "add filters later" is a plan, not a hole.
+  /\bfill(?: it)? in later\b/i,
+  /\|\s*later\s*(?=\|)/i,
+];
+
+function placeholderFindings(text        , displayPath        )            {
+  const findings            = [];
+  proseLines(text).forEach((line, index) => {
+    const hit = PLACEHOLDERS.map((re) => line.match(re)).find(Boolean);
+    if (!hit) return;
+    findings.push({
+      rule: 'placeholder', severity: 'fix', path: displayPath, line: index + 1,
+      message: `'${hit[0]}' is a placeholder: state the decision or the task, or record it as a gap in §3`,
+    });
+  });
+  return findings;
+}
+
+const REQUIREMENT_ID = /\b(?:US\d+|FR-\d+|NFR-\d+)\b/;
+
+/** The ids requirement.md defines and still holds live: a user story bullet (`**US1`) or an index
+ * row (`| FR-001 |`) whose row is not `Superseded`, read up to the History section. The first
+ * defining line of each id is its locator. */
+function requirementIds(text        )                                      {
+  const ids = new Map                ();
+  const lines = proseLines(text);
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (/^##\s+(?:\d+\.\s*)?History\b/i.test(line)) break;
+    const story = line.match(/^\s*[-*]\s+\*\*(US\d+)\b/);
+    const row = line.match(/^\s*\|\s*((?:FR|NFR)-\d+)\s*\|/);
+    const id = story?.[1] || (row && !/\bSuperseded\b/i.test(line) ? row[1] : null);
+    if (id && !ids.has(id)) ids.set(id, i + 1);
+  }
+  return [...ids].map(([id, line]) => ({ id, line }));
+}
+
+function coverageFindings(planText        , planPath        , requirementText        , requirementPath        )            {
+  const visible = proseLines(planText, { keepCode: true });
+  return requirementIds(requirementText)
+    .filter(({ id }) => !visible.some((line) => new RegExp(`\\b${id}\\b`).test(line)))
+    .map(({ id, line }) => ({
+      rule: 'coverage', severity: 'fix'         , path: requirementPath, line, id,
+      message: `${id} is not traced anywhere in ${planPath}: name it on the task that delivers it, or on the §7 row that verifies it`,
+    }));
+}
+
+/** The requirement next to a plan, found the way the path resolver finds it: `intention/`
+ * under the structured layout, beside the plan otherwise. */
+function requirementBeside(planAbs        )                {
+  const dir = path.dirname(planAbs);
+  return [path.join(dir, 'intention', 'requirement.md'), path.join(dir, 'requirement.md')].find((f) => fs.existsSync(f)) || null;
+}
+
+// ── constitution (row 134 item 4: a MUST conflict refuses the planning stage's exit) ──────────────
+
+/** Where the base tier is, beside a runtime root: the checkout's `core/shared` copy, else the
+ * install's guidance tree, a sibling of `<install>/.doflow/runtime` (which carries no core/shared),
+ * resolved the way `resolveBashHelper` finds the bash helpers. */
+function constitutionBaseCandidates(runtimeRoot         = REPO_ROOT)           {
+  return [
+    path.join(runtimeRoot, 'core', 'shared', 'guidance', 'references', 'CONSTITUTION_BASE.md'),
+    path.resolve(runtimeRoot, '..', 'guidance', 'references', 'CONSTITUTION_BASE.md'),
+  ];
+}
+function constitutionBaseFile(runtimeRoot         = REPO_ROOT)                {
+  return constitutionBaseCandidates(runtimeRoot).find((file) => fs.existsSync(file)) || null;
+}
+const CONSTITUTION_BASE = constitutionBaseFile() || constitutionBaseCandidates()[0];
+const CONSTITUTION_LOCAL = 'agent-docs/constitution.md';
+const UNBLOCK = 'revise the plan until it passes and record its row, or have a person amend the constitution with /do-constitution; there is no waiver';
+
+                                                                                       
+
+/** A heading's principle id: the text before ` — `, else its first word. */
+function principleId(cell        )         {
+  const plain = cell.replace(/[*`]/g, '').trim();
+  return (plain.split(/\s+[—–-]\s+/)[0].split(/\s+/)[0] || '').trim();
+}
+
+/** The principles a constitution file declares: each `### ` heading under `## Principles`, MUST
+ * unless its body carries `**Tier:** SHOULD`. */
+function parsePrinciples(text        , source        )              {
+  const principles              = [];
+  const lines = proseLines(text, { keepCode: true });
+  let inside = false;
+  let current                   = null;
+  lines.forEach((line, index) => {
+    if (/^##\s/.test(line)) { inside = /^##\s+Principles\b/i.test(line); current = null; return; }
+    if (!inside) return;
+    const heading = line.match(/^###\s+(.+?)\s*$/);
+    if (heading) {
+      current = { id: principleId(heading[1]), tier: 'MUST', source, line: index + 1 };
+      if (current.id) principles.push(current);
+      return;
+    }
+    const tier = line.match(/^\s*\*\*Tier:\*\*\s*(MUST|SHOULD)\b/i);
+    if (tier && current) current.tier = tier[1].toUpperCase()                     ;
+  });
+  return principles;
+}
+
+/** A principle id declared twice in one file, named with both lines; null when every id is unique. */
+function duplicateId(principles             , file        )                {
+  const seen = new Map                ();
+  for (const p of principles) {
+    if (seen.has(p.id)) return `${file} declares ${p.id} twice (lines ${seen.get(p.id)} and ${p.line})`;
+    seen.set(p.id, p.line);
+  }
+  return null;
+}
+
+/** Both tiers, tier-2 taking precedence: a tier-2 principle with a base id replaces it in place,
+ * a new id is appended. `error` is set when either file cannot be read, has no `## Principles`
+ * section with a principle in it, or declares an id twice; the gate then refuses rather than
+ * check the plan against fewer principles than the constitution holds. A base MUST the overlay
+ * makes SHOULD is allowed (the designed tier-2 path) and listed in `downgrades`, never silent. */
+function loadConstitution({ checkoutRoot, runtimeRoot = REPO_ROOT }                                                ) {
+  const none = { principles: []               , downgrades: []                                                  };
+  const baseFile = constitutionBaseFile(runtimeRoot);
+  if (!baseFile) return { ...none, error: `the base constitution cannot be found (searched ${constitutionBaseCandidates(runtimeRoot).join(', ')})` };
+  let base        ;
+  try { base = fs.readFileSync(baseFile, 'utf8'); } catch (error     ) {
+    return { ...none, error: `the base constitution ${baseFile} cannot be read (${error.code || error.message})` };
+  }
+  const principles = parsePrinciples(base, 'CONSTITUTION_BASE.md');
+  if (!principles.length) return { ...none, error: `the base constitution ${baseFile} declares no principle` };
+  const baseDuplicate = duplicateId(principles, baseFile);
+  if (baseDuplicate) return { ...none, error: baseDuplicate };
+  const localFile = path.join(checkoutRoot, CONSTITUTION_LOCAL);
+  let local                = null;
+  try { local = fs.readFileSync(localFile, 'utf8'); } catch (error     ) {
+    if (error.code !== 'ENOENT') return { ...none, error: `the repo constitution ${CONSTITUTION_LOCAL} cannot be read (${error.code || error.message})` };
+  }
+  if (local === null) return { principles, downgrades: none.downgrades, error: null                  };
+  const overlay = parsePrinciples(local, CONSTITUTION_LOCAL);
+  if (!overlay.length) {
+    return { ...none, error: `the repo constitution ${CONSTITUTION_LOCAL} has no \`## Principles\` section with a \`### <ID> — <name>\` principle, so its principles cannot be read` };
+  }
+  const overlayDuplicate = duplicateId(overlay, CONSTITUTION_LOCAL);
+  if (overlayDuplicate) return { ...none, error: overlayDuplicate };
+  const version = (proseLines(local).join('\n').match(/\*\*Version:\*\*\s*([^\s·]+)/) || [])[1] || null;
+  const downgrades                                                = [];
+  for (const principle of overlay) {
+    const at = principles.findIndex((p) => p.id === principle.id);
+    if (at === -1) { principles.push(principle); continue; }
+    if (principles[at].tier === 'MUST' && principle.tier === 'SHOULD') downgrades.push({ ...principle, version });
+    principles[at] = principle;
+  }
+  return { principles, downgrades, error: null                  };
+}
+
+/** The §2 "Constitution Check" record in the plan's visible Markdown: one table row per
+ * principle, read by its `Principle` and `Result` columns. A header row with no `|---|` separator
+ * under it is no table; `unparseable` is then that header's line. */
+function constitutionRecord(planText        ) {
+  const lines = proseLines(planText, { keepCode: true });
+  const start = lines.findIndex((line) => /^##\s+(?:\d+\.\s*)?Constitution Check\b/i.test(line));
+  const rows                                                      = [];
+  if (start === -1) return { heading: null, rows, unparseable: null                  };
+  const cellsOf = (line        ) => line.trim().replace(/^\||\|$/g, '').split('|').map((cell) => cell.trim());
+  let columns                                               = null;
+  for (let i = start + 1; i < lines.length && !/^##\s/.test(lines[i]); i += 1) {
+    if (!/^\s*\|/.test(lines[i])) { if (columns) break; continue; }
+    const cells = cellsOf(lines[i]);
+    if (!columns) {
+      const names = cells.map((cell) => cell.replace(/[*`]/g, '').toLowerCase());
+      if (!(names.includes('principle') && names.includes('result'))) continue;
+      if (!(lines[i + 1] && cellsOf(lines[i + 1]).every((cell) => /^:?-+:?$/.test(cell)))) return { heading: start + 1, rows, unparseable: i + 1 };
+      columns = { principle: names.indexOf('principle'), result: names.indexOf('result') };
+      i += 1;
+      continue;
+    }
+    rows.push({ id: principleId(cells[columns.principle] || ''), result: (cells[columns.result] || '').replace(/[*`]/g, '').trim().toUpperCase(), line: i + 1 });
+  }
+  return { heading: start + 1, rows, unparseable: null                  };
+}
+
+/** One finding per principle that is not recorded as passing: a MUST marked FAIL or without a
+ * PASS/FAIL row refuses exit; a SHOULD marked FAIL is advisory. The tier is the constitution's,
+ * whatever the row says, so a plan cannot downgrade a MUST. */
+function constitutionFindings({ planText, planPath, principles }                                                                 )            {
+  const { heading, rows, unparseable } = constitutionRecord(planText);
+  if (unparseable) {
+    return [{ rule: 'constitution-unparseable', severity: 'refuses-exit', path: planPath, line: unparseable,
+      message: `no parseable Constitution Check: the table header has no |---| separator row under it, so no principle is recorded; ${UNBLOCK}` }];
+  }
+  const findings            = [];
+  for (const principle of principles) {
+    const recorded = rows.filter((r) => r.id === principle.id && (r.result === 'PASS' || r.result === 'FAIL'));
+    const failed = recorded.find((r) => r.result === 'FAIL');
+    const tier = `${principle.id} (${principle.tier})`;
+    if (principle.tier === 'MUST' && failed) {
+      findings.push({ rule: 'constitution-must-fail', severity: 'refuses-exit', path: planPath, line: failed.line, id: principle.id,
+        message: `${tier} is marked FAIL in the Constitution Check: ${UNBLOCK}` });
+    } else if (principle.tier === 'MUST' && !recorded.length) {
+      findings.push({ rule: 'constitution-must-missing', severity: 'refuses-exit', path: planPath, line: heading || 1, id: principle.id,
+        message: `${tier} has no PASS/FAIL row in the Constitution Check (${principle.source}): add \`| ${principle.id} | MUST | PASS | <how> |\` once the plan complies, or ${UNBLOCK}` });
+    } else if (failed) {
+      findings.push({ rule: 'constitution-should-fail', severity: 'advisory', path: planPath, line: failed.line, id: principle.id,
+        message: `${tier} is marked FAIL in the Constitution Check: advisory, recorded and not blocking` });
+    }
+  }
+  return findings;
+}
+
+/** The checkout a plan belongs to: the nearest directory above it holding `.git`, else `fallback`. */
+function checkoutOf(file        , fallback        )         {
+  for (let dir = path.dirname(file); ; dir = path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    if (path.dirname(dir) === dir) return fallback;
+  }
+}
+
+/** The constitution findings, or one refusal when the constitution itself cannot be read. */
+function constitutionCheck({ planText, planPath, checkoutRoot }                                                              )            {
+  const { principles, downgrades, error } = loadConstitution({ checkoutRoot });
+  if (error) return [{ rule: 'constitution-unreadable', severity: 'refuses-exit', path: planPath, line: 1, message: `${error}: nothing can be checked, so the plan is refused` }];
+  const notes            = downgrades.map((d) => ({ rule: 'constitution-downgrade', severity: 'advisory'         , path: d.source, line: d.line, id: d.id,
+    message: `${d.id} is MUST in the base constitution and SHOULD in ${d.source}${d.version ? ` ${d.version}` : ''}: the overlay downgrades it, recorded and not blocking` }));
+  return [...notes, ...constitutionFindings({ planText, planPath, principles })];
+}
+
+/** Every content finding for one plan file. Paths are shown relative to `cwd`. */
+function planFindings({ planAbs, text, displayPath, cwd }                                                                     )            {
+  const findings = placeholderFindings(text, displayPath);
+  const requirement = requirementBeside(planAbs);
+  if (requirement) {
+    let requirementText = null;
+    try { requirementText = fs.readFileSync(requirement, 'utf8'); } catch { /* unreadable: no coverage claim either way */ }
+    if (requirementText !== null) findings.push(...coverageFindings(text, displayPath, requirementText, path.relative(cwd, requirement)));
+  }
+  findings.push(...constitutionCheck({ planText: text, planPath: displayPath, checkoutRoot: checkoutOf(planAbs, cwd) }));
+  return findings;
+}
+
+/** The planning stage's exit (row 134): the feature's plan.md, found under the first root that has
+ * it, checked against both constitution tiers of that checkout. `refusals` refuse the exit;
+ * `advisories` are printed and recorded nowhere else. A run with no feature, or a feature with no
+ * plan, is refused: the planning stage exists to produce that plan. */
+function planStageExit({ roots, slug }                                          ) {
+  // plan.md, else planning/plan.md under the structured layout (the roadmap facts read the same two).
+  const feature = slug ? path.join('agent-docs', 'doflow', slug) : null;
+  const found = feature ? roots.flatMap((r) => ['plan.md', path.join('planning', 'plan.md')].map((rel) => ({ r, rel: path.join(feature, rel) })))
+    .find(({ r, rel }) => fs.existsSync(path.join(r, rel))) : undefined;
+  const relative = found ? found.rel : feature ? path.join(feature, 'plan.md') : null;
+  const root = found?.r;
+  if (!relative || !root) {
+    const where = relative ? `${relative} (or planning/plan.md) under ${roots.join(', ')}` : 'a plan: the run names no feature';
+    return { refusals: [{ rule: 'plan-missing', severity: 'refuses-exit', path: relative || 'plan.md', line: 1, message: `no plan to check (looked for ${where}); write plan.md before completing the planning stage` }]             , advisories: []              };
+  }
+  let planText        ;
+  try { planText = fs.readFileSync(path.join(root, relative), 'utf8'); } catch (error     ) {
+    return { refusals: [{ rule: 'plan-missing', severity: 'refuses-exit', path: relative, line: 1, message: `${relative} cannot be read (${error.code || error.message})` }]             , advisories: []              };
+  }
+  const findings = constitutionCheck({ planText, planPath: relative.split(path.sep).join('/'), checkoutRoot: root });
+  return { refusals: findings.filter((f) => f.severity === 'refuses-exit'), advisories: findings.filter((f) => f.severity === 'advisory') };
+}
+
+module.exports = {
+  placeholderFindings, coverageFindings, requirementIds, planFindings, proseLines,
+  parsePrinciples, loadConstitution, constitutionFindings, planStageExit, CONSTITUTION_BASE, constitutionBaseFile,
+};

package/src/runtime/policy-init.js

@@ -0,0 +1,118 @@
+'use strict';
+
+/**
+ * `doflow roadmap --action init-policy --commit`: a person-run command, kept out of src/runtime/roadmap/**
+ * so the autopilot loop's git reach (G53, G54) does not widen. It adds one commit to the local develop that
+ * touches only core/registry/gates.json, built with git plumbing in a temporary index so the index, the
+ * working tree and the checked-out branch stay as they are. The bytes are the reviewed working copy when
+ * there is one, else the packaged policy; invalid bytes are refused. A develop checked out in any worktree
+ * is not moved (that worktree's index would go stale): the commands to run there are printed instead. The
+ * ref moves with compare-and-swap. Nothing is staged, pushed, tagged or published, and the loop still reads
+ * the policy only from develop's committed head.
+ */
+
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync: defaultExecFileSync } = require('node:child_process');
+const { loadPolicy } = require('./roadmap/gates.js');
+const { resolveMainRoot } = require('./roadmap/loop.js');
+
+const REL = 'core/registry/gates.json';
+const MESSAGE = 'chore(roadmap): add the autopilot gate policy';
+const shellQuote = (text        )         => ["'", text.split("'").join("'\\''"), "'"].join('');
+
+/** Every git command addresses the named checkout; inherited routing variables are dropped. */
+function optionsFor(root        , env     )      {
+  const environment = { ...env };
+  for (const key of Object.keys(environment)) if (/^GIT_(?:DIR|WORK_TREE|COMMON_DIR|INDEX_FILE|OBJECT_DIRECTORY|ALTERNATE_OBJECT_DIRECTORIES|CONFIG_COUNT|CONFIG_KEY_\d+|CONFIG_VALUE_\d+)$/.test(key)) delete environment[key];
+  return { cwd: root, encoding: 'utf8', env: environment, stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024 };
+}
+
+/** The path of the worktree that has `ref` checked out, if any. */
+function checkedOutAt(execFileSync     , root        , opts     , ref        )                     {
+  const out = String(execFileSync('git', ['-C', root, 'worktree', 'list', '--porcelain', '-z'], opts));
+  for (const block of out.split('\0\0').filter(Boolean)) {
+    const fields = block.split('\0');
+    const listed = fields.find((s) => s.startsWith('worktree '))?.slice(9);
+    if (listed && fields.find((s) => s.startsWith('branch '))?.slice(7) === ref) return path.resolve(listed);
+  }
+  return undefined;
+}
+
+function commitPolicyCommand(options     )         {
+  const { json = false, fsImpl = fs } = options;
+  const root = options.root || resolveMainRoot(options.cwd || process.cwd());
+  const execFileSync = options.execFileSync || defaultExecFileSync;
+  const opts = optionsFor(root, options.env || process.env);
+  const target = path.join(root, REL);
+  const packaged = path.join(options.repoRoot, REL);
+  const reason = (error     )         => String(error?.stderr || error?.message || error).trim();
+  const fail = (message        )         => {
+    if (json) console.log(JSON.stringify({ schema: 1, action: 'init-policy', error: 'not-committed', detail: message }));
+    else console.error(`doflow roadmap: ${message}`);
+    process.exitCode = 1;
+    return 1;
+  };
+
+  let old        ;
+  try { old = String(execFileSync('git', ['-C', root, 'rev-parse', '--verify', '-q', 'refs/heads/develop'], opts)).trim(); }
+  catch { return fail('no local develop branch (or not a git repository); create develop first, the loop reads the policy only from its head'); }
+  let present = true;
+  try { execFileSync('git', ['-C', root, 'cat-file', '-e', `${old}:${REL}`], opts); } catch { present = false; }
+  if (present) return fail(`develop already has ${REL}; nothing changed`);
+
+  let workingCopy      = null;
+  try { workingCopy = fsImpl.readFileSync(target); }
+  catch (error     ) { if (error.code !== 'ENOENT') return fail(`cannot read ${target}: ${error.message}`); }
+  const bytes = workingCopy ?? fsImpl.readFileSync(packaged);
+  const verdict = loadPolicy(bytes);
+  if (!verdict.ok) return fail(`${workingCopy ? target : 'the packaged policy'} is not a valid policy (${verdict.reason}); nothing changed`);
+
+  const elsewhere = checkedOutAt(execFileSync, root, opts, 'refs/heads/develop');
+  if (elsewhere) {
+    const destination = path.join(elsewhere, REL);
+    const source = workingCopy ? target : packaged;
+    const commands = [`mkdir -p ${shellQuote(path.dirname(destination))}`];
+    if (path.resolve(source) !== path.resolve(destination)) commands.push(`cp ${shellQuote(source)} ${shellQuote(destination)}`);
+    commands.push(`git -C ${shellQuote(elsewhere)} add -- ${REL}`, `git -C ${shellQuote(elsewhere)} commit -m ${shellQuote(MESSAGE)} -- ${REL}`);
+    return fail(`develop is checked out at ${elsewhere}; moving its branch would leave that worktree's index stale, so nothing was changed. Run instead:\n  ${commands.join('\n  ')}`);
+  }
+
+  // git itself creates and locks this temporary index (read-tree, update-index, write-tree); this module writes no file.
+  const scratch = path.join(os.tmpdir(), `doflow-policy-${crypto.randomBytes(8).toString('hex')}.index`);
+  const indexed = { ...opts, env: { ...opts.env, GIT_INDEX_FILE: scratch } };
+  let commit        ;
+  try {
+    const blob = String(execFileSync('git', ['-C', root, 'hash-object', '-w', '--stdin'], { ...opts, stdio: ['pipe', 'pipe', 'pipe'], input: bytes })).trim();
+    execFileSync('git', ['-C', root, 'read-tree', old], indexed);
+    execFileSync('git', ['-C', root, 'update-index', '--add', '--cacheinfo', `100644,${blob},${REL}`], indexed);
+    const tree = String(execFileSync('git', ['-C', root, 'write-tree'], indexed)).trim();
+    commit = String(execFileSync('git', ['-C', root, 'commit-tree', tree, '-p', old, '-m', MESSAGE, '--no-gpg-sign'], opts)).trim();
+  } catch (error     ) {
+    return fail(`cannot build the commit: ${reason(error)}; nothing changed`);
+  } finally {
+    for (const leftover of [scratch, `${scratch}.lock`]) fsImpl.rmSync(leftover, { force: true });
+  }
+  try { execFileSync('git', ['-C', root, 'update-ref', 'refs/heads/develop', commit, old], opts); }
+  catch (error     ) { return fail(`develop moved or could not be updated (${reason(error)}); nothing changed, run the command again`); }
+
+  // The working copy is now tracked on develop: an identical untracked copy would collide with a later merge of develop.
+  let copy = 'none';
+  let copyNote = '';
+  if (workingCopy) {
+    let tracked = false;
+    try { tracked = String(execFileSync('git', ['-C', root, 'ls-files', '--', REL], opts)).trim() !== ''; } catch { /* untracked */ }
+    let now      = null;
+    try { now = fsImpl.readFileSync(target); } catch { /* gone already */ }
+    if (tracked) { copy = 'kept'; copyNote = `kept ${target}: it is tracked in the checked-out branch`; }
+    else if (now && Buffer.from(now).equals(Buffer.from(bytes))) { fsImpl.unlinkSync(target); copy = 'removed'; copyNote = `removed ${target} (identical to the committed bytes, now tracked on develop)`; }
+    else if (now) { copy = 'kept'; copyNote = `kept ${target}: it differs from the committed bytes`; }
+  }
+  if (json) console.log(JSON.stringify({ schema: 1, action: 'init-policy', committed: true, commit, previous: old, file: REL, root, workingCopy: copy }));
+  else console.log(`develop ${old} -> ${commit} (${REL} only)${copyNote ? `\n${copyNote}` : ''}\nNothing was pushed; that is yours.`);
+  return 0;
+}
+
+module.exports = { commitPolicyCommand };

package/src/runtime/profiles/doctor.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveRolloutProfile, isCapabilityActive } = require('./resolve.js');
+const { checkRollbackState, tripRollback, resetRollback } = require('./rollback.js');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+
+                               
+                                                    
+                                                  
+                     
+                         
+                           
+                             
+    
+ 
+
+function buildProfilesDoctor(options    
+                    
+                       
+            
+               
+ )                      {
+  const fsImpl = options?.fsImpl || fs;
+  const repoRoot = options?.repoRoot || REPO_ROOT;
+
+  const profile = resolveRolloutProfile(options);
+  const rollback = checkRollbackState(options);
+
+  let harnessCount = 0;
+  let verifiedFacts = true;
+  let nativeTelemetry = true;
+
+  try {
+    const harnessesPath = path.join(repoRoot, 'core', 'registry', 'harnesses.json');
+    if (fsImpl.existsSync(harnessesPath)) {
+      const data = JSON.parse(fsImpl.readFileSync(harnessesPath, 'utf8'));
+      if (Array.isArray(data.harnesses)) {
+        harnessCount = data.harnesses.length;
+        for (const h of data.harnesses) {
+          if (!h.contextProfile || typeof h.contextProfile.capacityTokens?.value !== 'number') {
+            verifiedFacts = false;
+          }
+          if (!h.nativeTelemetry || !Array.isArray(h.nativeTelemetry.signals)) {
+            nativeTelemetry = false;
+          }
+        }
+      }
+    }
+  } catch {
+    verifiedFacts = false;
+    nativeTelemetry = false;
+  }
+
+  return {
+    profile,
+    rollback,
+    registryVerified: {
+      harnessCount,
+      verifiedFacts,
+      nativeTelemetry,
+    },
+  };
+}
+
+function printProfilesDoctor(report                     )       {
+  console.log('\n[Rollout Profile & Governance]');
+  const p = report.profile;
+  const r = report.rollback;
+
+  console.log(`  profile           ${p.name.padEnd(12)} (${p.origin.source}: ${p.origin.detail || 'default'})`);
+  if (r.active) {
+    console.log(`  rollback          ACTIVE (${r.reason}, origin: ${r.origin}) -> forced baseline`);
+  } else {
+    console.log('  rollback          inactive (normal operation)');
+  }
+
+  const caps = p.capabilities;
+  console.log(`  capabilities      retrieval: ${caps.retrieval}, advisor: ${caps.advisor}, graph: ${caps.graph}, verification: ${caps.verification}`);
+  console.log(`  canary tag        ${caps.telemetryCanaryTag ? 'yes' : 'no'} (sample rate: ${(p.canarySampleRate * 100).toFixed(0)}%)`);
+
+  const reg = report.registryVerified;
+  const regStatus = reg.verifiedFacts && reg.nativeTelemetry ? 'PASS' : 'UNVERIFIED';
+  console.log(`  harness registry  ${reg.harnessCount} harnesses checked (${regStatus})`);
+}
+
+module.exports = {
+  buildProfilesDoctor,
+  printProfilesDoctor,
+  resolveRolloutProfile,
+  checkRollbackState,
+  isCapabilityActive,
+  tripRollback,
+  resetRollback,
+};