@yeison.restrepo.r/code-conductor 1.52.3 → 1.52.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -483,7 +483,7 @@ The backup and temp rules keep the installer's own backups and crash-stranded te
483
483
  | `systemMessage` | `default` | yes, for example Guard 2's overwrite prompt | no: the warning is lost |
484
484
  - Agent definitions provided by plugins are not searched.
485
485
  - `resume` (`[FEAT-055]`) needs approvals that recorded their commit: a run approved before it is refused `ORCH_RESUME_UNANCHORED` and still needs `end`, then `start`, and a Build task entry without a stored SNAP is redone.
486
- - Unattended mode (`[FEAT-054]`) binds the agents, not the orchestrator session: the run file is inside the orchestrator's write surface, so a hand edit could set `unattended` just as it could forge an approval, and Guard 6 does not stop it. Its deterministic plan check covers only the orchestrator write surface, any `Files` entry outside printable ASCII (`[BUG-086]`) and the control-plane files, including those that run code outside the run and any `CLAUDE.md`, `CLAUDE.local.md` or npm manifest at any depth (`[BUG-080]`, `[BUG-081]`, `[BUG-082]`); every other judgement is the delegated reviewer's.
486
+ - Unattended mode (`[FEAT-054]`) binds the agents, not the orchestrator session: the run file is inside the orchestrator's write surface, so a hand edit could set `unattended` just as it could forge an approval, and Guard 6 does not stop it. Its deterministic plan check covers only the orchestrator write surface, any `Files` entry outside printable ASCII (`[BUG-086]`) and the control-plane files, including those that run code outside the run (git hooks and config-read hook runners, editor and container auto-run files, package-manager and build-system files, CI pipelines) and any `CLAUDE.md`, `CLAUDE.local.md` or package-manager or build-system manifest at any depth (`[BUG-080]`, `[BUG-081]`, `[BUG-082]`, `[BUG-085]`); every other judgement is the delegated reviewer's.
487
487
 
488
488
  The five role agent definitions it dispatches ship from `1.37.0`; their limits are the next item.
489
489
  - **The role agents (`1.37.0`) are bounded by their tool masks, and Guard 7 bounds one thing beneath them: the shell.**
@@ -496,17 +496,13 @@ The backup and temp rules keep the installer's own backups and crash-stranded te
496
496
  - **`[BUG-057]`, open:** `.claude/memory/project.md` is append-only and the phase commands instruct a full read of it, which collides with Guard 1's 150-line read limit once the file grows; on a long-lived project the read cost rises with project age. Until it is fixed, prune or archive old checkpoint sections by hand when the file gets large.
497
497
  - **`[BUG-058]`, open:** the test suite does not pass on a Windows checkout (CRLF checkout of `.mjs` files, `--import` given a bare path, symlink and `chmod` fixtures, `spawnSync('npm')` without a shell), and CI has no Windows leg to show it. Until it is fixed, develop against the suite on Linux/macOS or WSL; the shipped product itself is unaffected.
498
498
  - **`[BUG-059]`, open:** the test helper that fakes the `gh` CLI is POSIX-only, so on a Windows machine where the suites load, tests can reach a real, logged-in `gh` and perform live GitHub writes. Until it is fixed, do not run `npm test` on Windows while authenticated to `gh`, or log out (`gh auth logout`) first.
499
- - **`[BUG-069]`, open:** with `--opencode`, the installer overwrites an existing `.opencode/plugin/conductor-guard.js` without a backup, unlike the merged files it backs up. Until it is fixed, copy an edited plugin aside before re-running the installer with `--opencode`.
500
499
  - **`[BUG-070]`, open:** the GitHub Actions workflows pin `actions/checkout` and `actions/setup-node` by tag rather than by commit SHA, so a moved tag would change what runs; the risk is low, since both actions are first-party and the records guard runs with a read-only token and no secrets. Until it is fixed, a fork can pin both actions to full commit SHAs in its own workflows.
501
500
  - **`[BUG-071]`, open:** the OpenCode guard plugin forwards only `command` from OpenCode's `bash` call, so if that tool runs a command in another working directory, Guard 3 evaluates it as if it ran in the project root. Until it is fixed, treat Guard 3 under OpenCode as best-effort for commands that set their own working directory.
