@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

package/src/runtime/rules-report.js

@@ -0,0 +1,336 @@
+'use strict';
+
+/**
+ * `doflow rules`: the read-only view of the values the runtime owns for a project, each with its source, so
+ * guidance and policy text can point here instead of copying numbers. Four sections:
+ *   review    the protocol `review --action start` resolves per task class, attended and unattended (the real
+ *             `resolveProtocol`; nothing is copied from the registries)
+ *   gates     per class and gate `autopilot` and `minSeats` from the packaged gates.json, and the loop limits
+ *   tiers     owner -> tier, and tier -> model per worker from `workers.models`
+ *   settings  the effective value and layer of the keys above
+ * A value that cannot be resolved prints as `unresolved:<reason>`. The verb writes nothing and spawns only `git`
+ * (to say whether develop holds a committed gate policy).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { REPO_ROOT } = require('../helper/repo-root.js');
+const { finishRuntime, usageError, captureCaught } = require('./cli-result.js');
+const { resolveProtocol } = require('./review/resolve-protocol.js');
+const { invalidProjectCandidate, invalidPresetCandidate } = require('./review/findings.js');
+
+const REGISTRY = (file        ) => path.join(REPO_ROOT, 'core', 'registry', file);
+const PROTOCOLS_FILE = 'core/registry/protocols.json';
+const GATES_FILE = 'core/registry/gates.json';
+const MODELS_FILE = 'core/registry/models.json';
+const SETTINGS_FILE = 'core/registry/settings.json';
+const VERIFICATION_FILE = 'core/registry/verification.json';
+// Keys of the settings section, beyond the ones `resolveProtocol` reads.
+const REPORT_SETTINGS = ['review.preset', 'review.rounds', 'review.sameFamily', 'autopilot.enabled'];
+const GIT_LOCATION_KEYS = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY', 'GIT_COMMON_DIR', 'GIT_ALTERNATE_OBJECT_DIRECTORIES'];
+
+const unresolved = (reason         )         => `unresolved:${String(reason instanceof Error ? reason.message : reason).split('\n')[0].slice(0, 160)}`;
+const isUnresolved = (value         )          => typeof value === 'string' && value.startsWith('unresolved:');
+
+/** Where an origin or layer name comes from: a registry file for a registry value, else the settings layer. */
+function sourceOf(origin        )         {
+  switch (origin) {
+    case 'registry': return PROTOCOLS_FILE;
+    case 'floor': return GATES_FILE;
+    case 'risk': return VERIFICATION_FILE;
+    case 'default': return SETTINGS_FILE;
+    case 'env': return 'environment';
+    default: return `settings:${origin}`;
+  }
+}
+
+const readJson = (file        )      => JSON.parse(fs.readFileSync(REGISTRY(file), 'utf8'));
+
+/** The effective `{ value, layer, source }` of a setting, or `{ value: 'unresolved:…' }` when the resolver cannot say. */
+function settingEntry(settings     , key        , view         )      {
+  try {
+    const resolution = view ? settings.get(key, view) : settings.get(key);
+    // As the protocol loader judges them: a preset key refuses any invalid layer, another review.* key an invalid project or local one.
+    const invalid = key.endsWith('.preset') ? invalidPresetCandidate(resolution) : key.startsWith('review.') ? invalidProjectCandidate(resolution) : undefined;
+    if (resolution.state === 'invalid' || invalid) {
+      const candidate = invalid ?? resolution.candidates.find((c     ) => c.status === 'invalid');
+      return { value: unresolved(`invalid ${key}${candidate ? ` in ${candidate.source}: ${candidate.reason}` : ''}`), layer: null, source: null };
+    }
+    const layer = resolution.origin?.layer ?? 'default';
+    return { value: resolution.value ?? null, layer, source: sourceOf(layer) };
+  } catch (error) {
+    return { value: unresolved(error), layer: null, source: null };
+  }
+}
+
+/** The keys `resolveProtocol` reads from the settings, from the registry's own `consumers` lists. */
+function protocolSettingKeys()           {
+  return Object.entries     (readJson('settings.json').keys)
+    .filter(([key, spec]) => key.startsWith('review.') && (spec.consumers ?? []).some((c        ) => c.endsWith('review/resolve-protocol.ts')))
+    .map(([key]) => key);
+}
+
+function gitShow(project        , args          )                                            {
+  const env                                     = { ...process.env };
+  for (const key of GIT_LOCATION_KEYS) delete env[key];
+  const res = spawnSync('git', ['-C', project, ...args], { env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000 });
+  return { status: res.status, stdout: typeof res.stdout === 'string' ? res.stdout : '' };
+}
+
+/** Whether the project's local develop holds a committed gate policy, and whether it is the packaged one. The working tree is never read. */
+function projectPolicyState(project        , packagedText        )         {
+  const develop = gitShow(project, ['rev-parse', '--verify', '-q', 'refs/heads/develop']);
+  if (develop.status === null) return unresolved('git cannot run');
+  if (develop.status !== 0) return unresolved('no local develop branch');
+  const blob = gitShow(project, ['show', `refs/heads/develop:${GATES_FILE}`]);
+  if (blob.status !== 0) return 'absent';
+  return blob.stdout === packagedText ? 'committed on develop, same as packaged' : 'committed on develop, differs from packaged';
+}
+
+                                                                             
+
+/** The gate policy as `review --action start` reads it (shipped gates.json narrowed by the project's override), and what the override did. */
+function loadPolicyFor(project               )               {
+  try {
+    const loaded = require('./review/start.js').loadGatePolicy(project);
+    if (!loaded.ok) return { policy: null, override: `invalid:${loaded.reason}`, reason: loaded.reason };
+    return { policy: loaded.policy, override: loaded.override, reason: null };
+  } catch (error) {
+    const reason = unresolved(error).slice('unresolved:'.length);
+    return { policy: null, override: `invalid:${reason}`, reason };
+  }
+}
+
+function gatesSection(taskClasses          , project               , loaded              )      {
+  let packagedText = '';
+  try { packagedText = fs.readFileSync(REGISTRY('gates.json'), 'utf8'); } catch { /* the policy load has failed the same way */ }
+  const head = {
+    source: GATES_FILE, override: loaded.override,
+    projectPolicy: project ? projectPolicyState(project, packagedText) : unresolved('no project'),
+  };
+  const policy = loaded.policy;
+  if (!policy) return { policy: null, section: { ...head, classes: unresolved(loaded.reason), loop: unresolved(loaded.reason) } };
+  const classes      = {};
+  for (const name of taskClasses) {
+    const gates      = {};
+    for (const [gate, rule] of Object.entries     (policy.classes?.[name] ?? {})) {
+      gates[gate] = {
+        autopilot: typeof rule?.autopilot === 'string' ? rule.autopilot : unresolved('autopilot not declared'),
+        minSeats: Number.isInteger(rule?.minSeats) && rule.minSeats > 0 ? rule.minSeats : 0,
+      };
+    }
+    classes[name] = gates;
+  }
+  return {
+    policy,
+    section: {
+      ...head,
+      classes,
+      loop: { maxSteps: policy.loop?.maxSteps ?? unresolved('loop.maxSteps not declared'), wip: policy.loop?.wip ?? unresolved('loop.wip not declared') },
+    },
+  };
+}
+
+function protocolRow(registry     , protocol     )      {
+  const preset = registry.presets[protocol.id];
+  const origin = protocol.origins.seats === 'floor' ? 'floor' : protocol.origins.id;
+  return {
+    preset: protocol.id,
+    seats: { count: protocol.seats.length, roles: protocol.seats.map((seat     ) => seat.agent) },
+    rounds: { min: preset.rounds.min, max: registry.hardRoundCap, default: preset.rounds.default, effective: protocol.rounds },
+    crossAnswer: protocol.crossAnswer,
+    synthesizer: protocol.synthesizer,
+    origin,
+    source: sourceOf(origin),
+    ...(protocol.disagreements.length ? { disagreements: protocol.disagreements } : {}),
+  };
+}
+
+/** The review section: `resolveProtocol` per class, attended (floor 0) and unattended (the class's gate-b floor). */
+function reviewSection(taskClasses          , settings     , gatePolicy     , gatesReason               )      {
+  const classes      = {};
+  let inputs     ;
+  try {
+    const protocols = require('./review/protocols.js').loadProtocols();
+    if (!protocols.ok) throw new Error(protocols.errors.join('; '));
+    const { loadVerificationRegistry, reviewDepthPolicy } = require('./verification/registry.js');
+    const verification = loadVerificationRegistry({ repoRoot: REPO_ROOT });
+    const settingsView      = {};
+    for (const key of protocolSettingKeys()) {
+      const entry = settingEntry(settings, key);
+      if (isUnresolved(entry.value)) throw new Error(String(entry.value).slice('unresolved:'.length));
+      settingsView[key] = { value: entry.value, layer: entry.layer };
+    }
+    inputs = { registry: protocols.registry, settingsView, risk: verification.policy.defaultRiskLevel, riskPolicy: reviewDepthPolicy(verification) };
+  } catch (error) {
+    for (const name of taskClasses) classes[name] = { attended: unresolved(error), unattended: unresolved(error) };
+    return { classes };
+  }
+  for (const name of taskClasses) {
+    const row = (unattended         )      => {
+      if (unattended && gatesReason) return unresolved(gatesReason);
+      try {
+        const resolved = resolveProtocol({
+          kind: 'review', taskClass: name, risk: inputs.risk, paths: null, runPreset: null, advicePick: null,
+          settingsView: inputs.settingsView, gatePolicy, unattended, registry: inputs.registry, riskPolicy: inputs.riskPolicy,
+        });
+        return resolved.ok ? protocolRow(inputs.registry, resolved.protocol) : unresolved(`${resolved.reason}:${resolved.field}`);
+      } catch (error) {
+        return unresolved(error);
+      }
+    };
+    classes[name] = { attended: row(false), unattended: row(true) };
+  }
+  return { classes };
+}
+
+function tiersSection(env                                    )      {
+  let tiers     ;
+  try {
+    tiers = readJson('models.json').dispatchTiers;
+    if (!tiers) throw new Error(`${MODELS_FILE} has no dispatchTiers`);
+  } catch (error) {
+    return unresolved(error);
+  }
+  let models     ;
+  try {
+    const { readBindings } = require('./worker/models.js');
+    const bindings = readBindings({ env, projectRoot: null });
+    const { knownWorkerIds } = require('../registry/worker-ids.js');
+    const workers           = knownWorkerIds({ registry: { harnesses: readJson('harnesses.json').harnesses } }).ids;
+    models = bindings.state === 'invalid'
+      ? unresolved(`workers.models ${bindings.reason}`)
+      : Object.fromEntries(workers.map((worker) => [worker, Object.fromEntries(tiers.tiers.map((tier        ) => [tier, bindings.map?.[worker]?.[tier] ?? 'unset']))]));
+  } catch (error) {
+    models = unresolved(error);
+  }
+  return {
+    source: MODELS_FILE, default: tiers.default, tiers: tiers.tiers, byOwner: tiers.byOwner,
+    modelsSource: 'settings:user workers.models (global-only)', models,
+  };
+}
+
+/** The report for `project` (null with `global`: the user layer only). */
+function buildRulesReport({ taskClass = null, global = false, project = null, env = process.env }                                                                                                                     = {})      {
+  let taskClasses          ;
+  try {
+    taskClasses = Object.keys(readJson('gates.json').classes);
+  } catch (error) {
+    return { schema: 1, review: unresolved(error), gates: unresolved(error), tiers: tiersSection(env), settings: {} };
+  }
+  if (taskClass) taskClasses = taskClasses.filter((name) => name === taskClass);
+
+  let settings      = null;
+  let settingsReason                = null;
+  try {
+    settings = require('./settings/resolve.js').loadSettings({ projectRoot: project, global, env: { ...env } });
+  } catch (error) {
+    settingsReason = unresolved(error);
+  }
+
+  let globalSettings      = settings;
+  if (settings && !global) {
+    try { globalSettings = require('./settings/resolve.js').loadSettings({ global: true, env: { ...env } }); } catch (error) { globalSettings = null; }
+  }
+  const loadedPolicy = loadPolicyFor(global ? null : project);
+  const gates = gatesSection(taskClasses, global ? null : project, loadedPolicy);
+  const report      = { schema: 1 };
+  report.review = settings
+    ? reviewSection(taskClasses, settings, gates.policy, loadedPolicy.reason)
+    : { classes: Object.fromEntries(taskClasses.map((name) => [name, { attended: settingsReason, unattended: settingsReason }])) };
+  report.review.override = loadedPolicy.override;
+  report.gates = gates.section;
+  report.tiers = tiersSection(env);
+  report.settings = {};
+  for (const key of REPORT_SETTINGS) {
+    // The autopilot switch is global-only: read it from the global view whatever the project says.
+    const view = key === 'autopilot.enabled' ? globalSettings : settings;
+    report.settings[key] = view
+      ? settingEntry(view, key, key === 'autopilot.enabled' ? 'global' : undefined)
+      : { value: settingsReason ?? unresolved('settings unreadable'), layer: null, source: null };
+  }
+  return report;
+}
+
+function seatsText(seats     )         {
+  const counts = new Map                ();
+  for (const role of seats.roles) counts.set(role, (counts.get(role) ?? 0) + 1);
+  return `${seats.count} seat${seats.count === 1 ? '' : 's'} (${[...counts].map(([role, n]) => (n > 1 ? `${role} x${n}` : role)).join(', ')})`;
+}
+
+function protocolText(row     )         {
+  if (typeof row === 'string') return row;
+  return `${row.preset}: ${seatsText(row.seats)}, rounds ${row.rounds.effective} (min ${row.rounds.min}, max ${row.rounds.max}), cross-answer ${row.crossAnswer ? 'on' : 'off'}, synthesizer ${row.synthesizer}, origin=${row.origin}${row.disagreements ? ` [ignored: ${row.disagreements.map((d     ) => `${d.field}=${d.value} ${d.reason}`).join('; ')}]` : ''}`;
+}
+
+/** The compact text form (about 45 lines for all nine classes). */
+function rulesLines(report     )           {
+  const lines           = [];
+  if (typeof report.review === 'string') lines.push(`review: ${report.review}`);
+  else lines.push(`review: protocol per task class, as \`review --action start\` resolves it (origin: registry=${PROTOCOLS_FILE}, floor=${GATES_FILE} gate-b minSeats, user|project|local=settings layer; gate override: ${report.review.override ?? 'none'})`);
+  for (const [name, rows] of Object.entries     (report.review.classes ?? {})) {
+    lines.push(`  ${name} attended:   ${protocolText(rows.attended)}`);
+    lines.push(`  ${name} unattended: ${protocolText(rows.unattended)}`);
+  }
+  lines.push('');
+  if (typeof report.gates === 'string') lines.push(`gates: ${report.gates}`);
+  else {
+    lines.push(`gates: ${report.gates.source}; override: ${report.gates.override}; develop policy: ${report.gates.projectPolicy}`);
+    const none           = [];
+    if (typeof report.gates.classes === 'string') lines.push(`  ${report.gates.classes}`);
+    else for (const [name, gates] of Object.entries     (report.gates.classes)) {
+      const entries = Object.entries     (gates);
+      if (entries.length === 0) none.push(name);
+      for (const [gate, rule] of entries) lines.push(`  ${name} ${gate}: autopilot=${rule.autopilot} minSeats=${rule.minSeats}`);
+    }
+    if (none.length) lines.push(`  no gates declared: ${none.join(', ')}`);
+    if (typeof report.gates.loop !== 'string') lines.push(`  loop: maxSteps=${report.gates.loop.maxSteps} wip=${report.gates.loop.wip}`);
+  }
+  lines.push('');
+  if (typeof report.tiers === 'string') lines.push(`tiers: ${report.tiers}`);
+  else {
+    lines.push(`tiers: owner -> tier from ${report.tiers.source} (default ${report.tiers.default}; tiers ${report.tiers.tiers.join(', ')})`);
+    lines.push(`  ${Object.entries(report.tiers.byOwner).map(([owner, tier]) => `${owner}=${tier}`).join(' ')}`);
+    if (typeof report.tiers.models === 'string') lines.push(`  models: ${report.tiers.models}`);
+    else {
+      const set = Object.entries     (report.tiers.models).filter(([, byTier]) => Object.values(byTier).some((model) => model !== 'unset'));
+      lines.push(`  model per worker and tier (${report.tiers.modelsSource}): ${set.length === 0 ? `unset for all ${Object.keys(report.tiers.models).length} workers` : ''}`.trimEnd());
+      for (const [worker, byTier] of set) lines.push(`    ${worker}: ${Object.entries(byTier).map(([tier, model]) => `${tier}=${model}`).join(' ')}`);
+    }
+  }
+  lines.push('');
+  lines.push('settings: effective value and layer');
+  for (const [key, entry] of Object.entries     (report.settings)) {
+    lines.push(`  ${key} = ${isUnresolved(entry.value) ? entry.value : JSON.stringify(entry.value)}${entry.layer ? ` (${entry.layer}, ${entry.source})` : ''}`);
+  }
+  return lines;
+}
+
+function handleRulesCommand({ taskClass, json = false, global = false, positional = [], env = process.env, cwd = process.cwd(), out = (line        ) => console.log(line) }      = {})         {
+  const usage = (message        )         => usageError('rules', message, false);
+  try {
+    if (positional.length > 1) return usage(`unexpected positional argument '${positional[1]}'`);
+    if (global && positional.length > 0) return usage('-g reads the user layer only and takes no project');
+    let project                = null;
+    if (!global) {
+      project = path.resolve(cwd, positional[0] ?? '.');
+      if (!fs.existsSync(project) || !fs.statSync(project).isDirectory()) return usage(`project '${positional[0]}' is not a directory`);
+    }
+    if (taskClass != null) {
+      let known           = [];
+      try { known = Object.keys(readJson('gates.json').classes); } catch { /* every class is then unchecked; the report says unresolved */ }
+      if (known.length > 0 && !known.includes(taskClass)) return usage(`--task-class '${taskClass}' is not a task class (${known.join(', ')})`);
+    }
+    const report = buildRulesReport({ taskClass, global, project, env });
+    if (json) out(JSON.stringify(report));
+    else for (const line of rulesLines(report)) out(line);
+    return finishRuntime(0);
+  } catch (error     ) {
+    captureCaught(error, 'rules', 1);
+    console.error(`[ERROR] rules: ${error?.message || String(error)}`);
+    return finishRuntime(1);
+  }
+}
+
+module.exports = { handleRulesCommand, buildRulesReport, rulesLines };

