amsd-pipeline-shared 0.5.0 → 0.5.2

package/orchestrations/scripts/lib/handlers/prd-phases.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * THE PHASES A PRD DECLARES, ONE PER LINE.
+ *
+ * The caller loops over these to run each phase of a codeline. An empty list means "this PRD
+ * declares no phases", and the loop then does nothing — so this must never return empty for any
+ * reason other than the PRD genuinely having none.
+ *
+ * IT DID. Extracted from an inline shell snippet, the body kept the shell's own placeholder:
+ *
+ *     require('./_read-input.js').readJsonOrRefuse('$1', 'the PRD', { expect: 'object' })
+ *
+ * `$1` was never substituted, so it tried to open a file literally named `$1`, threw, and the
+ * caller's `2>/dev/null` swallowed it. Every parallel lane received an empty phase list, ran its
+ * loop zero times, and reported `✓ completed` — in five seconds, having done nothing. Live
+ * 2026-08-17, mock3: two lanes, two pending stories, no writer invoked, no commit, pipeline
+ * reported success.
+ *
+ * The caller passed the path all along; the function it called dropped the argument.
+ *
+ *   argv[2]  the PRD to read; falls back to $PRD_FILE
+ *   stdout   one phase id per line, in declared order
+ *   exit 1   the PRD cannot be read or parsed — NOT an empty list, which reads as "no phases"
+ */
+'use strict';
+
+const fs = require('fs');
+
+const file = process.argv[2] || process.env.PRD_FILE || '';
+if (!file) {
+  process.stderr.write('[prd-phases] no PRD given: pass a path or set PRD_FILE\n');
+  process.exit(1);
+}
+
+let prd;
+try {
+  prd = require('./_read-input.js').readJsonOrRefuse(file, 'the PRD', { expect: 'object' });
+} catch (err) {
+  // LOUD. A silent failure here is indistinguishable from a PRD with no phases, and the caller
+  // treats that as "nothing to do" rather than "I could not tell".
+  process.stderr.write(`[prd-phases] cannot read ${file}: ${err.message}\n`);
+  process.exit(1);
+}
+
+const phases = Object.keys(prd.implementationOrder || {});
+process.stdout.write(phases.length ? `${phases.join('\n')}\n` : '');

package/orchestrations/scripts/lib/handlers/rebuild-cross-contract.js

@@ -0,0 +1,7 @@
+      const fs = require('fs');
+      const paths = (process.env.COMPLETED_LIST||'').split(':').filter(Boolean);
+      const stories = paths.flatMap(p => {
+        try { return JSON.parse(fs.readFileSync(p,'utf8')).stories||[]; } catch { return []; }
+      });
+      fs.writeFileSync(process.argv[2], JSON.stringify({stories},null,2));
+    

package/orchestrations/scripts/lib/handlers/record-declared-pass.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * record-declared-pass.js <prd> <codeline> — a lane the operator declared passed (EPAM_PASSED_LANES) is that
+ * codeline's result for every story spanning it, recorded as one and marked as declared. A codeline that already
+ * has a result keeps it. AMSD-2974 run 9 (2026-10-08): declared lanes recorded nothing, and the completeness check
+ * (spanning-stories-incomplete.js) failed the run for them.
+ */
+'use strict';
+const fs = require('fs');
+
+const [file, cl] = process.argv.slice(2);
+try {
+  const prd = JSON.parse(fs.readFileSync(file, 'utf8'));
+  let changed = false;
+  for (const s of prd.stories || []) {
+    if (!s || !Array.isArray(s.codelines) || !s.codelines.includes(cl)) continue;
+    s.perCodeline = s.perCodeline || {};
+    if (s.perCodeline[cl]) continue;
+    s.perCodeline[cl] = { status: 'completed', completed: true, completedAt: new Date().toISOString(), reviewStatus: 'declared-passed' };
+    changed = true;
+  }
+  if (changed) fs.writeFileSync(file, JSON.stringify(prd, null, 2));
+} catch (e) { process.stderr.write(`[record-declared-pass] ${e.message}\n`); process.exit(1); }