502
501
  - **`[BUG-072]`, open:** the reserved list for recorded spec and plan folders misses root dot-directories outside `.claude` (such as `.husky`, `.vscode`, `.devcontainer`) and `bin`, `lib`, `tools`, so a `- Specs:` or `- Plans:` line in the project `CLAUDE.md` can make one of them the spec or plan agent's Guard 5 write scope. Until it is fixed, review any `- Specs:` or `- Plans:` line in the project `CLAUDE.md` and keep it pointing at a documentation folder.
503
502
  - **`[BUG-074]`, open:** the `/cc-orchestrate` role definitions disagree on when a task's tests are done: `code` may hand back `build_executed` on a red suite, `plan` requires each task to end green, and `qa` passes only on exit 0, so one suite result gates differently depending on the role. Until it is fixed, read a `build_executed` hand-back's reported suite exit code yourself and treat a non-zero one as not done.
504
503
  - **`[BUG-075]`, open:** `scripts/orchestrate.mjs` validates only the shape of a role hand-back, so it accepts a `build_executed` whose report says the suite failed or whose `ops.f` lists out-of-scope paths, lets `end` close a run with no `verify_pass`, and stamps an approval with the global `git config user.name`; Guards 5 and 7 still block the out-of-scope writes themselves. Until it is fixed, check that a run reached `verify_pass` before trusting its record, and do not read the approval name as proof of who approved.
505
- - **`[BUG-077]`, open:** `scripts/orchestrate.mjs` lets `approve spec <path> <sha256>` accept any file path relative to the run root, without checking that it is the spec the `spec` role handed back or that it sits under the run's `docs.specs` folder, so approving the wrong path makes the post-approval hash check in `install` protect that file while later edits to the real spec go undetected. Until it is fixed, confirm that the path you approve is the spec the `spec` role handed back, under the run's recorded specs folder.
506
504
  - **`[BUG-078]`, open:** `scripts/orchestrate.mjs` builds a fix round's write scope with the approved plan included, so Guard 5 lets the fix-round `code` agent write to the plan and only the brief's instruction stops it; any change other than checkbox ticks still halts the run with `ORCH_APPROVED_DOC_CHANGED` on the next `install audit` or fix round, and ticks do not affect `tasks.done`. Until it is fixed, check after a fix round that the approved plan's checkboxes are unchanged.
507
505
  - **`[BUG-079]`, open:** `scripts/orchestrate.mjs` stores every non-security hand-back's full SNAP in `.claude/memory/orchestrator-run.json` with a 64 KiB cap per SNAP but no cap on the total, so a plan of roughly 80 or more tasks with maximally sized hand-backs can push the run file past the hook's 10 MiB read cap, after which `readRunFile` returns null and Guard 6 downgrades from deny to warn for the rest of the run. Until it is fixed, keep orchestrated plans well under 80 tasks, or split a larger item into several runs.
