@yeison.restrepo.r/code-conductor 1.52.4 → 1.52.6
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
|
@@ -496,16 +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
|
-
- **`[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
503
|
- **`[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
504
|
- **`[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-
|
|
505
|
+
- **`[BUG-087]`, open:** with `--opencode`, the installer writes `.opencode/plugin/conductor-guard.js` through a path that follows symlinks, so a checkout that ships that file as a symlink makes the install overwrite the link's target, which can be outside the project, with the shipped plugin bytes; a timestamped backup is written next to the target. Until it is fixed, check that `.opencode/plugin/conductor-guard.js` is not a symlink (or remove it) before running `code-conductor --opencode` in a checkout you did not author, and restore from the backup if a target was overwritten.
|
|
509
506
|
- **The `P7` false positive** described under [Guard 3, and what it learned](#guard-3-and-what-it-learned) is still live.
|
|
510
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.
|
|
511
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.
|
package/lib/installer/deploy.mjs
CHANGED
|
@@ -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
|
|
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
|
|
240
|
-
//
|
|
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
|
+
"version": "1.52.6",
|
|
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",
|
|
@@ -34,6 +34,8 @@ A halt stops the run (D12, amended by FEAT-055). Recovery is `node "$S/orchestra
|
|
|
34
34
|
|
|
35
35
|
`install code|audit|qa` halts `ORCH_APPROVED_DOC_CHANGED` when the approved spec or plan changed after its approval (a ticked plan checkbox is not a change), and `ORCH_APPROVAL_UNHASHED` on a run whose approvals were recorded before FEAT-056. Recovery for both is `end`, then `start`. `install security` halts the same two codes.
|
|
36
36
|
|
|
37
|
+
`handback <role>` halts `ORCH_HANDBACK_SCOPE_MISMATCH` when the hand-back's `ops.scope` is not the scope `install` wrote for that position, entry for entry and in the same order, or when `audit`, `security` or `qa`, which are installed with no scope, hand back one; and `ORCH_HANDBACK_OUT_OF_SCOPE` when a path in `ops.f` is absolute, has an empty, `.` or `..` segment, or lies outside that scope. The script recomputes the scope from the plan and the run's pinned folders; it never reads it back from `.claude/memory/band-envelope.json`. Neither halt records the hand-back. For both, name the hand-back file you passed: it is what the owner reads next. Recovery is `resume` or `end`, then `start`.
|
|
38
|
+
|
|
37
39
|
`handback audit` halts `ORCH_VERDICT_MISSING`, `ORCH_VERDICT_INVALID` or `ORCH_VERDICT_INCONSISTENT` when the audit report's `VERDICT:` line is absent, malformed, misplaced or contradicts its findings; `ORCH_AUDIT_RETURN` when the audit returned the change and the run has no fix rounds left; `ORCH_AUDIT_ESCALATE` when the audit escalated a decision to the owner, at any round; and `ORCH_FIX_SCOPE_UNAPPROVED` when a blocker or major finding of a returned audit names a file outside the approved plan's task files, or the approved spec or plan. For those six, also name `.conductor/handback/audit-<round>.txt`: its findings are what the owner reads next. `handback qa` halts `ORCH_GATE_WITHHELD` when the run's last audit entry carries no `VERDICT: APPROVE`. Recovery for all seven is `end`, then `start`.
|
|
38
40
|
|
|
39
41
|
`install security` and `handback security` halt `ORCH_VERDICT_MISSING`, `ORCH_VERDICT_INVALID` or `ORCH_VERDICT_INCONSISTENT` as `handback audit` does, because the same parser reads the security report's `VERDICT:` line (a failed scan without `VERDICT: ESCALATE` is also `ORCH_VERDICT_INCONSISTENT`); `ORCH_SECURITY_REPORT_MISSING` / `ORCH_SECURITY_REPORT_INVALID` (no, malformed or misplaced `SCANS:` line or owner-only block, a malformed finding line, a severity that does not match the run's threshold, a dependency finding outside the run's lockfile or filed in the wrong part, or a report that contradicts the run's `dependency`); `ORCH_SECURITY_REPORT_INCOMPLETE` (the script's own re-run of the local scan found a status or a line the report lacks or files in the wrong part); `ORCH_SECURITY_SCAN_FAILED` (a scan did not complete, the base commit does not track the scanner, or its scanner predates FEAT-059); `ORCH_SECURITY_BLOCKED` (`VERDICT: RETURN`: a finding the change introduces at or above the run's threshold); and `ORCH_SECURITY_ESCALATE` (`VERDICT: ESCALATE` with every scan run: a decision only the owner takes). For those, also name `.conductor/handback/security.txt`: its findings are what the owner reads next; never quote its owner-only block. `handback qa` also halts `ORCH_GATE_WITHHELD` when the last security verdict is not `VERDICT: APPROVE` or is absent. Recovery is `end`, then `start`. After updating an installed project, commit the updated `.claude/scripts/security-scan.mjs` before the next `start`: a base commit that still holds the 1.48.0 scanner halts `ORCH_SECURITY_SCAN_FAILED` and names that recovery.
|
|
@@ -42,11 +44,13 @@ A halt stops the run (D12, amended by FEAT-055). Recovery is `node "$S/orchestra
|
|
|
42
44
|
|
|
43
45
|
**Resume (FEAT-055).** Offer `resume` next to `end` when the run recorded the spec approval; run it only on the owner's word, as `end`. `node "$S/orchestrate.mjs" resume` takes no argument. It keeps both approvals when each approved document still hashes as approved and HEAD descends from the commit each approval recorded, then keeps the Build task hand-backs, in order, while each stored SNAP still validates and HEAD descends from its commit. Every record after the first that fails, and every Verify record (audit, fix round, security, qa), is dropped and redone. On success it prints `run <ITEM> resumed after <code> from <gate>: kept <k> record(s), dropped <d>; next: <step>`: print the run header again and continue at step 2 with the step it names (`install <role> --check`, the pause in step mode, `install <role>`, a fresh dispatch); never revive the halted agent. A refusal exits 2 and writes nothing, so the run stays halted: `ORCH_RESUME_NO_RUN` (no valid run file), `ORCH_RESUME_NOT_HALTED` (the run is live: continue with the step it names), `ORCH_NO_SESSION_ID`, `ORCH_RESUME_NO_GATE` (no spec approval), `ORCH_APPROVAL_UNHASHED` (approved before FEAT-056), `ORCH_RESUME_UNANCHORED` (an approval records no commit, or git cannot check it), `ORCH_APPROVED_DOC_CHANGED` (an approved document changed; a ticked plan checkbox is not a change) and `ORCH_RESUME_HISTORY_REWRITTEN` (HEAD no longer descends from an approval's commit). After any of them but `ORCH_RESUME_NOT_HALTED`, recovery is `end`, then `start`.
|
|
44
46
|
|
|
47
|
+
**Abandon (BUG-075).** `end` ends a live run only after `qa` records `verify_pass`; a halted run, an invalid run file and a missing one need no flag. On a live run with no `verify_pass`, `end` refuses with `ORCH_END_UNVERIFIED`, exit 2, and removes nothing. To drop such a run on the owner's word only (after `ORCH_RUN_ACTIVE`, after a declined pause, or to restart), run `node "$S/orchestrate.mjs" end --abandon`. Its first line reads `run <ITEM> abandoned at <gate> before verify_pass` and the record follows: report that line, and never present the run as finished. Never pass `--abandon` on your own.
|
|
48
|
+
|
|
45
49
|
## Steps
|
|
46
50
|
|
|
47
51
|
1. **Start.** Run `node "$S/orchestrate.mjs" start $ARGUMENTS`. It resolves the run's test command and its spec and plan folders before it writes anything, and its stdout ends with `docs: specs <dir>, plans <dir> (<source>)[; group <group>]; test command: <command>; audit rounds: <n>; security: threshold <level>, dependency scan <command | not covered for <reason> | disabled (--no-dependency-audit)>`. With a `- Role models:` line in the project `CLAUDE.md`, it then ends with `; role models: spec=<m>, plan=<m>, code=<m>, audit=<m>, security=<m>, qa=<m>, define-review=<m>`, each `<m>` one of `opus`, `sonnet`, `haiku` or `inherit`, followed by `; note: audit and code share <m>` when both name the same model (FEAT-053).
|
|
48
52
|
- If stdout names a replaced stale run, report its item and start time.
|
|
49
|
-
- On `ORCH_RUN_ACTIVE`, report it, offer `end
|
|
53
|
+
- On `ORCH_RUN_ACTIVE`, report it, offer `end --abandon` (see "Abandon" under "On any halt"), and stop.
|
|
50
54
|
- On `ORCH_TEST_COMMAND_UNRESOLVED` or `ORCH_TEST_COMMAND_UNSAFE`, report it and stop. No run file was written, so there is nothing to `end`. The owner adds a `test` script to `package.json`, or removes the chaining from the command it names, before a fresh `start`.
|
|
51
55
|
- On `ORCH_SECURITY_COMMAND_UNSAFE`, report it and stop in the same way: a recorded security command carries chaining, and no run file was written.
|
|
52
56
|
- On `ORCH_DOC_LOCATION_INVALID`, report it and stop. No run file was written. The owner fixes the named `- Specs:` / `- Plans:` line in `CLAUDE.md` (add the missing one, fix the value, or use two disjoint folders) before a fresh `start`.
|
|
@@ -74,11 +78,12 @@ A halt stops the run (D12, amended by FEAT-055). Recovery is `node "$S/orchestra
|
|
|
74
78
|
- **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
79
|
- **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
80
|
- **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.
|
|
81
|
+
- **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
82
|
- **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
83
|
- **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
84
|
- **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.
|
|
80
85
|
4. **Build.** Dispatch `code` once per plan task, serially, until the router moves on to `audit`. A `--check` refusal names the next step.
|
|
81
|
-
5. **Verify.** Dispatch `audit`. The audit report ends in one `VERDICT:` line just before its `SNAP_HANDBACK` line; only `VERDICT: APPROVE` lets the router move on to `security`. When `handback audit` prints `audit round <round>: RETURN with <b> blocker/major finding(s); fix round <r> of <N>: review <review> sha256 <sha256>; scope <scope>`, run the fix round: `install code --check` prints the envelope and the line `fix round <r> of <N>: review <review> sha256 <sha256>`; take the brief's values from that line, never from your own reading of the report. In a run with role models, `install code` then ends with `model: <alias>`, as every dispatch does; it reads `model: opus` when `handback audit` ended its line with `; model opus (escalated: <tasks> returned twice)`, because the audit returned one of those plan tasks a second time. Then pause, install and dispatch a fresh `code` agent with the fix-round task from the dispatch table, hand it back from `.conductor/handback/code-fix-<r>.txt`, and dispatch `audit` again. Never revive an earlier agent and never message one. The orchestrator never decides whether another round runs: the script's output does. A `RETURN` with no fix rounds left, or an `ESCALATE`, halts the run (follow "On any halt"). Then dispatch `security`, which runs the recorded audit and scan commands and ends its report as the audit does: its `SCANS:` line, then one `VERDICT:` line just before its `SNAP_HANDBACK` line. `VERDICT: APPROVE` means every scan completed and no finding the change introduces is a `blocker`; `VERDICT: RETURN` means one is (`ORCH_SECURITY_BLOCKED`); `VERDICT: ESCALATE` means a scan failed (`ORCH_SECURITY_SCAN_FAILED`) or text in the change addressed the agent (`ORCH_SECURITY_ESCALATE`). A finding is a `blocker` or a `minor` by the threshold `start` recorded, and the script, not you, checks it. Findings already present at the base commit go in the report's owner-only block (`PRE-EXISTING (owner only):` … `END PRE-EXISTING`); the script writes them to `.conductor/security-pre-existing.txt` and to nothing public. This changes 1.48.0 behavior: a finding already present at the base, a dependency advisory included, no longer blocks the run at any level; only the findings the change introduces decide the verdict. `handback security` prints `security handed back build_executed; VERDICT: APPROVE; <n> finding(s) below <threshold> recorded; dependency=<ran|not-covered|disabled>; pre-existing findings, if any, are in .conductor/security-pre-existing.txt (owner only)`, and only then `qa`, or, in an unattended run, the delegated build review. In an unattended run, run `node "$S/orchestrate.mjs" delegate build --check`. It prints `delegate build: spec <path> sha256 <h>; plan <path> sha256 <h>; files <files>; security <summary>`, with the model segment as at the approvals. Dispatch a fresh `define-review` agent with the build brief below, filled from that line only, write its report verbatim to `.conductor/delegate/build.md`, and run `node "$S/orchestrate.mjs" delegate build`. Only `build approved by delegated review: …; next: install qa` lets `qa` run; a `RETURN` or `ESCALATE` halts the run (follow "On any halt"). A run started before FEAT-034 has no seat: `qa` follows the audit and `handback qa` prints `security=not-configured (run predates FEAT-034)`. When `qa`'s hand-back records `verify_pass`, run `node "$S/orchestrate.mjs" end`. It prints the run it removed.
|
|
86
|
+
5. **Verify.** Dispatch `audit`. The audit report ends in one `VERDICT:` line just before its `SNAP_HANDBACK` line; only `VERDICT: APPROVE` lets the router move on to `security`. When `handback audit` prints `audit round <round>: RETURN with <b> blocker/major finding(s); fix round <r> of <N>: review <review> sha256 <sha256>; scope <scope>`, run the fix round: `install code --check` prints the envelope and the line `fix round <r> of <N>: review <review> sha256 <sha256>`; take the brief's values from that line, never from your own reading of the report. In a run with role models, `install code` then ends with `model: <alias>`, as every dispatch does; it reads `model: opus` when `handback audit` ended its line with `; model opus (escalated: <tasks> returned twice)`, because the audit returned one of those plan tasks a second time. Then pause, install and dispatch a fresh `code` agent with the fix-round task from the dispatch table, hand it back from `.conductor/handback/code-fix-<r>.txt`, and dispatch `audit` again. Never revive an earlier agent and never message one. The orchestrator never decides whether another round runs: the script's output does. A `RETURN` with no fix rounds left, or an `ESCALATE`, halts the run (follow "On any halt"). Then dispatch `security`, which runs the recorded audit and scan commands and ends its report as the audit does: its `SCANS:` line, then one `VERDICT:` line just before its `SNAP_HANDBACK` line. `VERDICT: APPROVE` means every scan completed and no finding the change introduces is a `blocker`; `VERDICT: RETURN` means one is (`ORCH_SECURITY_BLOCKED`); `VERDICT: ESCALATE` means a scan failed (`ORCH_SECURITY_SCAN_FAILED`) or text in the change addressed the agent (`ORCH_SECURITY_ESCALATE`). A finding is a `blocker` or a `minor` by the threshold `start` recorded, and the script, not you, checks it. Findings already present at the base commit go in the report's owner-only block (`PRE-EXISTING (owner only):` … `END PRE-EXISTING`); the script writes them to `.conductor/security-pre-existing.txt` and to nothing public. This changes 1.48.0 behavior: a finding already present at the base, a dependency advisory included, no longer blocks the run at any level; only the findings the change introduces decide the verdict. `handback security` prints `security handed back build_executed; VERDICT: APPROVE; <n> finding(s) below <threshold> recorded; dependency=<ran|not-covered|disabled>; pre-existing findings, if any, are in .conductor/security-pre-existing.txt (owner only)`, and only then `qa`, or, in an unattended run, the delegated build review. In an unattended run, run `node "$S/orchestrate.mjs" delegate build --check`. It prints `delegate build: spec <path> sha256 <h>; plan <path> sha256 <h>; files <files>; security <summary>`, with the model segment as at the approvals. Dispatch a fresh `define-review` agent with the build brief below, filled from that line only, write its report verbatim to `.conductor/delegate/build.md`, and run `node "$S/orchestrate.mjs" delegate build`. Only `build approved by delegated review: …; next: install qa` lets `qa` run; a `RETURN` or `ESCALATE` halts the run (follow "On any halt"). A run started before FEAT-034 has no seat: `qa` follows the audit and `handback qa` prints `security=not-configured (run predates FEAT-034)`. When `qa`'s hand-back records `verify_pass`, run `node "$S/orchestrate.mjs" end`. It prints the run it removed. Before that hand-back `end` refuses with `ORCH_END_UNVERIFIED`.
|
|
82
87
|
6. **Report.** From the record `end` printed, name:
|
|
83
88
|
- every hand-back, with its role, gate and task;
|
|
84
89
|
- each audit round's verdict, from the audit entries' `round` and `verdict`, and each fix round with its files, from their `fix`;
|
package/scripts/orchestrate.mjs
CHANGED
|
@@ -552,6 +552,8 @@ function codeScope(root, run, step) {
|
|
|
552
552
|
return taskScope(task ?? { id: step.task, files: [] }, run.plan);
|
|
553
553
|
}
|
|
554
554
|
|
|
555
|
+
const docLocationHalt = (run) => new Halt('ORCH_DOC_LOCATION_UNRESOLVED', `run ${run.item} records no docs location (started before FEAT-047); run end, then start`);
|
|
556
|
+
|
|
555
557
|
function envelopeFields(run, root, step) {
|
|
556
558
|
const { tk, scope } = ROLE_ARTIFACTS[step.role];
|
|
557
559
|
const fields = {
|
|
@@ -562,9 +564,7 @@ function envelopeFields(run, root, step) {
|
|
|
562
564
|
if (step.role === 'code') fields.scope = codeScope(root, run, step);
|
|
563
565
|
else if (step.role === 'spec' || step.role === 'plan') {
|
|
564
566
|
// Read as pinned, never re-checked: the cap was enforced once, at start.
|
|
565
|
-
if (!isPlainObject(run.docs?.scopes) || !Array.isArray(run.docs.scopes[step.role]))
|
|
566
|
-
throw new Halt('ORCH_DOC_LOCATION_UNRESOLVED', `run ${run.item} records no docs location (started before FEAT-047); run end, then start`);
|
|
567
|
-
}
|
|
567
|
+
if (!isPlainObject(run.docs?.scopes) || !Array.isArray(run.docs.scopes[step.role])) throw docLocationHalt(run);
|
|
568
568
|
fields.scope = run.docs.scopes[step.role];
|
|
569
569
|
} else if (scope) fields.scope = scope;
|
|
570
570
|
// Ruling 2: ticket identity rides the spec envelope only, never its content.
|
|
@@ -969,6 +969,33 @@ async function securityHandback(root, run, gate, text) {
|
|
|
969
969
|
return `security handed back ${gate}; VERDICT: APPROVE; ${summary.total} finding(s) below ${threshold} recorded; dependency=${report.scans.dependency}; pre-existing findings, if any, are in ${OWNER_FILE} (owner only)`;
|
|
970
970
|
}
|
|
971
971
|
|
|
972
|
+
// BUG-075: recomputed as install computed it, never read back from the envelope file, which the orchestrator can write.
|
|
973
|
+
function expectedScope(root, run, role) {
|
|
974
|
+
if (role === 'code') return codeScope(root, run, nextStep(run));
|
|
975
|
+
if (role !== 'spec' && role !== 'plan') return null;
|
|
976
|
+
if (!isPlainObject(run.docs)) throw docLocationHalt(run);
|
|
977
|
+
return docScopes(run.docs)[role];
|
|
978
|
+
}
|
|
979
|
+
|
|
980
|
+
const sameList = (a, b) => Array.isArray(a) && a.length === b.length && a.every((x, i) => x === b[i]);
|
|
981
|
+
const scopeText = (scope) => (scope === null || scope === undefined ? 'none' : JSON.stringify(scope));
|
|
982
|
+
// A path that needs normalizing is not the one the scope names, so it is never normalized.
|
|
983
|
+
const unsafePath = (p) => /^[A-Za-z]:/.test(p) || p.split('/').some((seg) => seg === '' || seg === '.' || seg === '..');
|
|
984
|
+
|
|
985
|
+
// BUG-075: returned, not thrown, so resume drops the record where handback halts on it.
|
|
986
|
+
function claimHalt(env, role, expected) {
|
|
987
|
+
const claimed = env.ops.scope;
|
|
988
|
+
if (expected === null ? claimed !== undefined : !sameList(claimed, expected)) {
|
|
989
|
+
return new Halt('ORCH_HANDBACK_SCOPE_MISMATCH', `${role} was installed with scope ${scopeText(expected)}, the hand-back names ${scopeText(claimed)}`);
|
|
990
|
+
}
|
|
991
|
+
if (expected === null) return null;
|
|
992
|
+
const covers = expected.map(globToRegExp);
|
|
993
|
+
const paths = (Array.isArray(env.ops.f) ? env.ops.f : []).map((f) => String(f).replace(/:[CMD]$/, ''));
|
|
994
|
+
const outside = paths.find((p) => unsafePath(p) || !covers.some((re) => re.test(p)));
|
|
995
|
+
if (outside === undefined) return null;
|
|
996
|
+
return new Halt('ORCH_HANDBACK_OUT_OF_SCOPE', `${role} lists ${outside} in ops.f, outside its scope ${scopeText(expected)}`);
|
|
997
|
+
}
|
|
998
|
+
|
|
972
999
|
async function handback(root, sessionId, role, bytes) {
|
|
973
1000
|
const text = bytes.toString('utf8');
|
|
974
1001
|
const run = liveRun(root, sessionId);
|
|
@@ -982,6 +1009,8 @@ async function handback(root, sessionId, role, bytes) {
|
|
|
982
1009
|
if (!MAY_HAND_BACK[role].includes(env.ops.gate)) {
|
|
983
1010
|
throw new Halt('ORCH_GATE_UNEARNED', `${role} may hand back ${MAY_HAND_BACK[role].join('|')}, not ${env.ops.gate}`);
|
|
984
1011
|
}
|
|
1012
|
+
const claim = claimHalt(env, role, expectedScope(root, run, role));
|
|
1013
|
+
if (claim) throw claim;
|
|
985
1014
|
if (role === 'security') return securityHandback(root, run, env.ops.gate, text);
|
|
986
1015
|
const verdict = role === 'audit' ? parseVerdict(text) : null;
|
|
987
1016
|
const recorded = recordHandback(run, role, env.ops.gate, verdict?.verdict, { snap });
|
|
@@ -992,6 +1021,13 @@ async function handback(root, sessionId, role, bytes) {
|
|
|
992
1021
|
return `${role} handed back ${env.ops.gate}${note}`;
|
|
993
1022
|
}
|
|
994
1023
|
|
|
1024
|
+
// BUG-077: the owner's spec approval binds a document the spec hand-back named, as delegate's does.
|
|
1025
|
+
function checkSpecHandedBack(run, rel) {
|
|
1026
|
+
const named = handedBackDocs(run, 'spec');
|
|
1027
|
+
if (named.includes(rel)) return;
|
|
1028
|
+
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`);
|
|
1029
|
+
}
|
|
1030
|
+
|
|
995
1031
|
// Two human approvals, one gate write (A4): only an approved plan writes define_approved.
|
|
996
1032
|
// FEAT-055: and HEAD at that moment, so resume can tell whether history still holds it.
|
|
997
1033
|
// FEAT-056: each approval binds the bytes the owner was shown; a stale hash writes nothing.
|
|
@@ -1003,12 +1039,13 @@ function approve(root, sessionId, what, rel, shown) {
|
|
|
1003
1039
|
if (!RECORD_KINDS.includes(what)) throw new Refusal(APPROVE_USAGE);
|
|
1004
1040
|
if (!SHA256_HEX.test(shown ?? '')) throw new Refusal(APPROVE_USAGE);
|
|
1005
1041
|
const content = readDoc(root, rel, APPROVE_USAGE);
|
|
1042
|
+
if (what === 'spec') checkSpecHandedBack(run, rel);
|
|
1006
1043
|
const sha256 = documentHash(what, content);
|
|
1007
1044
|
checkLoopClosed(run, what, rel, sha256);
|
|
1008
1045
|
if (sha256 !== shown.toLowerCase()) {
|
|
1009
1046
|
throw new Refusal(`ORCH_DOC_HASH_STALE: ${what} ${rel} hashes ${sha256}, not the ${shown} that was shown; show the document again`);
|
|
1010
1047
|
}
|
|
1011
|
-
const approval = { at: new Date().toISOString(), by:
|
|
1048
|
+
const approval = { at: new Date().toISOString(), by: 'owner', path: rel, sha256, commit: headObject(root) };
|
|
1012
1049
|
if (what === 'plan') return approvePlan(root, run, content.toString('utf8'), approval);
|
|
1013
1050
|
saveRun(root, { ...run, approvals: { ...run.approvals, spec: approval } });
|
|
1014
1051
|
return `spec approved: sha256 ${sha256}`;
|
|
@@ -1065,11 +1102,16 @@ const snapFiles = (entry) => { try { const f = JSON.parse(entry?.snap).ops.f; re
|
|
|
1065
1102
|
// The role's pinned docs folder (FEAT-047): its scope glob without the trailing **, or '' when none was pinned.
|
|
1066
1103
|
const docsFolder = (run, kind) => String(run.docs?.scopes?.[kind]?.[0] ?? '').replace(/\*\*$/, '');
|
|
1067
1104
|
|
|
1068
|
-
// The
|
|
1069
|
-
function
|
|
1105
|
+
// The documents the Define role named in its hand-back, inside its pinned folder: the brief's, never the orchestrator's pick.
|
|
1106
|
+
function handedBackDocs(run, kind) {
|
|
1070
1107
|
const folder = docsFolder(run, kind);
|
|
1071
|
-
|
|
1108
|
+
return snapFiles(run.handbacks.findLast((h) => h.role === kind)).filter((f) => /:[CM]$/.test(f)).map((f) => f.slice(0, -2))
|
|
1072
1109
|
.filter((p) => folder !== '' && p.startsWith(folder) && p.endsWith('.md'));
|
|
1110
|
+
}
|
|
1111
|
+
|
|
1112
|
+
function handedBackDoc(run, kind) {
|
|
1113
|
+
const folder = docsFolder(run, kind);
|
|
1114
|
+
const docs = handedBackDocs(run, kind);
|
|
1073
1115
|
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`);
|
|
1074
1116
|
return docs[0];
|
|
1075
1117
|
}
|
|
@@ -1262,11 +1304,16 @@ function candidateEntries(run) {
|
|
|
1262
1304
|
}
|
|
1263
1305
|
|
|
1264
1306
|
// A task entry still describes the repository: its position, its SNAP and its commit all hold.
|
|
1265
|
-
|
|
1307
|
+
// BUG-075: and it still names the scope its task installs, over paths inside it.
|
|
1308
|
+
function taskEntryHolds(root, run, entry, taskId) {
|
|
1266
1309
|
if (entry.task !== taskId || typeof entry.snap !== 'string' || validate(`${entry.snap}\n`) !== '') return false;
|
|
1267
1310
|
let env = null;
|
|
1268
1311
|
try { env = JSON.parse(entry.snap); } catch { return false; }
|
|
1269
|
-
|
|
1312
|
+
if (env?.sys?.role !== 'code' || ancestry(root, env.sys.c) !== 0) return false;
|
|
1313
|
+
try { return claimHalt(env, 'code', codeScope(root, run, { task: taskId })) === null; } catch (e) {
|
|
1314
|
+
if (e instanceof Halt) return false;
|
|
1315
|
+
throw e;
|
|
1316
|
+
}
|
|
1270
1317
|
}
|
|
1271
1318
|
|
|
1272
1319
|
// Each approved document's entry, then Build's task entries up to the first that fails; Verify is always redone.
|
|
@@ -1276,7 +1323,7 @@ function keptEntries(root, run) {
|
|
|
1276
1323
|
if (!run.approvals.plan) return { kept: approved, tasks: 0 };
|
|
1277
1324
|
const tasks = entries.filter((h) => h.role === 'code' && !('fix' in h));
|
|
1278
1325
|
let n = 0;
|
|
1279
|
-
while (n < tasks.length && n < run.tasks.ids.length && taskEntryHolds(root, tasks[n], run.tasks.ids[n])) n += 1;
|
|
1326
|
+
while (n < tasks.length && n < run.tasks.ids.length && taskEntryHolds(root, run, tasks[n], run.tasks.ids[n])) n += 1;
|
|
1280
1327
|
return { kept: [...approved, ...tasks.slice(0, n)], tasks: n };
|
|
1281
1328
|
}
|
|
1282
1329
|
|
|
@@ -1474,13 +1521,30 @@ function clearRunFiles(root) {
|
|
|
1474
1521
|
rmSync(join(root, DELEGATE_DIR), { recursive: true, force: true });
|
|
1475
1522
|
}
|
|
1476
1523
|
|
|
1524
|
+
const END_USAGE = 'usage: orchestrate.mjs end [--abandon]';
|
|
1525
|
+
|
|
1526
|
+
// BUG-075: the run end would drop before Verify passed, or null; a missing, broken or halted run is never held.
|
|
1527
|
+
function unverifiedRun(root) {
|
|
1528
|
+
let run = null;
|
|
1529
|
+
try { run = readRun(root); } catch { return null; }
|
|
1530
|
+
if (!run || run.halt) return null;
|
|
1531
|
+
const last = run.handbacks.at(-1);
|
|
1532
|
+
return last?.role === 'qa' && last.gate === 'verify_pass' ? null : run;
|
|
1533
|
+
}
|
|
1534
|
+
|
|
1477
1535
|
// Prints the run it removes, so the closing report reads the record rather than memory.
|
|
1478
|
-
|
|
1536
|
+
// BUG-075: a live run ends only after qa's verify_pass, unless the owner abandons it by name.
|
|
1537
|
+
function end(root, args) {
|
|
1538
|
+
if (args.length > 1 || (args.length === 1 && args[0] !== '--abandon')) throw new Refusal(END_USAGE);
|
|
1539
|
+
const run = unverifiedRun(root);
|
|
1540
|
+
if (run && args.length === 0) {
|
|
1541
|
+
throw new Refusal(`ORCH_END_UNVERIFIED: run ${run.item} is at ${describeStep(nextStep(run))} with no verify_pass; end it only after qa, after a halt, or with end --abandon on the owner's word`);
|
|
1542
|
+
}
|
|
1479
1543
|
const path = join(root, RUN_FILE);
|
|
1480
1544
|
const text = existsSync(path) ? readFileSync(path, 'utf8').trim() : 'no run file';
|
|
1481
1545
|
rmSync(path, { force: true });
|
|
1482
1546
|
clearRunFiles(root);
|
|
1483
|
-
return text;
|
|
1547
|
+
return run ? `run ${run.item} abandoned at ${run.gate} before verify_pass\n${text}` : text;
|
|
1484
1548
|
}
|
|
1485
1549
|
|
|
1486
1550
|
function recordHalt(root, halt) {
|
|
@@ -1587,7 +1651,7 @@ export async function cli(argv, env, cwd = process.cwd()) {
|
|
|
1587
1651
|
delegate: () => delegate(root, sid, argv.slice(1)),
|
|
1588
1652
|
resume: () => resume(root, sid, argv.slice(1)),
|
|
1589
1653
|
envelope: () => envelopeVerb(root, sid, argv.slice(1)),
|
|
1590
|
-
end: () => end(root),
|
|
1654
|
+
end: () => end(root, argv.slice(1)),
|
|
1591
1655
|
};
|
|
1592
1656
|
try {
|
|
1593
1657
|
if (!verbs[verb]) throw new Refusal('usage: orchestrate.mjs start|install|handback|approve|hash|review|delegate|resume|envelope|end');
|