package/orchestrations/scripts/lib/handlers/release-line-prd.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * release-line-prd.js <lane-prd> <out> <codeline> <line> — the lane's PRD for one more release line.
+ *
+ * The stories whose plan ships on that line for this codeline, pending again — a story completed on the codeline's
+ * own base is not done on another line (each line is its own branch and its own change). Everything else about the
+ * story (its plan, its fix sites, its criteria) is kept: the line is worked from the same plan.
+ */
+'use strict';
+const fs = require('fs');
+
+const [src, out, codeline, line, canonicalFile] = process.argv.slice(2);
+const prd = JSON.parse(fs.readFileSync(src, 'utf8'));
+// A resumed lane works from its checkpoint PRD, which may predate the plan: the canonical PRD holds it then.
+const canonical = canonicalFile && fs.existsSync(canonicalFile) ? JSON.parse(fs.readFileSync(canonicalFile, 'utf8')) : null;
+for (const s of prd.stories || []) {
+  const c = s && !s.overallPlan && ((canonical && canonical.stories) || []).find((x) => x && x.id === s.id);
+  if (c && c.overallPlan) s.overallPlan = c.overallPlan;
+}
+const onLine = (s) => !!(s && s.overallPlan && (s.overallPlan.packages || []).some((p) => p && p.providedBy === codeline
+  && (p.releaseLines || []).some((l) => l && l.line === line)));
+const stories = (prd.stories || []).filter(onLine).map((s) => ({
+  ...s, status: 'pending', completed: false, passes: false, completedAt: null,
+}));
+const ids = new Set(stories.map((s) => s.id));
+const order = {};
+for (const [phase, list] of Object.entries(prd.implementationOrder || {})) {
+  const kept = (list || []).filter((id) => ids.has(id));
+  if (kept.length) order[phase] = kept;
+}
+fs.writeFileSync(out, JSON.stringify({ ...prd, stories, implementationOrder: order }, null, 2));