508
- - **`[BUG-083]`, open:** the `publish` job in `.github/workflows/publish.yml` avoids an npm cache only by omitting `cache:` from `actions/setup-node`, which v5+ overrides when `package.json` declares a `packageManager` (or `devEngines.packageManager`) field; no such field exists today, so there is no current impact, but adding one would let the job holding `id-token: write` restore a cache the `verify` job populated. Until it is fixed, do not add a `packageManager` or `devEngines.packageManager` field to `package.json`, or set `package-manager-cache: false` on the `publish` job's `setup-node` step in a fork.
509
- - **`[BUG-085]`, open:** the unattended plan check's `CONTROL_PLANE` list in `scripts/orchestrate.mjs` does not yet cover config-read hook runners, editor and container auto-run configuration, other package managers' files or other CI systems, so in an `--unattended` run a plan approved only by the delegated review can write files that run code outside the run. Until it is fixed, check an `--unattended` run's diff for changes to such files before committing, opening the project in an editor or container, installing dependencies or pushing.
510
506
  - **The `P7` false positive** described under [Guard 3, and what it learned](#guard-3-and-what-it-learned) is still live.
511
507
  - **A re-run against an untouched `project.md` prints a recovery hint it cannot prove is needed.** If you install, never write anything into `.claude/memory/project.md`, and install again, you get a line suggesting the file may have been overwritten by a pre-`1.30.0` re-run. It was not; it equals the stub because it was seeded and never edited. The check compares content and **cannot distinguish "seeded and untouched" from "clobbered"**, which is why the wording is hedged to "may have been" rather than "was". This residual is named and accepted in [`BUG-039`'s spec at `:129`](docs/superpowers/specs/2026-09-27-bug039-installer-host-owned-state-design.md), where the alternative (restoring from the host's own git history) was rejected as writing host files out of the host's history with new failure modes. A **fresh** install is silent, which the Quickstart shows.
512
508
  - **Three open dossiers**, which are the evidence-collection pipeline working rather than a backlog: a session denial tally, one for interleaved-artifact reports, and an intermittent commit-hook hang in the `snap-build` suite. A dossier holds specimens until a mechanism is characterized by probe; an id is minted only when the written condition is met. `[BUG-047]` is what that pipeline produces when it completes: an out-of-scope note, then a dossier, then four specimens across four sessions, then a mint, then a release.
@@ -31,13 +31,13 @@ const OPENCODE_DIR = '.opencode';
31
31
  // block and would otherwise be invisible (BUG-049). A backup outside `root` (a
32
32
  // symlinked target resolved into a dotfiles checkout) prints absolute, and only a
33
33
  // backup inside a --project root claims the ignore rule covers it.
34
- function backupReporter(report, { root, rootLabel, file, ignoredByDesign }) {
34
+ function backupReporter(report, { root, rootLabel, file, ignoredByDesign, action = 'merging' }) {
35
35
  return (backupPath) => {
36
36
  const rel = relative(root, backupPath);
37
37
  const inside = rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
38
38
  const shown = inside ? rootLabel + rel.split(sep).join('/') : backupPath;
39
39
  const suffix = inside && ignoredByDesign ? ' (git-ignored by design)' : '';
40
- report(`code-conductor: backed up ${rootLabel}${file} to ${shown} before merging${suffix}`);
40
+ report(`code-conductor: backed up ${rootLabel}${file} to ${shown} before ${action}${suffix}`);
41
41
  };
42
42
  }
43
43
  const toStdout = (m) => process.stdout.write(`${m}\n`);
@@ -234,10 +234,28 @@ function mergeFlowStatus(templateClaude, target, home, report) {
234
234
  if (FLOW_STATUS_REPORT[status]) report(FLOW_STATUS_REPORT[status](previous));
235
235
  }
236
236
 
237
+ const OPENCODE_PLUGIN = '.opencode/plugin/conductor-guard.js';
238
+ // A plugin is "in place" after these statuses; every other one leaves the host's file (or nothing) there.
239
+ const PLUGIN_IN_PLACE = new Set(['created', 'merged', 'unchanged']);
240
+
241
+ // The plugin is a managed asset, so the shipped bytes win. Going through mergeFileInto
242
+ // still backs up a copy the host edited before replacing it (BUG-069).
243
+ const replaceWithTemplate = (templateText, hostText) => ({ text: templateText, changed: hostText !== templateText });
244
+
245
+ function installOpencodePlugin(templateRoot, cwd, { warn, report }) {
246
+ const parts = OPENCODE_PLUGIN.split('/');
247
+ mkdirSync(join(cwd, ...parts.slice(0, -1)), { recursive: true });
248
+ const status = mergeFileInto(join(templateRoot, ...parts), join(cwd, ...parts), replaceWithTemplate, {
249
+ warn,
250
+ onBackup: backupReporter(report, { root: cwd, rootLabel: '', file: OPENCODE_PLUGIN, ignoredByDesign: true, action: 'replacing it' }),
251
+ });
252
+ if (PLUGIN_IN_PLACE.has(status)) report(`code-conductor: installed the OpenCode guard plugin at ${OPENCODE_PLUGIN}`);
253
+ }
254
+
237
255
  // `home` is where the user-level settings.json lives, consulted only by the flow status
238
256
  // line rule. A caller that passes none gets the project-level check alone.
239
- // `opencode` opts into the OpenCode guard plugin (FEAT-048); without it the template's
240
- // .opencode/ entry is skipped, so a Claude Code install is unchanged byte for byte.
257
+ // `opencode` opts into the OpenCode guard plugin (FEAT-048); without it the plugin
258
+ // is not installed, so a Claude Code install is unchanged byte for byte.
241
259
  export function deployProject(assetRoot, cwd, { warn = toStderr, report = toStdout, home = null, opencode = false } = {}) {
242
260
  const emit = warn;
243
261
  // Also run by the CLI's pre-flight; kept here for direct callers.
@@ -259,11 +277,10 @@ export function deployProject(assetRoot, cwd, { warn = toStderr, report = toStdo
259
277
  const templateClaude = join(templateRoot, '.claude');
260
278
  cpSync(templateClaude, target, { ...CP_OPTS, filter: hostOwnedFilter(templateClaude, PROJECT_HOST_OWNED) });
261
279
  for (const name of readdirSync(templateRoot)) {
262
- if (name === '.claude' || MERGED_ROOT_FILES.has(name)) continue;
263
- if (name === OPENCODE_DIR && !opencode) continue;
280
+ if (name === '.claude' || name === OPENCODE_DIR || MERGED_ROOT_FILES.has(name)) continue;
264
281
  cpSync(join(templateRoot, name), join(cwd, name), CP_OPTS);
265
- if (name === OPENCODE_DIR) report(`code-conductor: installed the OpenCode guard plugin at ${OPENCODE_DIR}/plugin/conductor-guard.js`);
266
282
  }
283
+ if (opencode) installOpencodePlugin(templateRoot, cwd, { warn: emit, report });
267
284
  for (const [source, { target: dest, merge }] of MERGED_ROOT_FILES) {
268
285
  mergeFileInto(join(templateRoot, source), join(cwd, dest), merge, {
269
286
  warn: emit,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yeison.restrepo.r/code-conductor",
3
- "version": "1.52.3",
3
+ "version": "1.52.5",
4
4
  "description": "A governance layer for Claude Code sessions: hooks that check an agent's commands before they run, a spec-first workflow, and project memory the next session reads.",
5
5
  "keywords": [
6
6
  "agentic-development",
@@ -74,6 +74,7 @@ A halt stops the run (D12, amended by FEAT-055). Recovery is `node "$S/orchestra
74
74
  - **The loop must be closed.** On `ORCH_REVIEW_OPEN`, a refusal that writes nothing, the role's loop has no recorded outcome: close it with its real outcome or `review <role> --close skipped:<reason>`, then show the approval again.
75
75
  - **The review must cover the document.** On `ORCH_REVIEW_DOC_MISMATCH`, a refusal that writes nothing, the loop closed `clean`, `cap` or `unchanged` over other bytes than the document you are approving, usually because it was edited after the loop: run `review <role> --close skipped:doc-changed`, then show the approval again with the skip notice and the document's new hash.
76
76
  - **The script checks the hash.** Pass the path and hash you showed to `approve`. On `ORCH_DOC_HASH_STALE`, a refusal that writes nothing, the document changed after you showed it: show it again with its new hash and wait for a new owner approval.
77
+ - **The spec must be the one handed back.** On `ORCH_SPEC_NOT_HANDED_BACK`, a refusal that writes nothing, the path you passed is not a document the spec hand-back named under the run's spec folder: show the approval again with the path from the hand-back's `ops.f` and its hash, and wait for the owner. A hand-back that names no spec there leaves nothing to approve: run `end`, then `start`.
77
78
  - **After spec:** show the owner the spec path from the hand-back, and for a bound run the snapshot path and sha256 from the start line: the owner reviews the spec against that snapshot. On approval, run `node "$S/orchestrate.mjs" approve spec <spec path> <sha256>` with the path and hash you showed.
78
79
  - **After plan:** show the owner the plan path named in the hand-back's `ops.f`. On approval, run `node "$S/orchestrate.mjs" approve plan <plan path> <sha256>` with the path and hash you showed. This writes `define_approved`, the only gate you author after `boundary_routed`.
79
80
  - **Unattended (FEAT-054).** When the start line ended with the unattended segment, show the approval as above, then run `node "$S/orchestrate.mjs" delegate <spec|plan> --check`. It prints `delegate <kind>: <doc> sha256 <hash>; source <source>`, ending `; model <alias>` in a run with role models. Dispatch a fresh `define-review` agent with the define brief below, filled from that line only; pass the model by the rule of step 2.4. The brief carries no author report, no review-loop finding, no observation line and no earlier verdict. Write its report verbatim with the Write tool to `.conductor/delegate/<kind>.md`, then run `node "$S/orchestrate.mjs" delegate <kind> <doc> <hash>` with the path and hash the `--check` line printed. On `<kind> approved by delegated review: …`, the approval is recorded with `define-review` as approver: continue. On `owner approval required: …`, show the reviewer's findings and wait for an owner message, exactly as in attended mode; the owner approves with `approve`. `delegate` runs once per approval: a second attempt refuses `ORCH_DELEGATED_ONCE`. On any refusal of `delegate` (`ORCH_NOT_UNATTENDED`, `ORCH_REVIEW_OPEN`, `ORCH_REVIEW_DOC_MISMATCH`, `ORCH_DOC_HASH_STALE`, a missing report, a document the hand-back does not name), wait for the owner as well; never retry another way. An owner message during an unattended run is the owner's word, as always. Known limit: the run file is inside your write surface, so a hand edit could set `unattended` just as it could forge an approval; Guard 6 does not stop it, and nothing in this command may do it.
@@ -24,6 +24,7 @@ export const WRITE_SURFACE = [RUN_FILE, ENVELOPE_FILE, '.claude/memory/session-s
24
24
  // as WRITE_SURFACE; a trailing `/**` protects the whole directory, so a file added to it is covered too.
25
25
  // Owner decision (BUG-081): also the files that run code outside the run, after it ends.
26
26
  // Owner decision (BUG-082): a CLAUDE.md or an npm manifest also reaches it at any depth, by its last segment (CONTROL_PLANE_NAMES).
27
+ // Owner decision (BUG-085): also the config-read hook runners, editor and container auto-run files, other package managers, build systems and CI systems.
27
28
  export const CONTROL_PLANE = [
28
29
  '.claude/hooks/**', 'project-template/.claude/hooks/**',
29
30
  '.opencode/plugin/**', 'project-template/.opencode/plugin/**',
@@ -42,8 +43,55 @@ export const CONTROL_PLANE = [
42
43
  '.claude/flow-status.mjs', 'project-template/.claude/flow-status.mjs',
43
44
  '.github/workflows/**', '.github/actions/**',
44
45
  'package.json', 'package-lock.json', 'npm-shrinkwrap.json', '.npmrc',
46
+ // BUG-085: config-read git hook runners.
47
+ '.pre-commit-config.yaml',
48
+ 'lefthook.yml', 'lefthook.yaml', 'lefthook.json', 'lefthook.toml', '.lefthook.yml', '.lefthook.yaml', '.lefthook.json', '.lefthook.toml',
49
+ 'lefthook-local.yml', 'lefthook-local.yaml', 'lefthook-local.json', 'lefthook-local.toml',
50
+ '.lefthook-local.yml', '.lefthook-local.yaml', '.lefthook-local.json', '.lefthook-local.toml',
51
+ '.lefthook/**', '.lefthook-local/**', '.overcommit.yml',
52
+ '.simple-git-hooks.json', '.simple-git-hooks.js', '.simple-git-hooks.cjs', '.simple-git-hooks.mjs',
53
+ 'simple-git-hooks.json', 'simple-git-hooks.js', 'simple-git-hooks.cjs', 'simple-git-hooks.mjs',
54
+ '.huskyrc', '.huskyrc.json', '.huskyrc.yaml', '.huskyrc.yml', '.huskyrc.js', '.huskyrc.cjs', 'husky.config.js', 'husky.config.cjs',
55
+ '.lintstagedrc', '.lintstagedrc.json', '.lintstagedrc.yaml', '.lintstagedrc.yml', '.lintstagedrc.js', '.lintstagedrc.cjs', '.lintstagedrc.mjs',
56
+ 'lint-staged.config.js', 'lint-staged.config.cjs', 'lint-staged.config.mjs',
57
+ // BUG-085: editor and container auto-run configuration.
58
+ '.vscode/**', '.idea/**', '.zed/**', '.devcontainer/**', '.devcontainer.json', '.gitpod.yml',
59
+ // BUG-085: other package managers' and build systems' manifests, lockfiles, config and build files.
60
+ '.yarnrc', '.yarnrc.yml', 'yarn.lock', '.yarn/**', '.pnp.cjs', '.pnp.loader.mjs',
61
+ 'pnpm-workspace.yaml', 'pnpm-lock.yaml', '.pnpmfile.cjs',
62
+ 'bunfig.toml', 'bun.lock', 'bun.lockb',
63
+ 'deno.json', 'deno.jsonc', 'deno.lock',
64
+ 'pyproject.toml', 'setup.py', 'setup.cfg', 'requirements.txt', 'pipfile', 'pipfile.lock',
65
+ 'poetry.lock', 'poetry.toml', 'uv.lock', 'uv.toml', 'pdm.lock',
66
+ 'gemfile', 'gemfile.lock', 'gems.rb', 'gems.locked', '.bundle/**',
67
+ 'composer.json', 'composer.lock',
68
+ 'cargo.toml', 'cargo.lock', '.cargo/**', 'rust-toolchain', 'rust-toolchain.toml', 'build.rs',
69
+ 'go.mod', 'go.work',
70
+ '.mvn/**', 'mvnw', 'mvnw.cmd', 'pom.xml', 'gradle/**', 'gradlew', 'gradlew.bat', 'gradle.properties',
71
+ 'build.gradle', 'build.gradle.kts', 'settings.gradle', 'settings.gradle.kts',
72
+ 'nuget.config', 'packages.lock.json', 'global.json', 'directory.build.props', 'directory.build.targets', 'directory.packages.props',
73
+ // BUG-085: other CI systems' pipeline files.
74
+ '.gitlab-ci.yml', '.circleci/**', 'azure-pipelines.yml', 'azure-pipelines.yaml', '.travis.yml', 'jenkinsfile',
75
+ 'bitbucket-pipelines.yml', '.buildkite/**', '.drone.yml', '.woodpecker.yml', '.woodpecker.yaml', '.woodpecker/**',
76
+ 'appveyor.yml', '.appveyor.yml', '.gitea/workflows/**', '.forgejo/workflows/**', '.cirrus.yml', '.cirrus.star', '.semaphore/**',
77
+ ];
78
+ // Owner decision (BUG-085): the other package managers' and build systems' fixed files also reach it at any depth, like npm's.
79
+ export const CONTROL_PLANE_NAMES = [
80
+ 'claude.md', 'claude.local.md', 'package.json', 'package-lock.json', 'npm-shrinkwrap.json', '.npmrc',
81
+ '.yarnrc', '.yarnrc.yml', 'yarn.lock', '.pnp.cjs', '.pnp.loader.mjs',
82
+ 'pnpm-workspace.yaml', 'pnpm-lock.yaml', '.pnpmfile.cjs',
83
+ 'bunfig.toml', 'bun.lock', 'bun.lockb',
84
+ 'deno.json', 'deno.jsonc', 'deno.lock',
85
+ 'pyproject.toml', 'setup.py', 'setup.cfg', 'requirements.txt', 'pipfile', 'pipfile.lock',
86
+ 'poetry.lock', 'poetry.toml', 'uv.lock', 'uv.toml', 'pdm.lock',
87
+ 'gemfile', 'gemfile.lock', 'gems.rb', 'gems.locked',
88
+ 'composer.json', 'composer.lock',
89
+ 'cargo.toml', 'cargo.lock', 'rust-toolchain', 'rust-toolchain.toml', 'build.rs',
90
+ 'go.mod', 'go.work',
91
+ 'mvnw', 'mvnw.cmd', 'pom.xml', 'gradlew', 'gradlew.bat', 'gradle.properties',
92
+ 'build.gradle', 'build.gradle.kts', 'settings.gradle', 'settings.gradle.kts',
93
+ 'nuget.config', 'packages.lock.json', 'global.json', 'directory.build.props', 'directory.build.targets', 'directory.packages.props',
45
94
  ];
46
- export const CONTROL_PLANE_NAMES = ['claude.md', 'claude.local.md', 'package.json', 'package-lock.json', 'npm-shrinkwrap.json', '.npmrc'];
47
95
  // Where /cc-orchestrate writes each agent's final message for `handback` to read: inside
48
96
  // the surface, and cleared with the run so file names never collide across runs.
49
97
  export const HANDBACK_DIR = '.conductor/handback';
@@ -944,6 +992,13 @@ async function handback(root, sessionId, role, bytes) {
944
992
  return `${role} handed back ${env.ops.gate}${note}`;
945
993
  }
946
994
 
995
+ // BUG-077: the owner's spec approval binds a document the spec hand-back named, as delegate's does.
996
+ function checkSpecHandedBack(run, rel) {
997
+ const named = handedBackDocs(run, 'spec');
998
+ if (named.includes(rel)) return;
999
+ throw new Refusal(`ORCH_SPEC_NOT_HANDED_BACK: approve spec: ${rel} is not a document the spec hand-back names under ${docsFolder(run, 'spec')} (${named.length ? named.join(', ') : 'none'}); show the approval for a named document`);
1000
+ }
1001
+
947
1002
  // Two human approvals, one gate write (A4): only an approved plan writes define_approved.
948
1003
  // FEAT-055: and HEAD at that moment, so resume can tell whether history still holds it.
949
1004
  // FEAT-056: each approval binds the bytes the owner was shown; a stale hash writes nothing.
@@ -955,6 +1010,7 @@ function approve(root, sessionId, what, rel, shown) {
955
1010
  if (!RECORD_KINDS.includes(what)) throw new Refusal(APPROVE_USAGE);
956
1011
  if (!SHA256_HEX.test(shown ?? '')) throw new Refusal(APPROVE_USAGE);
957
1012
  const content = readDoc(root, rel, APPROVE_USAGE);
1013
+ if (what === 'spec') checkSpecHandedBack(run, rel);
958
1014
  const sha256 = documentHash(what, content);
959
1015
  checkLoopClosed(run, what, rel, sha256);
960
1016
  if (sha256 !== shown.toLowerCase()) {
@@ -1017,11 +1073,16 @@ const snapFiles = (entry) => { try { const f = JSON.parse(entry?.snap).ops.f; re
1017
1073
  // The role's pinned docs folder (FEAT-047): its scope glob without the trailing **, or '' when none was pinned.
1018
1074
  const docsFolder = (run, kind) => String(run.docs?.scopes?.[kind]?.[0] ?? '').replace(/\*\*$/, '');
1019
1075
 
1020
- // The document the Define role named in its hand-back, inside its pinned folder: the brief's, never the orchestrator's pick.
1021
- function handedBackDoc(run, kind) {
1076
+ // The documents the Define role named in its hand-back, inside its pinned folder: the brief's, never the orchestrator's pick.
1077
+ function handedBackDocs(run, kind) {
1022
1078
  const folder = docsFolder(run, kind);
1023
- const docs = snapFiles(run.handbacks.findLast((h) => h.role === kind)).filter((f) => /:[CM]$/.test(f)).map((f) => f.slice(0, -2))
1079
+ return snapFiles(run.handbacks.findLast((h) => h.role === kind)).filter((f) => /:[CM]$/.test(f)).map((f) => f.slice(0, -2))
1024
1080
  .filter((p) => folder !== '' && p.startsWith(folder) && p.endsWith('.md'));
1081
+ }
1082
+
1083
+ function handedBackDoc(run, kind) {
1084
+ const folder = docsFolder(run, kind);
1085
+ const docs = handedBackDocs(run, kind);
1025
1086
  if (docs.length !== 1) throw new Refusal(`delegate ${kind}: the ${kind} hand-back names ${docs.length} document(s) under ${folder}; show the approval and wait for the owner`);
1026
1087
  return docs[0];
1027
1088
  }