open/voyage
1
0
Fork 0
Code Issues Releases 13 Activity

feat(trekexecute): couple the executor to the review gate, the plan approval and the step checks

Browse source 
Wave 2, order 6. /trekexecute now:
- refuses a plan whose logged approval does not cover its current sha256
  (K2, approval-log verify --kind plan), before step 1;
- runs the step check (K9) and the step's optional Regression: (K10, new
  lib/verification/regression-check.mjs through the criteria runner) at step
  end, before the checkpoint; exit 2 is "not measured", never green;
- runs the architecture rules (K5) and the plan-file sweep (K6) after the last
  step; a violation or a file outside the plan turns completed into partial;
- reviews by itself in the closing run (Phase 7.2): run the thing, /simplify,
  /trekreview, verdict-gate; a BLOCK adds the review's remediation steps after
  the plan validator accepts them and the operator re-approves the plan, capped
  at TREKEXECUTE_MAX_REVIEW_ROUNDS (3);
- makes the main-merge gate a lock on the verdict: BLOCK or undecided keeps
  the merge closed; when open, the executor merges and the guard's question is
  the one question (operator decision 2026-10-08). The --gates pause before
  the wave merge-back is gone for the same reason.

The guard refuses a merge into main and a push in the permission mode that
shows no prompts, since no one can be asked (operator decision 2026-10-09; two
mode-read exemptions approved by the operator).