package/orchestrations/scripts/lib/handlers/release-lines.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * release-lines.js <prd> <codeline> — the release lines this codeline ships on beyond its own base.
+ *
+ * Read from the story's plan (detective-overall-plan): for each package this codeline provides, each release line
+ * the plan marks onCodelineBase:false, as "<line>\t<base>". The plan decides how many — 0, 1 or N; a line whose
+ * onCodelineBase is not stated is not guessed at. A codeline used to have one base and one story branch, and a shared
+ * library could not ship on the older lines its consumers are locked to (AMSD-2974, 2026-10-06).
+ */
+'use strict';
+const fs = require('fs');
+
+const [prdFile, codeline, canonicalFile] = process.argv.slice(2);
+const prd = JSON.parse(fs.readFileSync(prdFile, 'utf8'));
+// A resumed lane works from its checkpoint PRD, which may predate the plan: the canonical PRD holds it then.
+const canonical = canonicalFile && fs.existsSync(canonicalFile) ? JSON.parse(fs.readFileSync(canonicalFile, 'utf8')) : null;
+const planOf = (s) => (s && s.overallPlan) || ((canonical && canonical.stories || []).find((c) => c && c.id === s.id) || {}).overallPlan;
+const seen = new Set();
+for (const s of (prd && Array.isArray(prd.stories) ? prd.stories : [])) {
+  const plan = s && planOf(s);
+  for (const p of (plan && Array.isArray(plan.packages) ? plan.packages : [])) {
+    if (!p || p.providedBy !== codeline) continue;
+    for (const l of (Array.isArray(p.releaseLines) ? p.releaseLines : [])) {
+      if (!l || l.onCodelineBase !== false || !l.line || !l.base) continue;
+      const key = `${l.line}\t${l.base}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      process.stdout.write(`${key}\n`);
+    }
+  }
+}

package/orchestrations/scripts/lib/handlers/repo-exclude-patterns.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * WHAT IS NEVER AGENT OUTPUT — one answer, for every caller that needs it.
+ *
+ * Two shell files each carried a hand-written list, and they had drifted. worktree-health-check.sh
+ * named `.dart_tool`, `build`, `node_modules`; lib/git-ops.sh named `node_modules`, `build`,
+ * `.next`. Between them they described one ecosystem.
+ *
+ * The consequences ran in both directions. `git_add_client_outputs` decides what is COMMITTED TO A
+ * CLIENT REPOSITORY: on a Rust codeline whose target/ was not gitignored, the build tree was staged
+ * into the customer's repo. And the health check's list decides what counts as the agent's
+ * uncommitted work: the same directory was reported as thousands of uncommitted files, which set
+ * issues=1, which made Step 3.1 exit 1 and killed the phase.
+ *
+ * Ecosystem artefacts come from lib/ecosystem-registry.js, beside the ecosystem that produces them. Editor
+ * and OS droppings come from config/repo-artifacts.json. Nothing is named here.
+ *
+ *   argv[2]  the form the caller wants:
+ *              pathspec  git exclude pathspecs, one per line — for `git add -A -- ...`
+ *              glob      shell case-patterns, one per line — for a status-line filter
+ *              regex     one ERE matching any excluded path — for a `grep -vE` filter
+ *              diff      pathspec PLUS lockfiles — for the patch a REVIEW agent is shown
+ *
+ * `diff` is deliberately wider than `pathspec`. A lockfile must still be STAGED: a real dependency
+ * change belongs in the commit. But it must not be REVIEWED — it is machine-generated, frequently
+ * thousands of lines, and it would consume the reviewer's whole budget before it reached the code
+ * the change is actually about. Staging and reviewing are different questions, so they get
+ * different answers rather than one list bent to serve both.
+ *
+ * Every directory is emitted in BOTH the top-level and the nested form. `:!*​/node_modules/*`
+ * matches only a NESTED one; a top-level node_modules — the usual case — needs `:!node_modules/*`.
+ * The original list carried only the nested form, so a repo without node_modules in .gitignore
+ * staged the lot.
+ *
+ * Exit non-zero if the registry or the config cannot be read. A caller that silently fell back to
+ * an empty exclusion list would stage everything, which is the failure this exists to prevent.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { allArtifactDirs, allManifests } = require('../ecosystem-registry.js');
+
+const form = process.argv[2] || 'pathspec';
+if (!['pathspec', 'glob', 'regex', 'diff'].includes(form)) {
+  process.stderr.write(`[repo-exclude-patterns] unknown form: ${form}\n`);
+  process.exit(2);
+}
+
+const configPath = path.join(__dirname, '..', '..', '..', 'config', 'repo-artifacts.json');
+let config;
+try {
+  config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+} catch (err) {
+  // LOUD. An empty exclusion list stages a client's build tree into their repository.
+  process.stderr.write(`[repo-exclude-patterns] cannot read ${configPath}: ${err.message}\n`);
+  process.exit(1);
+}
+
+const dirs = [...new Set([...allArtifactDirs(), ...(config.dirs || [])])];
+const files = config.files || [];
+const enginePaths = config.enginePaths || [];
+
+// Lockfile names come from the ecosystem registry, beside the ecosystem that produces them.
+const lockfiles = [...new Set(allManifests().flatMap((e) => Object.keys(e.lockfiles || {})))];
+
+const out = [];
+if (form === 'pathspec' || form === 'diff') {
+  // THE LONG FORM, ALWAYS. git parses `:!` as the start of a magic signature and keeps reading
+  // magic characters, so `:!__pycache__/*` dies with "Unimplemented pathspec magic '_'" — which
+  // fails the whole `git add` and stages NOTHING. `:(exclude)` is unambiguous whatever follows.
+  // ONE GLOB PER DIRECTORY, NOT A TOP-LEVEL AND A NESTED PREFIX.
+  //
+  // `:(exclude)<dir>/*` is FATAL, not merely unmatched, when the directory is a symlink — git
+  // refuses a pathspec that crosses one:
+  //
+  //   fatal: pathspec ':(exclude)node_modules/*' is beyond a symbolic link
+  //
+  // Live 2026-08-18, both lanes, at the LAST step of a run that had otherwise succeeded — the fix
+  // was correct, the tests passed, the type check passed — every commit failed with exit 128
+  // because both codelines symlink node_modules to a shared install. Nothing could ever be
+  // committed in such a repo, and the story was demoted as undelivered.
+  //
+  // The bare `:(exclude)<dir>` form survives the symlink but stops excluding NESTED copies, which
+  // would stage a client's vendored tree: fixing the error by weakening the exclusion. The glob
+  // form is correct on all three counts — top-level contents, nested contents, and a symlinked
+  // directory — and replaces both prefixes with one pattern.
+  // TWO PATTERNS: the CONTENTS at any depth, and the ENTRY itself. A symlinked directory is a
+  // single entry to git, so the contents glob does not cover it and the link would be staged.
+  for (const d of dirs) out.push(`:(exclude,glob)**/${d}/**`, `:(exclude,glob)**/${d}`);
+  for (const f of files) out.push(`:(exclude)${f}`, `:(exclude)*/${f}`);
+  for (const p of enginePaths) out.push(`:(exclude)${p}`);
+  if (form === 'diff') {
+    for (const f of lockfiles) out.push(`:(exclude)${f}`, `:(exclude)*/${f}`);
+  }
+} else if (form === 'regex') {
+  // Anchored at the start OR after a slash, so it matches a top-level and a nested one alike.
+  const alt = [...dirs, ...files].map((d) => d.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+  process.stdout.write(`(^|/)(${alt})(/|$)\n`);
+  process.exit(0);
+} else {
+  for (const d of dirs) out.push(`${d}/*`, `*/${d}/*`);
+  for (const f of files) out.push(f, `*/${f}`);
+  for (const p of enginePaths) out.push(p);
+}
+
+process.stdout.write(`${out.join('\n')}\n`);

package/orchestrations/scripts/lib/handlers/resume-spec-output-present.js

@@ -0,0 +1,16 @@
+// THE PRD IS argv[2]. This read argv[1] — the script's own path — so it parsed its own
+// JavaScript as JSON, threw, and answered "no spec output" for every PRD ever passed to it.
+// The guard could never pass, so every resume that skips the spec pass was refused. Same
+// extraction defect as lib/handlers/prd-phases.js, which carried a literal '$1' from the
+// shell heredoc it was lifted out of and made every lane loop zero times.
+      try {
+        const p = JSON.parse(require('fs').readFileSync(process.argv[2], 'utf8'));
+        const stories = Array.isArray(p.stories) ? p.stories : [];
+        const has = (v) => Array.isArray(v) ? v.length > 0
+          : (v && typeof v === 'object') ? Object.keys(v).length > 0 : false;
+        const survived = stories.some((s) => s && (
+          has(s.fixSiteAnalysis) || has(s.verificationCriteria) ||
+          has(s.specification) || has((s.technicalNotes || {}).files)));
+        process.exit(survived ? 0 : 1);
+      } catch { process.exit(1); }
+    

package/orchestrations/scripts/lib/handlers/sibling-providers.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * WHICH OF THIS STORY'S OTHER CODELINES PROVIDE A PACKAGE THIS CODELINE DECLARES.
+ *
+ * A story spanning a shared library and the sites that consume it changes the library in its own
+ * lane; a site lane must build and test against THAT change, not the release it has installed. The
+ * facts come from lib/codeline-packages.js (each codeline's manifest, read by its ecosystem
+ * provider), scoped to the codelines the story spans — never the whole estate, never configured.
+ *
+ *   argv[2]  the lane's PRD (project.outputDirs: [{codeline, path}])
+ *   argv[3]  this codeline's root
+ *   stdout   one "packageName<TAB>providerRoot" line per sibling package this codeline declares
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { codelinePackages } = require('../codeline-packages.js');
+
+try {
+  const prd = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+  const here = path.resolve(process.argv[3] || '');
+  const dirs = (prd.project && Array.isArray(prd.project.outputDirs)) ? prd.project.outputDirs : [];
+  const mine = dirs.find((d) => d && d.path && path.resolve(d.path) === here);
+  if (!mine) process.exit(0);
+  const facts = codelinePackages(prd, dirs.map((d) => d.codeline));
+  const me = facts.find((f) => f.codeline === mine.codeline);
+  for (const name of Object.keys((me && me.declares) || {})) {
+    const provider = facts.find((f) => f.codeline !== mine.codeline && f.provides && f.provides.name === name);
+    const root = provider && (dirs.find((d) => d.codeline === provider.codeline) || {}).path;
+    // THE LINE THIS CONSUMER RECEIVES (the story's plan): a version shipped on a release line off the provider's own
+    // base is built from that line's story branch — suffix and story id, for the caller to name it.
+    let suffix = ''; let story = '';
+    for (const s of prd.stories || []) {
+      for (const p of ((s && s.overallPlan && s.overallPlan.packages) || [])) {
+        if (p.package !== name) continue;
+        const c = (p.consumers || []).find((x) => x && x.codeline === mine.codeline);
+        const l = c && (p.releaseLines || []).find((x) => x && x.version === c.receivesVia);
+        if (l && l.onCodelineBase === false && !suffix) { suffix = `-${String(l.line).replace(/[^A-Za-z0-9._-]/g, '-')}`; story = s.id; }
+      }
+    }
+    if (root) process.stdout.write(`${name}\t${root}\t${suffix}\t${story}\n`);
+  }
+} catch { process.exit(0); }

package/orchestrations/scripts/lib/handlers/spanning-stories-incomplete.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * WHICH SPANNING STORIES HAVE NOT REPORTED FROM EVERY CODELINE.
+ *
+ * A story listing two or more codelines is not finished when one lane succeeds — it is finished
+ * when every codeline it names has produced a result. Running it as "done" after one lane reports
+ * ships a fraction of the work while the run says success.
+ *
+ * Lifted out of run-agent-orchestration.sh on 2026-08-16, where it was a `node -e "..."` string.
+ * As a string it could not be tested, linted or type-checked, and it was invoked with
+ * `2>/dev/null || true`, so a syntax error in it and "every story is complete" were the same
+ * observation.
+ *
+ * Generic: the PRD path is an argument, and the rule holds for any project and any stack.
+ *
+ *   argv[2]  path to the PRD
+ *   stdout   "<story-id> → no result for: <codeline>, <codeline>" per offender, "; "-separated
+ *   exit 0   always when the PRD could be read — an empty result means nothing is incomplete
+ *   exit 1   the PRD is missing or unreadable, which is NOT the same as nothing being incomplete
+ */
+'use strict';
+
+const fs = require('fs');
+
+const prdPath = process.argv[2];
+if (!prdPath) {
+  process.stderr.write('[spanning-stories-incomplete] usage: <prd-path>\n');
+  process.exit(1);
+}
+
+let prd;
+try {
+  prd = require('./_read-input.js').readJsonOrRefuse(prdPath, 'the PRD', { expect: 'object' });
+} catch (e) {
+  // LOUD. The inline version swallowed this: an unreadable PRD produced an empty string, which
+  // the caller read as "no spanning story is incomplete" and carried on.
+  process.stderr.write(`[spanning-stories-incomplete] cannot read ${prdPath}: ${e && e.message}\n`);
+  process.exit(1);
+}
+
+const bad = [];
+for (const s of (prd.stories || [])) {
+  const want = Array.isArray(s.codelines) ? s.codelines : [];
+  if (want.length < 2) continue;                       // not a spanning story
+  const got = s.perCodeline || {};
+  const missing = want.filter((cl) => !got[cl]);
+  if (missing.length) bad.push(`${s.id} → no result for: ${missing.join(', ')}`);
+}
+
+process.stdout.write(bad.join('; '));

package/orchestrations/scripts/lib/handlers/spec-inputs-digest.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * spec-inputs-digest.js [orchestrationsDir] — WHAT A LANE'S SPECIFICATION WAS BUILT FROM, as one digest.
+ *
+ * config/spec-inputs.json declares it: the seams that produce the specification (by what they
+ * PRODUCE in the registry, never by name) — each one's base SI and every template file of its
+ * template family — and the SI contract's sections every agent receives. A lane's pre-writer
+ * checkpoint records this; a resume compares it (lib/run-checkpoint.sh lane_spec_is_current).
+ *
+ * Prints a sha256 hex digest; nothing when the declaration cannot be read.
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+function specInputsDigest(orchDir) {
+  const decl = JSON.parse(fs.readFileSync(path.join(orchDir, 'config', 'spec-inputs.json'), 'utf8'));
+  const reg = JSON.parse(fs.readFileSync(path.join(orchDir, 'agents', 'invocation-profiles.json'), 'utf8'));
+  const contract = JSON.parse(fs.readFileSync(path.join(orchDir, 'config', 'agent-contract.json'), 'utf8'));
+  const tplDir = path.join(orchDir, 'prompts', 'templates');
+  const tplFiles = fs.readdirSync(tplDir).filter((f) => f.endsWith('.json')).sort();
+  const produces = new Set(decl.produces || []);
+  const parts = [];
+  for (const [seam, p] of Object.entries(reg.profiles || {}).sort(([a], [b]) => a.localeCompare(b))) {
+    if (!p || !produces.has(p.produces)) continue;
+    parts.push(['seam', seam, p.si || '']);
+    const t = p.template;
+    if (!t) continue;
+    // The template and its family (<template>.<variant>.json, <template>-<part>.json).
+    for (const f of tplFiles) {
+      const id = f.slice(0, -5);
+      if (id === t || id.startsWith(`${t}.`) || id.startsWith(`${t}-`)) parts.push(['template', f, fs.readFileSync(path.join(tplDir, f), 'utf8')]);
+    }
+  }
+  // Templates the spec seams render without owning them (config: templates).
+  for (const t of decl.templates || []) {
+    for (const f of tplFiles) if (f.slice(0, -5) === t) parts.push(['shared-template', f, fs.readFileSync(path.join(tplDir, f), 'utf8')]);
+  }
+  for (const k of decl.contractSections || []) parts.push(['contract', k, contract[k] === undefined ? null : contract[k]]);
+  return crypto.createHash('sha256').update(JSON.stringify(parts)).digest('hex');
+}
+
+if (require.main === module) {
+  try { process.stdout.write(specInputsDigest(process.argv[2] || path.join(__dirname, '..', '..', '..'))); } catch { process.exit(0); }
+}
+
+module.exports = { specInputsDigest };

package/orchestrations/scripts/lib/handlers/spec-predates-plan.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * spec-predates-plan.js <prd> [canonical-prd] — the specified stories whose spec was built under another plan.
+ *
+ * A story's spec (fix sites, criteria) is the elaboration of its plan. AMSD-2974 (2026-10-08): every lane resumed a
+ * spec approved on 10-01, before the story had a plan; the plan then gave upexpress no change while its criteria
+ * demanded upexpress-owned work — the reviewer rejected, the writer was skipped, round after round. A spec made under
+ * a different plan, or under none, is the spec of another story: it is specified again, from the plan it has now.
+ *
+ *   stdout  one story id per line whose spec predates its plan; nothing otherwise. The plan is the story's own, or
+ *           the canonical PRD's when the story carries none (a lane's checkpoint copy may predate the plan).
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { planHash } = require(path.join(__dirname, '..', 'plan-hash.js'));
+
+function specPredatesPlan(prd, canonical) {
+  const canon = new Map(((canonical && canonical.stories) || []).filter(Boolean).map((s) => [s.id, s]));
+  return (prd.stories || [])
+    .filter((s) => s && s.status !== 'deprecated' && s.specification && s.specification.runId)
+    .filter((s) => {
+      // The run's plan is the canonical PRD's; a lane copy carries the plan it was specified under.
+      const plan = (canon.get(s.id) || {}).overallPlan || s.overallPlan;
+      const now = planHash(plan);
+      return now !== '' && now !== (s.specification.planHash || '');
+    })
+    .map((s) => s.id);
+}
+
+module.exports = { specPredatesPlan };
+
+if (require.main === module) {
+  try {
+    const prd = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+    const canonical = process.argv[3] && fs.existsSync(process.argv[3]) ? JSON.parse(fs.readFileSync(process.argv[3], 'utf8')) : null;
+    const out = specPredatesPlan(prd, canonical);
+    if (out.length) process.stdout.write(out.join('\n') + '\n');
+  } catch (e) { process.stderr.write(`[spec-predates-plan] ${e.message}\n`); }
+}

package/orchestrations/scripts/lib/handlers/stories-lacking-spec.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * WHICH PENDING STORIES OF A PHASE CARRY NO SPEC OUTPUT?
+ *
+ * The spec pass elaborates a story and records it under specification.appliedAgents (the same
+ * mark spec-mode-runner uses to count a story as specified). On a resume the run mode turns the
+ * whole spec pass off, which is right only while EVERY pending story was elaborated; a story
+ * whose content the remediation restored from canonical (its elaboration had gone to a
+ * placeholder child, regintel run 20260915T101555Z) reached the writer with no spec. This names
+ * the stories that still need the pass, so the resume runs it for them and them alone.
+ *
+ * Generic: the PRD is an argument; nothing here names a project, a stack or a story.
+ *
+ *   argv[1]  the PRD
+ *   argv[2]  a phase (optional; every phase when absent)
+ *   stdout   the story ids, one per line; nothing when every pending story is specified
+ */
+const fs = require('fs');
+
+/**
+ * A STORY THAT SPANS CODELINES IS SPECIFIED PER CODELINE. In a lane's PRD (story.codeline = the lane)
+ * the spec mark from another lane is not this lane's spec: AMSD-2974's three site lanes skipped their
+ * spec pass on a resume because cxshared's spec had stamped the story (2026-10-01). The lane's own
+ * fix-site entry is the mark that this codeline was investigated.
+ */
+function lacksOwnLane(s) {
+  if (!Array.isArray(s.codelines) || s.codelines.length < 2 || !s.codeline) return false;
+  // This lane's own spec pass stamped its codeline on the spec (spec-mode-runner.js stampSpecification).
+  if (s.specification && s.specification.runId && s.specification.codeline === s.codeline) return false;
+  const own = s.fixSiteAnalysisPerCodeline;
+  return !(own && Object.prototype.hasOwnProperty.call(own, s.codeline));
+}
+
+// A spec built under another plan, or before the story had one, is not this story's spec (spec-predates-plan.js).
+const { specPredatesPlan } = require('./spec-predates-plan.js');
+
+function storiesLackingSpec(prd, phase) {
+  const predates = new Set(specPredatesPlan(prd));
+  const byId = new Map((prd.stories || []).map((s) => [s.id, s]));
+  const ids = phase
+    ? ((prd.implementationOrder || {})[phase] || [])
+    : Object.values(prd.implementationOrder || {}).flat();
+  return ids
+    .map((id) => byId.get(id))
+    .filter((s) => s && s.completed !== true && s.status !== 'deprecated')
+    // THE PASS'S WRITE IS THE MARK. Every spec-pass write stamps specification.runId — on the
+    // story it specified and on each child it split off. Judging by appliedAgents counted the
+    // pass's own children as spec-less, and every resume re-split them (run 20260915T101555Z).
+    .filter((s) => !(s.specification && s.specification.runId) || lacksOwnLane(s) || predates.has(s.id))
+    .map((s) => s.id);
+}
+
+module.exports = { storiesLackingSpec };
+
+if (require.main === module) {
+  try {
+    const prd = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+    const out = storiesLackingSpec(prd, process.argv[3] || '');
+    if (out.length) process.stdout.write(out.join('\n') + '\n');
+  } catch (e) {
+    process.stderr.write(`[stories-lacking-spec] ${e.message}\n`);
+    process.exit(2);
+  }
+}

package/orchestrations/scripts/lib/handlers/write-missing-plans.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * write-missing-plans.js <canonical-prd> — a story specified before it had a plan gets its plan.
+ *
+ * The story's plan (detective-overall-plan) is written by its first detective during the spec pass. A story already
+ * specified before plans existed is never specified again on a resume, so no detective writes one and no release line
+ * the plan would name can ever run (the £0 rehearsal of AMSD-2974, 2026-10-06). Operator, 2026-10-06: such a story
+ * gets its plan — the detective's plan only: its fix sites, criteria and every other field are left as they are.
+ *
+ * Which stories: every story with no plan — the plan comes first, before any lane, so every codeline and every release
+ * line is worked from it (a resume's canonical PRD may carry no spec output at all: it lives in the lanes' checkpoints).
+ * A story with a plan keeps it. The detective runs as the spec pass runs it, for the story's first codeline, able to
+ * read every codeline of the story. A detective that cannot answer leaves no plan and says so — the run goes on.
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const prdFile = process.argv[2];
+const prd = JSON.parse(fs.readFileSync(prdFile, 'utf8'));
+const dirs = (prd.project && Array.isArray(prd.project.outputDirs)) ? prd.project.outputDirs : [];
+const { planScope, adoptPlanCodelines } = require('../plan-scope.js');
+
+// A STORY IS PLANNED ONCE PER RUN. A resume restores the canonical PRD from the run's checkpoint, which never held the
+// plan; asked again, the detective answered differently (AMSD-2974, 2026-10-07). The plan a run wrote is kept under the
+// run and is the plan on every later launch of it.
+const cfg = process.env.EPAM_PROJECT_CONFIG_DIR || process.env.PROJECT_CONFIG_DIR || '';
+const run = process.env.EPAM_RESUME_RUN || process.env.ORCH_RUN_ID || '';
+// What discovery grounded this run (one top-level key per codeline, with its path); absent = the story's own codelines.
+let facts = null;
+try { facts = cfg ? JSON.parse(fs.readFileSync(path.join(cfg, 'codeline-facts.json'), 'utf8')) : null; } catch { facts = null; }
+const keptDir = cfg && run ? path.join(cfg, 'runs', run, 'plans') : '';
+const keptFile = (id) => (keptDir ? path.join(keptDir, `${String(id).replace(/[^A-Za-z0-9._-]/g, '_')}.json`) : '');
+const keep = (s) => {
+  const f = keptFile(s.id);
+  if (!f || fs.existsSync(f)) return;
+  fs.mkdirSync(keptDir, { recursive: true });
+  fs.writeFileSync(f, JSON.stringify(s.overallPlan, null, 2));
+};
+let restored = false;
+for (const s of prd.stories || []) {
+  if (!s) continue;
+  if (s.overallPlan) { keep(s); if (adoptPlanCodelines(s, prd, facts).length) restored = true; continue; }
+  const f = keptFile(s.id);
+  if (f && fs.existsSync(f)) {
+    s.overallPlan = JSON.parse(fs.readFileSync(f, 'utf8'));
+    adoptPlanCodelines(s, prd, facts);
+    restored = true;
+    process.stderr.write(`[plan] ${s.id}: the plan this run wrote is kept — ${f}\n`);
+  }
+}
+if (restored) fs.writeFileSync(prdFile, JSON.stringify(prd, null, 2));
+const wanting = (prd.stories || []).filter((s) => s && !s.overallPlan);
+if (!wanting.length) process.exit(0);
+
+process.env.SPEC_MODE_NO_MAIN = '1';
+// eslint-disable-next-line global-require
+const runner = require(path.join(__dirname, '..', '..', 'spec-mode-runner.js'));
+
+(async () => {
+  let changed = false;
+  for (const s of wanting) {
+    const first = (Array.isArray(s.codelines) && s.codelines[0]) || s.codeline;
+    const root = (dirs.find((d) => d && d.codeline === first) || {}).path || prd.project.outputDir || '';
+    // THE DETECTIVE IS SHOWN EVERY CODELINE DISCOVERY GROUNDED (lib/plan-scope.js), not only the router's pick: the plan
+    // decides which codelines change and which only receive (AMSD-2974 run 1, 2026-10-09).
+    const scope = planScope(s, prd, facts);
+    const probe = { ...s, codeline: first, codelines: scope.codelines };
+    delete probe.overallPlan;
+    const prevRoot = process.env.PROJECT_ROOT;
+    process.env.PROJECT_ROOT = root;
+    try {
+      await runner.runCodeGraphDetective(probe, process.env.LOG_DIR || '', { prd: { ...prd, project: { ...prd.project, outputDirs: scope.outputDirs } } });
+    } catch (e) {
+      process.stderr.write(`[plan] ${s.id}: the detective did not answer (${(e && e.message) || e})\n`);
+    } finally {
+      if (prevRoot === undefined) delete process.env.PROJECT_ROOT; else process.env.PROJECT_ROOT = prevRoot;
+    }
+    if (probe.overallPlan) {
+      s.overallPlan = probe.overallPlan;
+      keep(s);
+      changed = true;
+      const added = adoptPlanCodelines(s, prd, facts);
+      if (added.length) process.stderr.write(`[plan] ${s.id}: the plan works ${added.join(', ')} too — the story is worked in ${s.codelines.join(', ')}\n`);
+      process.stderr.write(`[plan] ${s.id}: plan written (${probe.overallPlan.codelines.length} codeline(s), `
+        + `${(probe.overallPlan.packages || []).reduce((n, p) => n + (p.releaseLines || []).length, 0)} release line(s))\n`);
+    } else {
+      process.stderr.write(`[plan] ${s.id}: no plan — the detective gave none; this story's release lines cannot be known\n`);
+    }
+  }
+  if (changed) fs.writeFileSync(prdFile, JSON.stringify(prd, null, 2));
+})().catch((e) => { process.stderr.write(`[plan] could not write plans: ${(e && e.stack) || e}\n`); process.exit(0); });