package/src/runtime/scaffold/artifacts.js

@@ -5,7 +5,7 @@
 /**
  * Artifact parsing — turns the text of `requirement.md`, `design.md` and `plan.md` into the
  * structures `scaffold.js`'s generator reads: a requirement index and acceptance criteria, a
- * component index and whatever §4 declares as an interface, and the task list that is where the
+ * component index and whatever API / Interface Contracts declares as an interface, and the task list that is where the
  * intended file layout actually comes from.
  *
  * Pure text-in, structure-out: nothing here touches the filesystem or knows about the scaffold
@@ -93,7 +93,7 @@ function parseRequirement(text        )      {
 }
 
 /**
- * `design.md` → the component index (traceability) and whatever §4 declares as an interface
+ * `design.md` → the component index (traceability) and whatever API / Interface Contracts declares as an interface
  * (carried through verbatim rather than paraphrased).
  */
 function parseDesign(text        )      {
@@ -113,7 +113,7 @@ function parseDesign(text        )      {
     gaps.push({ artifact: 'design.md', what: 'component index', why: 'no `| Cn | … |` table row found under a "Components & Boundaries" heading' });
   }
 
-  // §4's subsections name their component in the heading — "### 4.5 Scaffold output contract (C16)".
+  // the Interface Contracts subsections name their component in the heading — "### 4.5 Scaffold output contract (C16)".
   // That attribution is what lets a declared interface reach the file that implements it, instead
   // of being restated from memory somewhere downstream.
   const contractBody = section(text, /API\s*\/?\s*Interface Contracts|Interface Contracts/i);
@@ -151,20 +151,57 @@ function parseDesign(text        )      {
  * `external-contract:` names the case this generator cannot help with: a dependency with no local
  * repo to scan — a vendor API, a SaaS integration, a service in another org — whose contract exists
  * only as a document. The doc is an *input* to the scaffold, never part of it.
+ *
+ * `tier:` (106 review R-1) is the task line's dispatch tier, read by dispatch the way brief-tools
+ * reads it. It never opens the metadata, and the parsed task carries `tier` only when the line has
+ * one, so a line without it parses exactly as before; the line hash and the graph tuples list their
+ * fields and do not read it.
+ */
+const TASK_KEYS = ['owner', 'files', 'depends-on', 'external-contract', 'acceptance', 'budget', 'tier'];
+
+/** DEC-021: the keys that open the metadata wherever they follow whitespace or a dash (8ce5ad7). */
+const LEGACY_KEY_PATTERN = /(?:^|[\s—-])(owner|files|depends-on|external-contract):\s/;
+/** DEC-021: the 080 keys open the metadata only after the em-dash separator. */
+const NEW_KEY_PATTERN = /—\s*(acceptance|budget):\s/;
+
+/** A `depends-on:` value naming another task of the same plan (IC-001). */
+const TASK_ID = /^[A-Za-z]+\.\d+$/;
+
+/**
+ * The `**Task graph:**` header before the first `## ` section (IC-001, DEC-008): `'v1'` opts the
+ * plan into the graph rules, absence is `null`, and any other value is kept as `{ invalid }` for
+ * IC-003's `bad-header`.
  */
-const TASK_KEYS = ['owner', 'files', 'depends-on', 'external-contract'];
+function parseGraphHeader(text        )                                    {
+  for (const line of text.split(/\r?\n/)) {
+    if (/^##\s/.test(line)) break;
+    const match = line.match(/^\*\*Task graph:\*\*\s*(.*)$/);
+    if (match) return match[1].trim() === 'v1' ? 'v1' : { invalid: match[1].trim() };
+  }
+  return null;
+}
+
+/** `budget: attempts=<n>`, n in 1..999; anything else is kept verbatim as `{ invalid }`. */
+function parseBudget(value                    )                                                    {
+  if (value === undefined) return null;
+  const raw = value.replace(/`/g, '').trim();
+  const match = raw.match(/^attempts=([0-9]+)$/);
+  const attempts = match ? Number(match[1]) : NaN;
+  return attempts >= 1 && attempts <= 999 ? { attempts } : { invalid: raw };
+}
 
 /** `plan.md` → the task list, which is where the intended file layout actually comes from. */
 function parsePlan(text        )      {
   const gaps        = [];
   const tasks        = [];
+  const graphHeader = parseGraphHeader(text);
 
   // Anchored on the whole heading: `### Task Summary` is orientation, not the task list, and a
   // loose match would read the summary table's rows as tasks.
   const body = section(text, /^##\s+(?:\d+\.\s*)?Tasks\s*$/i);
   if (body === null) {
     gaps.push({ artifact: 'plan.md', what: 'task list', why: 'no "Tasks" section' });
-    return { tasks, gaps };
+    return { tasks, gaps, graphHeader };
   }
 
   for (const line of joinWrapped(body)) {
@@ -174,8 +211,13 @@ function parsePlan(text        )      {
     if (!match) continue;
     const [, mark, id, rest] = match;
 
-    const keyPattern = new RegExp(`(?:^|[\\s—-])(${TASK_KEYS.join('|')}):\\s`);
-    const keyAt = rest.search(keyPattern);
+    // DEC-021 new-keys-open-after-separator: the four pre-080 keys open the metadata as on 8ce5ad7;
+    // `acceptance:` and `budget:` open it only after the ` — ` separator, so prose such as
+    // "Record the acceptance: criteria" in a description keeps its 8ce5ad7 parse and line hash.
+    // Once the metadata has started, every `;` chunk parses all six keys.
+    const legacyAt = rest.search(LEGACY_KEY_PATTERN);
+    const newAt = rest.search(NEW_KEY_PATTERN);
+    const keyAt = legacyAt === -1 ? newAt : newAt === -1 ? legacyAt : Math.min(legacyAt, newAt);
     const head = (keyAt === -1 ? rest : rest.slice(0, keyAt)).replace(/[\s—-]+$/, '').trim();
     const meta = keyAt === -1 ? '' : rest.slice(keyAt).replace(/^[\s—-]+/, '');
 
@@ -190,6 +232,9 @@ function parsePlan(text        )      {
     }
 
     const list = (value                    ) => (value ? value.split(',').map((v) => v.replace(/`/g, '').trim()).filter(Boolean) : []);
+    const dependsOn = list(fields['depends-on']);
+    // A near-miss starts with a task id but carries more text (`A.1 (after review)`).
+    const nearMiss = (value        ) => !TASK_ID.test(value) && TASK_ID.test(value.split(/[\s(]/)[0]);
 
     tasks.push({
       id,
@@ -199,15 +244,21 @@ function parsePlan(text        )      {
       stories,
       owner: fields.owner || null,
       files: list(fields.files),
-      dependsOn: list(fields['depends-on']),
+      dependsOn,
       externalContract: fields['external-contract'] || null,
+      parallel: /\[P\]/.test(head),
+      taskDeps: dependsOn.filter((value) => TASK_ID.test(value)),
+      nearMissDeps: dependsOn.filter(nearMiss),
+      acceptance: list(fields.acceptance),
+      budget: parseBudget(fields.budget),
+      ...(fields.tier === undefined ? {} : { tier: fields.tier.replace(/`/g, '').trim() }),
     });
   }
 
   if (tasks.length === 0) {
     gaps.push({ artifact: 'plan.md', what: 'task list', why: 'the Tasks section holds no `- [ ] <phase>.<n> …` items — there is no intended file layout to mirror' });
   }
-  return { tasks, gaps };
+  return { tasks, gaps, graphHeader };
 }
 
 module.exports = {

package/src/runtime/scaffold/generate.js

@@ -336,13 +336,13 @@ function planSourceStubs({ byPath, scaffoldDir, repoRoot, fsImpl, slug, message,
         ? reqs.map((r     ) => `requirement:   ${r.id} — ${r.summary}`)
         : ['requirement:   none — no user story on the owning task resolves to a requirement']),
       ...(comps.length
-        ? comps.map((c     ) => `component:     ${c.id} — ${c.name} (design.md §3)`)
+        ? comps.map((c     ) => `component:     ${c.id} — ${c.name} (design.md Components & Boundaries)`)
         : ['component:     none — no design component serves this task\'s requirements']),
     ];
 
     const bodyParts           = [''];
     if (declared.length) {
-      header.push(`shape:         declared in design.md §4 (${[...new Set(declared.map((d     ) => d.component))].join(', ')}), quoted below`);
+      header.push(`shape:         declared in design.md API / Interface Contracts (${[...new Set(declared.map((d     ) => d.component))].join(', ')}), quoted below`);
       for (const decl of declared) {
         const lines = decl.block.split('\n');
         const shown = lines.slice(0, 40);
@@ -354,11 +354,11 @@ function planSourceStubs({ byPath, scaffoldDir, repoRoot, fsImpl, slug, message,
         ].join('\n'));
       }
     } else {
-      header.push('shape:         not declared in design.md §4 — placeholder signature below');
+      header.push('shape:         not declared in design.md API / Interface Contracts — placeholder signature below');
       // Not a skip — the file was emitted. Conflating the two would let 29 "we wrote it, but the
       // design never said what it should look like" rows hide inside a skip count, which is the
       // opposite of what the manifest is for.
-      shapeUndeclared.push({ path: path.join('src', file) + STUB_SUFFIX, why: 'design.md §4 declares no interface for this file\'s component — the signature below is a placeholder, not a contract' });
+      shapeUndeclared.push({ path: path.join('src', file) + STUB_SUFFIX, why: 'design.md API / Interface Contracts declares no interface for this file\'s component — the signature below is a placeholder, not a contract' });
     }
 
     const pkg = snake(words(path.basename(path.dirname(file)) || 'scaffold')).replace(/_/g, '');
@@ -422,7 +422,7 @@ function planTestStubs({ requirement, componentsForRequirement, language, slug,
           'reads as coverage. Replace the body, do not delete the failure.',
           '',
           `requirement:   ${id}${req ? ` — ${req.summary}` : ' — not present in the requirement index'}`,
-          ...(comps.length ? comps.map((c     ) => `component:     ${c.id} — ${c.name} (design.md §3)`) : []),
+          ...(comps.length ? comps.map((c     ) => `component:     ${c.id} — ${c.name} (design.md Components & Boundaries)`) : []),
           `criteria:      ${cases.length} from requirement.md §6`,
           `language:      ${language.id} (detected from ${language.signal} by command-detect.ts)`,
         ];
@@ -442,15 +442,27 @@ function planTestStubs({ requirement, componentsForRequirement, language, slug,
 /**
  * contracts/ — partitioned here, generated by the prose algorithm. See the module header for why
  * the walk-up is not reimplemented in code.
+ * A task-id `depends-on:` value (`taskDeps`) is an edge in the task graph, not a service, so it
+ * gets no frame. A task whose `external-contract:` is left with no external value after that
+ * filter is pushed onto `notEvaluated` as `external-contract-orphaned` rather than dropped (IC-001).
  * @param {Array<Object>} tasks from `plan.tasks`
  * @param {Set<string>} ownedPaths every path a task in this plan already owns
+ * @param {Array<Object>} notEvaluated mutated with one entry per orphaned `external-contract:`
  * @returns {Array<Object>} externalDependencies
  */
-function partitionExternalDependencies(tasks       , ownedPaths             )        {
+function partitionExternalDependencies(tasks       , ownedPaths             , notEvaluated       )        {
   const externalDependencies        = [];
   const dependencyTasks = new Map               ();
   for (const task of tasks) {
-    for (const dep of task.dependsOn) {
+    const taskDeps = new Set(task.taskDeps || []);
+    const external = task.dependsOn.filter((dep        ) => !taskDeps.has(dep));
+    if (task.externalContract && external.length === 0) {
+      notEvaluated.push({
+        what: `plan.md → ${task.id} external-contract: ${task.externalContract}`,
+        why: 'external-contract-orphaned — no external depends-on: value remains once task-id dependencies are removed, so no contract frame is generated from it',
+      });
+    }
+    for (const dep of external) {
       if (!dependencyTasks.has(dep)) dependencyTasks.set(dep, []);
       dependencyTasks.get(dep) .push(task);
     }
@@ -714,7 +726,7 @@ function generateScaffold(options      = {})      {
   const planned = new Map([...sourcePlanned, ...testPlanned]);
 
   const ownedPaths = new Set([...byPath.keys()]);
-  const externalDependencies = partitionExternalDependencies(plan.tasks, ownedPaths);
+  const externalDependencies = partitionExternalDependencies(plan.tasks, ownedPaths, notEvaluated);
 
   const { written, unchanged, preserved } = applyPlannedFiles({ planned, blocked, scaffoldDir, fsImpl });
 
@@ -777,7 +789,7 @@ function renderManifest(result     , planned                  )         {
     '_Nothing generated._');
 
   lines.push('## Emitted without a declared shape', '');
-  lines.push('These files exist and are traceable, but `design.md` §4 never declared an interface for',
+  lines.push('These files exist and are traceable, but `design.md` API / Interface Contracts never declared an interface for',
     'them, so their signature is a placeholder rather than a contract. Reviewing the placeholder as',
     'if it were the designed API is the mistake this section exists to prevent.', '');
   table(['Path', 'Why'], result.shapeUndeclared.map((s     ) => [s.path, s.why]),