progress.json gains optional coupling fields (Handover 5); the validator
rejects the runner's exitCode in plan_verification.failed_criteria (C15).
Pointer lines name the skills test-first and debugging (S2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-10-09 19:22:00 +02:00
commit 920fbd3c47
Signed by: ktg
SSH key fingerprint: SHA256:JakMjO6FTBBzN0Bhfj9saOoEjaFxlSdYuZQQpM/lF9Q
15 changed files with 1310 additions and 64 deletions
Download patch file Download diff file Expand all files Collapse all files

76
lib/validators/progress-validator.mjs
View file

@ -8,9 +8,13 @@
// cross-check in trekexecute, not by this per-validation shape check.
// The same holds for the wave-1 step-loop fields (per step: start_sha, report_path,
// red_proof, test_lock, fix_rounds 0..5; per run: decisions): shape-checked when
// present, never required.
// present, never required. So are the wave-2 coupling fields (per step: step_check
// from K9, regression from K10; per run: plan_approval, arch_rules, scope_sweep,
// simplify, review) and the key of plan_verification.failed_criteria: the runner
// says `exitCode`, progress says `exit_code`, and only `exit_code` is accepted (C15).
import { readFileSync, existsSync } from 'node:fs';
import { readFileSync, existsSync, realpathSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { issue, fail } from '../util/result.mjs';
export const PROGRESS_REQUIRED_TOP = ['schema_version', 'plan', 'plan_version', 'mode', 'status', 'total_steps', 'current_step', 'steps'];
@ -28,6 +32,17 @@ export const PROGRESS_MAX_FIX_ROUNDS = 5;
export const PROGRESS_RED_PROOF_VALUES = ['proven', 'rejected', 'not-run'];
export const PROGRESS_TEST_LOCK_VALUES = ['locked', 'released', 'not-locked'];
// Wave 2 (order 6) coupling fields. Each value is the exit of a contract CLI said
// in words; "not-measured" / "not-run" are never green, and "absent" means the plan
// declared nothing (no `Regression:` field), so nothing new happened.
export const PROGRESS_STEP_CHECK_VALUES = ['clean', 'findings', 'not-measured']; // K9 exit 0 / 1 / 2
export const PROGRESS_REGRESSION_VALUES = ['passed', 'failed', 'unrunnable', 'not-run', 'absent']; // K10
export const PROGRESS_PLAN_APPROVAL_VALUES = ['approved', 'not-checked']; // K2; not-checked = a session spec
export const PROGRESS_ARCH_RULES_VALUES = ['pass', 'violation', 'not-measured']; // K5 exit 0 / 1 / 2
export const PROGRESS_SCOPE_SWEEP_VALUES = ['pass', 'deviation', 'not-measured']; // K6 exit 0 / 1 / 2
export const PROGRESS_SIMPLIFY_VALUES = ['applied', 'clean', 'reverted', 'not-run'];
export const PROGRESS_REVIEW_GATE_EXITS = [0, 1, 2]; // K7: ALLOW/WARN, BLOCK, could not decide
function checkStepFields(k, s, errors) {
const set = (v) => v !== undefined && v !== null;
if (s.fix_rounds !== undefined &&
@ -47,6 +62,50 @@ function checkStepFields(k, s, errors) {
if (set(s.test_lock) && !PROGRESS_TEST_LOCK_VALUES.includes(s.test_lock)) {
errors.push(issue('PROGRESS_TEST_LOCK_INVALID', `steps["${k}"].test_lock "${s.test_lock}" not in [${PROGRESS_TEST_LOCK_VALUES.join(', ')}]`));
}
if (set(s.step_check) && !PROGRESS_STEP_CHECK_VALUES.includes(s.step_check)) {
errors.push(issue('PROGRESS_STEP_CHECK_INVALID', `steps["${k}"].step_check ${JSON.stringify(s.step_check)} not in [${PROGRESS_STEP_CHECK_VALUES.join(', ')}]`));
}
if (set(s.regression) && !PROGRESS_REGRESSION_VALUES.includes(s.regression)) {
errors.push(issue('PROGRESS_REGRESSION_INVALID', `steps["${k}"].regression ${JSON.stringify(s.regression)} not in [${PROGRESS_REGRESSION_VALUES.join(', ')}]`));
}
}
const isStr = (v) => typeof v === 'string' && v.trim() !== '';
// Wave 2 (order 6) run-level fields; all optional, shape-checked when set.
function checkCouplingFields(p, errors) {
const set = (v) => v !== undefined && v !== null;
const oneOf = (field, values, code) => {
if (set(p[field]) && !values.includes(p[field])) {
errors.push(issue(code, `${field} ${JSON.stringify(p[field])} not in [${values.join(', ')}]`));
}
};
oneOf('plan_approval', PROGRESS_PLAN_APPROVAL_VALUES, 'PROGRESS_PLAN_APPROVAL_INVALID');
oneOf('arch_rules', PROGRESS_ARCH_RULES_VALUES, 'PROGRESS_ARCH_RULES_INVALID');
oneOf('simplify', PROGRESS_SIMPLIFY_VALUES, 'PROGRESS_SIMPLIFY_INVALID');
const sw = p.scope_sweep;
if (set(sw) && !(typeof sw === 'object' && PROGRESS_SCOPE_SWEEP_VALUES.includes(sw.status) &&
Array.isArray(sw.outside) && sw.outside.every(isStr))) {
errors.push(issue('PROGRESS_SCOPE_SWEEP_INVALID',
`scope_sweep must be {status: ${PROGRESS_SCOPE_SWEEP_VALUES.join('|')}, outside: [paths]}`));
}
const rv = p.review;
if (set(rv) && !(typeof rv === 'object' && Number.isInteger(rv.round) && rv.round >= 1 &&
PROGRESS_REVIEW_GATE_EXITS.includes(rv.gate_exit))) {
errors.push(issue('PROGRESS_REVIEW_INVALID', 'review must be {round: integer >= 1, gate_exit: 0|1|2, ...}'));
}
// C15: the criteria runner reports `exitCode`; progress.json carries `exit_code`
// (an integer, or null when the criterion never ran). The executor translates;
// the runner's key here means the translation was skipped.
const fc = p.plan_verification?.failed_criteria;
if (fc !== undefined && fc !== null) {
const ok = Array.isArray(fc) && fc.every((c) => c && typeof c === 'object' && !('exitCode' in c) &&
'exit_code' in c && (c.exit_code === null || Number.isInteger(c.exit_code)));
if (!ok) {
errors.push(issue('PROGRESS_FAILED_CRITERIA_KEY',
'plan_verification.failed_criteria entries carry exit_code (integer or null), never the runner key exitCode'));
}
}
}
// The run-level decision log (P4): every decision the executor took on its own,
@ -129,6 +188,7 @@ export function validateProgressObject(parsed, opts = {}) {
}
checkDecisions(parsed.decisions, errors);
checkCouplingFields(parsed, errors);
return { valid: errors.length === 0, errors, warnings, parsed };
}
@ -152,7 +212,17 @@ export function validateProgress(filePath, opts = {}) {
return validateProgressContent(text, opts);
}
if (import.meta.url === `file://${process.argv[1]}`) {
// The real paths on both sides: a `file://` comparison fails when the path holds a
// space or runs through a symlink, and the CLI then exits 0 having checked nothing.
function isMain() {
try {
return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
} catch {
return false;
}
}
if (isMain()) {
const args = process.argv.slice(2);
const filePath = args.find(a => !a.startsWith('--'));
if (!filePath) {