jules-orchestrator-kit 0.67.0 → 0.69.0

package/README.md

@@ -68,7 +68,8 @@ git add .agent AGENTS.md SPEC.md CONSTRAINTS.md .gitignore && git commit -m "cho
 
 ```bash
 # 3. Author a scoped, verified task envelope with guardrails & secret scrubbing
-npx jules-orchestrator-kit task create
+#    Interactive by default. Pass the prompt to skip straight to review:
+npx jules-orchestrator-kit task create -p "Refactor the invoice module"
 ```
 
 `init` reads the repository, not a template: it detects the stack, picks a
@@ -207,7 +208,7 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 * **Fail-Closed Security & Secret Redaction:** Evaluates explicit Deny rules before Allow rules against canonicalized, case-folded paths. Redacts high-entropy keys and base64-encoded credentials (such as Kubernetes `Secret` manifests).
 * **Complexity & Cost Router:** Zero-dependency heuristic classifier (`src/router.mjs`) routing mechanical tasks to lightweight models while reserving primary models for complex refactors, with a `node --check` syntax-verification gate that transparently escalates a FAST-tier result to the primary provider if it left broken JS on disk.
 * **Terminal UI & Diagnostic Matrix (`agentctl doctor`):** Interactive terminal dashboard, task sidecar manager, and automated transactional self-repair.
-* **Verified Test Suite:** Tested with **1154 unit tests across 166 suites passing in < 15.0s**.
+* **Verified Test Suite:** Tested with **1223 unit tests across 173 suites**, green on every supported platform.
 
 <br/>
 
@@ -240,7 +241,7 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 | `doctor` | `agentctl doctor [--probe] [--json]` | Diagnostic check runner. `--probe` additionally starts the configured provider's CLI to confirm it answers, rather than only finding it on `PATH`. | `0` (Healthy), `1` (Failures) |
 | `queue` | `agentctl queue [--dag] [--concurrency <n>] [--dry-run] [--json]` | Consumes and executes task envelopes in `.agent/jules-queue/` with Kahn's DAG dependency resolution. Non-task files (manifests, `README.md`) are skipped, and `--dry-run` previews without moving anything. | `0` (Complete) |
 | `swarm` | `agentctl swarm [--json]` | Runs parallel multi-agent swarm across worker slots with PID liveness detection. | `0` (Complete) |
-| `check` / `gate` / `audit`| `agentctl check [--mode working-tree] [--fix] [--allow-protected] [--allow-test-change <kind>] [--json] [--json-report <path>]` | Runs security, secret scanning, rules budget audit, and tiered verification gates (with declarative assertion support) against working tree or branch. | `0` (Approved), `1` (Budget/Arg), `3` (Scope), `4` (Verify), `5` (Diff >75K), `6` (Secret), `8` (Flaky) |
+| `check` / `gate` / `audit`| `agentctl check [--mode working-tree] [--fix] [--allow-protected] [--allow-test-change <kind>] [--json] [--json-report <path>]` | Runs security, secret scanning, rules budget audit, and tiered verification gates (with declarative assertion support) against working tree or branch. | `0` (Approved), `1` (Budget/Arg), `3` (Scope), `4` (Verify), `5` (Diff >75K), `6` (Secret **or** test integrity), `8` (Flaky) |
 | `mutate` / `mutation` | `agentctl mutate [--min-score <n>] [--max-mutants <n>] [--cmd <testCmd>] [--json]` | Runs zero-dependency diff mutation testing harness on changed hunks with operator inversion and safety rollback. | `0` (Passed), `1` (Score Low) |
 | `coverage` | `agentctl coverage [--min <pct>] [--cmd <testCmd>] [--base <ref>] [--json]` | Runs native zero-dependency V8 diff coverage check against added diff lines. | `0` (Passed), `1` (Low Coverage) |
 | `probe` / `stability` | `agentctl probe [--repeat <n>] [--min <passRate>] [--cmd <testCmd>] [--json]` | Probes test suite flakiness across N consecutive iterations with oscillation detection. | `0` (Passed), `1` (Flaky) |
@@ -285,6 +286,9 @@ branchPrefix: "agent/"   # Prefix for task branches
 verify:
   test: "npm test"
   build: "npm run build"
+  timeout_ms: 300000     # Per-stage kill time in ms (default 300000)
+  minTests: 1            # Floor for "the suite actually ran" (0 disables)
+  required: true         # false = this repo uses only the scope/secret phases
 
 # Scope protection rules (Deny-first evaluation)
 scope:

package/ROADMAP_V1.md

@@ -0,0 +1,210 @@
+# 🗺️ Jules Orchestrator Kit — Roadmap to v1.0 & Beyond
+
+The **jules-orchestrator-kit** is the zero-dependency safety gatekeeper and self-healing engineering kernel for autonomous coding agents — **Google Jules**, **Claude Code**, **Codex** and the **Gemini CLI** — in any repository and any stack.
+
+> [!IMPORTANT]
+> **Zero Runtime Dependencies is a strict core invariant.**  
+> Every feature on this roadmap is built strictly with native Node.js 20+ built-in modules (`node:fs`, `node:child_process`, `node:crypto`, `node:http`, `node:readline`, `node:test`).
+
+---
+
+## 📌 Release Milestones Overview
+
+```
+ v0.69.0 (Current Stable) ──► v0.70.0 (Distributed Swarms & Leases) ──► v1.0.0 (Production Hardened Kernel)
+ (Read, Not Just Counted)    (Multi-Agent DAG & Resource Locks)        (Enterprise Telemetry & SLA)
+```
+
+---
+
+## ✅ Shipped Milestones (v0.20.0 – v0.69.0)
+
+
+### v0.69.0: Read, Not Just Counted
+- [x] **Expected-Value-First Assertions (`src/security.mjs`)** — JUnit and PHPUnit document the order the guard read as prose.
+- [x] **A Regex Is An Expected Value (`src/security.mjs`)** — a rewritten pattern was neither a change nor a loss.
+- [x] **Renaming A Test Is Not Tampering (`src/security.mjs`)** — on the one-line form, the name blanked into the expectation.
+- [x] **An Environment Prefix Runs (`src/git.mjs`)** — `PYTHONPATH=src pytest` never started, and was reported as a failure.
+- [x] **`node -e ""` Is A Placeholder (`src/stack-detector.mjs`)** — the same no-op, spelled to look like work.
+- [x] **`init` Rejects An Oracle That Proves Nothing (`src/wizard-init.mjs`)** — silence at setup is silence at every gate after it.
+
+### v0.68.0: Not An Approval Either
+- [x] **An Unreadable Dialect Blocks (`src/security.mjs`)** — the guard said it had not checked, and approved anyway.
+- [x] **A Command That Cannot Fail Is Not An Oracle (`src/engine.mjs`)** — `task create` already refused what the gate accepted.
+- [x] **chai And node-tap (`src/security.mjs`)** — a dot chain where RSpec has a space, and a receiver named `ct`.
+- [x] **A Reformat Is Not A Weakening (`src/security.mjs`)** — the weakening count was still line-based.
+- [x] **`bootstrap` Declines (`src/stack-detector.mjs`)** — rather than writing an oracle that asserts its own impossibility.
+
+### v0.67.0: A Move Is Not A Deletion
+- [x] **In-Body Skips (`src/security.mjs`)** — a test could be silenced with `self.skipTest()`, the form unittest's own documentation uses.
+- [x] **Cross-File Moves (`src/security.mjs`)** — refactoring produced CRITICAL findings for assertions that still run.
+- [x] **The Published Package Explains Itself (`scripts/run-tests.mjs`)** — `npm test` crashed with a raw ENOENT in an installed copy.
+- [x] **The Label Names What Failed (`bin/agentctl.mjs`)** — a deleted assertion was reported under a bare SECRETS heading.
+
+### v0.66.0: Saying Nothing Is Not Saying Approved
+- [x] **An Assertion Is A Statement (`src/security.mjs`)** — a rewritten expected value whose keyword sat on a context line collected five green phases.
+- [x] **Line Comments Are Stripped (`src/security.mjs`)** — they never were; `pending` was left at the comment and the copy after the loop put it back.
+- [x] **The Boundary Reaches The Operator (`src/security.mjs`)** — the warning was wired to a function the gate does not call.
+- [x] **Evidence Before Rules (`src/memory.mjs`)** — a hardcoded sentence was being injected into every prompt as if it were a fix.
+
+### v0.65.0: The First Hour
+- [x] **The Quickstart No Longer Rejects Its Own Output (`src/engine.mjs`)** — `init` wrote the scaffold, told the user to commit it, and the gate called that commit a scope violation while advising `--allow-protected`.
+- [x] **A Stated Count Outranks A Phrase (`src/ops/test-collection.mjs`)** — a healthy 190-test TAP suite was rejected as empty because a skipped fixture printed `no tests found`.
+- [x] **`init` Probes On The Headless Path (`src/wizard-init.mjs`)** — `--yes` means "do not ask me", not "do not check".
+- [x] **`verify.minTests` Reaches The Floor (`src/engine.mjs`)** — the failure message named a lever that was connected to nothing.
+
+### v0.64.0: What The Guard Could Not Read
+- [x] **The Package Is Checked The Way It Is Installed (`scripts/package-integrity-check.mjs`)** — the tarball's own import graph, resolved inside the tarball. The previous release shipped the activation-coverage check without the contract it imports.
+- [x] **Five Silent Ecosystems (`src/security.mjs`)** — JUnit, RSpec, PHPUnit, Minitest and XCTest all returned `PASS` on a rewritten expected value, and `assertEqual` had been working only by accident.
+- [x] **`UNREADABLE` (`src/security.mjs`)** — coverage ending is fine; coverage ending silently is not.
+- [x] **Contracts For The Opposite Failure (`src/guard-policy.mjs`)** — ten ordinary edits that must produce no finding, because a guard that flags everything is switched off within a week.
+
+### v0.63.0: Can It Still Go Red?
+- [x] **Activation Coverage (`scripts/guard-reach-check.mjs`)** — Blocking in CI and in the release. Eleven known-bad canaries across six ecosystems must each still produce the finding they name; four hand-written mutants of the applicability predicate must each break at least one. Runs in 88 ms.
+- [x] **A Hand-Written Policy Contract (`src/guard-policy.mjs`)** — Derived from what the tool advertises, never from the regexes that implement it, so the implementation cannot be its own oracle.
+- [x] **Verdicts Carry Their Denominator (`src/security.mjs`)** — `checkTestTampering` reports `inputsSeen` and a `PASS`/`FAIL`/`NOT_APPLICABLE` status, so "checked and clean" is no longer byte-identical to "nothing was checked".
+
+
+### v0.62.0: No Denominator, No Claim
+- [x] **A File Is Not A Claim (`src/stack-detector.mjs`)** — `make test` requires the Makefile to declare the target; `app.json` requires a package.json beside it; a `test` script that is `echo … && exit 0` is a placeholder, not an oracle.
+- [x] **The Generated Fallback Oracle Can Fail (`src/stack-detector.mjs`)** — It checks that every source file parses instead of asserting that the working directory exists, and refuses to pass with nothing to check.
+- [x] **Lockfiles And Toolchain Pins Are Protected (`src/config.mjs`)** — `package.json` was protected and `package-lock.json` was not. Plus `.envrc`, `.git-credentials`, cloud credential trees and CodeBuild.
+- [x] **The Sixth Spelling Of "Where Are The Tests" (`src/evidence.mjs`)** — Go co-located tests and every monorepo produced `fileCount: 0`, which switched `strictTestLock` off in silence.
+- [x] **Seven More Runners In The Collection Floor** — Maven, Gradle, PHPUnit, RSpec, dotnet, XCTest, ctest, ExUnit.
+- [x] **100% Of Nothing Is Not 100% (`src/coverage.mjs`)** — Diff coverage reports `scored: false` where V8 measured nothing, instead of the best possible number.
+
+
+### v0.61.0: Green Against Nothing
+- [x] **Collection Floor (`src/ops/test-collection.mjs`)** — A verification command that exits 0 having collected zero tests is no longer a pass. The count is read from the runner's own summary across node:test, pytest, cargo, jest, vitest, mocha and go; an unrecognised runner states no count and is not failed for it.
+
+
+### v0.60.0: A Guard Worth Reading
+- [x] **Per-Check Overrides (`--allow-test-change <kind>`)** — Answering one tamper finding no longer silences the five other checks in the bundle. `--allow-test-modifications` remains as the blunt form.
+- [x] **Unchanged Assertions Cancel Before Pairing (`src/security.mjs`)** — Reordering or moving an assertion is no longer reported as two rewritten expectations.
+- [x] **A Reworded Message Is Not A Rewritten Expectation (`src/security.mjs`)** — Message-position string arguments are compared apart from value positions, so improving the wording of a failure is silent while `assert.equal(name(), "Alice")` → `"Bob"` still fires.
+
+
+### v0.59.0: One Answer Per Question
+- [x] **One Test-Path Classifier (`src/test-paths.mjs`)** — Five modules had five definitions of "is this a test file?"; the tamper guard's could not see `tests/test_calc.py`, so every check in it was off for the standard pytest, Rust and RSpec layouts. All five now share `isTestPath`.
+- [x] **Statement-Level Expectation Pairing (`src/security.mjs`)** — Assertions are reassembled from the diff's two images before pairing, so wrapping one across lines no longer walks through the guard. Contributed as PR #14 by an external agent; verified and merged.
+- [x] **Numeric Literals Beyond Decimal (`src/security.mjs`)** — Hex, binary, octal, exponent and underscored literals normalise, so `0xFF` → `0xFE` is a rewritten expectation like any other.
+
+
+### v0.58.0: Locks That Lock
+- [x] **A CLI Lock Is A Lease (`src/state.mjs`, `bin/agentctl.mjs`)** — `lock acquire` no longer witnesses its own exiting process, so two agents can no longer both hold the same file. `--ttl` bounds it; `--pid` binds it to a real long-lived process instead.
+- [x] **A URL No Longer Disables The Secret Scanner (`src/security.mjs`)** — URLs, data: URIs and integrity hashes are stripped from a line rather than skipping the whole line, and a URL's userinfo and query values are scanned on their own.
+- [x] **Untracked Symlinks Are Judged By Their Target (`src/git.mjs`)** — Working-tree mode resolves links git has never seen, and a symlink is rendered as its target *path* rather than read through.
+- [x] **Rewritten Expectations Are Reported (`src/security.mjs`)** — An assertion whose literal changed while its shape did not is `ASSERTION_EXPECTATION_CHANGED`, with `--allow-test-modifications` as the documented override.
+- [x] **Scope Guard Covers Every Forge (`src/config.mjs`)** — GitLab, CircleCI, Jenkins, Azure, Travis, Drone, Buildkite and Woodpecker definitions are denied alongside `.github/**`; build and test-runner configuration is protected.
+- [x] **Python Runs As A Module (`src/stack-detector.mjs`)** — `python -m pytest` under whichever interpreter name this machine has, so an ordinary layout is not rejected on first contact.
+- [x] **Build Artifacts Do Not Read As Tampering (`src/evidence.mjs`)** — Caches a test run writes itself are excluded from the integrity hash.
+
+
+### v0.57.0: Honest Reporting
+- [x] **Stack-Native TDD Oracles (`src/ops/tdd-generator.mjs`)** — Generated in the runner's own language, with a RED check that requires the assertion to have actually run rather than accepting any non-zero exit.
+- [x] **JSON Envelopes Reach The DAG Runner (`src/dag-engine.mjs`)** — `isDagTaskFile` is exported and used for the CLI's count, so a queue of `.json` envelopes is no longer reported as empty.
+- [x] **`swarm` Honours Its Flags (`bin/agentctl.mjs`)** — `--json`, `--dry-run` and `--concurrency` are parsed, and the registry describes a dispatcher rather than an inspector.
+- [x] **No Score Where Nothing Was Measured (`src/mutation.mjs`)** — An empty mutant population reports `null` and a reason instead of a vacuous 100%.
+- [x] **New Files Are Visible To Every Gate (`src/git.mjs`)** — The synthetic diff for an untracked file carries a `@@` header, so mutation and diff coverage can place its lines at all.
+
+
+### v0.56.0: Wired, Not Just Shipped
+- [x] **File-Aware Locking (`src/state.mjs`)** — `acquireLock()` compares the requested paths against every live lock instead of only the task id.
+- [x] **Checkpoints That Exist (`src/engine.mjs`, `src/session-ops.mjs`)** — Taken before a dispatch and before `patch --apply`, so `agentctl rollback` finally has something to restore.
+- [x] **Reachable Monorepo Scoping (`verify.scope: affected`)** — The boundary resolver is called by the gate, opt-in, defaulted on for repositories detected as monorepos and widening again when a shared file changes.
+- [x] **Process-Group Reaping For The Test Runner (`scripts/run-tests.mjs`)** — An interrupted run takes its whole tree with it instead of orphaning every process below the first level. A first instance of the v0.60.0 guillotine, applied where the leak was actually observed.
+- [x] **Live-Path Corrections (`src/provider.mjs`, `src/engine.mjs`)** — `listSources()` works against the real API, and Node's test-runner context no longer masks a failing verification command.
+
+
+### v0.55.0: Verification Integrity
+- [x] **Assertion Weakening Detection (`src/security.mjs`)** — A specific expectation swapped for a vague one is reported as `ASSERTION_WEAKENED`, closing the one-out-one-in bypass that counting assertions could never see.
+- [x] **Symlink-Aware Scope (`src/git.mjs`, `src/engine.mjs`)** — Added links are judged by the path they resolve to as well as their own name, without following anything on disk.
+- [x] **Source-Bound Evidence (`src/evidence.mjs`)** — Manifests attest to the source tree, not only the tests, and the integrity hash finally sees test files that live at the repository root.
+
+
+### v0.54.1: The Gate Fails Closed
+- [x] **No Oracle, No Approval (`src/engine.mjs`)** — A change that ran zero verification commands is rejected rather than approved; `verify.required: false` is the deliberate opt-out, read from the base commit.
+- [x] **Binary Payload Inspection (`src/security.mjs`, `src/git.mjs`)** — Files git renders as "Binary files ... differ" are read directly for structured credentials, closing the NUL-byte bypass, and their real size is charged against the payload ceiling.
+
+
+### v0.54.0: First-Run Friction — Honest Errors, Detected Defaults
+- [x] **Base Branch Detection (`src/git.mjs`)** — `detectDefaultBranch()` resolves `origin/HEAD`, a local `main`/`master`, then the checked-out branch, replacing the hardcoded `main` that failed the first gate in every `master` or `develop` repository.
+- [x] **Diagnosable Gate Output (`bin/agentctl.mjs`, `src/ops/verify-output.mjs`)** — Phase errors are rendered instead of swallowed, and a failing stage's stdout is no longer discarded because the spawn wrapper wrote one line to stderr.
+- [x] **Truthful Remediation Hints (`bin/agentctl.mjs`)** — Test tampering no longer advises rotating API keys, and a provider that refused the dispatch is no longer reported as an exhausted repair loop.
+- [x] **Provider-First Onboarding & `agentctl provider set` (`src/wizard-init.mjs`, `src/config-edit.mjs`)** — The wizard asks which agent before asking about one vendor's plans, and switching providers no longer means re-running onboarding.
+- [x] **Named Targets And Flags Actually Take Effect (`bin/agentctl.mjs`, `src/ops/ide-scaffold.mjs`, `src/ops/cli-intent.mjs`)** — `mcp init <target>`, `task create --title/--prompt` and `doctor --probe` all did something other than what they said; each now does what it says, or is no longer advertised.
+- [x] **Onboarding Trap Distinguished From Overreach (`src/git.mjs`)** — `partitionTracked()` tells uncommitted scaffolding apart from an agent editing its own rules, so the first-run exit 3 advises committing rather than bypassing the gate.
+- [x] **Rehearsals Write Nothing (`src/wizard-task.mjs`)** — `task create --dry-run` synthesizes and validates the envelope without queueing it.
+
+
+### v0.53.0: Universal Portability — Any Stack, Any Agent, Any CI
+- [x] **Provider Readiness Probe (`src/provider-readiness.mjs`, `agentctl providers`)** — Per-provider capability descriptors: a credential for the hosted `jules` adapter, a `PATH` binary for the `claude-code`/`codex`/`gemini-flash` exec adapters, with a cross-platform PATHEXT-aware resolver that spawns nothing.
+- [x] **Vendor-Neutral Environment Spellings (`src/env-aliases.mjs`)** — Every `JULES_*` knob also answers to `AGENT_*`, normalised once at CLI entry, with the legacy name always winning.
+- [x] **Verification Profiles (`src/profiles.mjs`, `agentctl profile`)** — `minimal | standard | max` expanded at load time into a stack-aware pipeline that skips unsupported gates with a stated reason rather than failing the diff.
+- [x] **Generated Stack-Aware CI (`src/ci-templates.mjs`, `agentctl ci init`)** — GitHub Actions and GitLab jobs carrying the detected stack's toolchain, replacing the copy of this repository's own nine-way Node matrix.
+- [x] **Consumer Repository Hygiene (`bin/init.js`)** — `init` no longer copies the kit's twenty internal scripts into the target repository, and both entry points now write the same manifest pair.
+
+
+### v0.52.x: Entropy Hardening, Egress Auditing & CI Defense
+- [x] **Binary Asset Classification Guard (`src/security.mjs`)** — Restricts binary asset skipping to tokens $\ge 256$ chars, preventing length $\pmod 4 = 0$ keys from bypassing entropy checks.
+- [x] **CI Runtime & Egress Security (`.github/workflows/*.yml`)** — Linux eBPF runtime monitoring and network egress auditing via StepSecurity.
+- [x] **GitHub Actions Supply Chain Hardening (`.github/`)** — Action SHA pinning, least-privilege `contents: read`, and automated Zizmor CI gate.
+- [x] **Assertion Removal & Anti-Tamper Guard (`src/security.mjs`)** — Detects test deletion bypass (`ASSERTION_REMOVAL`) and vacuous assertion weakening.
+- [x] **Shannon Entropy Diff Scanner (`src/security.mjs`)** — High-entropy token detection (>4.5 entropy, $\ge 24$ chars) on added diff lines.
+- [x] **Jules API Patch Ingestion & Edge Webhooks (`src/session-ops.mjs`, `src/webhook.mjs`)** — API changeset extraction and Webhook `Uint8Array` Edge runtime parity.
+- [x] **Zero-Test Oracle Bootstrapping & Git Remote Origin Auto-Detection (`src/stack-detector.mjs`, `src/git.mjs`)** — Auto-configuration for virgin repositories.
+
+### v0.51.0: Mechanical Falsification, AST Mutation & V8 Coverage
+- [x] **Diff-Hunk Mutation Testing Engine (`src/mutation.mjs`, `agentctl mutate`)** — Transactional operator inversion with automatic shadow disk rollback.
+- [x] **Native V8 Diff Coverage Enforcer (`src/coverage.mjs`, `agentctl coverage`)** — Zero-dependency V8 coverage mapping against added `+` hunks.
+- [x] **Test-Oscillation Cycle Detector (`src/remediation.mjs`, `src/engine.mjs`)** — Halts multi-test oscillation cycles in OODA repair loops.
+- [x] **Flakiness Stability Prober & Event Loop Delay Guard (`src/stability.mjs`, `src/perf.mjs`)** — Multi-pass repetition probing and Big-O event loop delay monitor.
+
+### v0.40.0 – v0.50.0: Architecture Governance & Universal Envelopes
+- [x] **Universal Stack-Agnostic Task Templates (`src/web-templates.mjs`)** — Pre-calibrated templates for Cargo, Go, Python, PHP, .NET, Java, and Node.
+- [x] **Specialist Agent Roles (`.agent/prompts/`)** — Eight stack-neutral specialist personas with dynamic command hydration.
+- [x] **All-In-One CI Verification Gate (`agentctl check`)** — Unified security, scope, payload, and stack test gatekeeper.
+- [x] **Stack-Tailored Contract Scaffolding (`src/scaffold.mjs`)** — Automatic `SPEC.md`, `CONSTRAINTS.md`, and `DESIGN.md` generation on init.
+
+### v0.30.0 – v0.39.0: Budget Provenance, Terminal UX & Autonomous Resilience
+- [x] **Rolling 24h Budget Ledger & Limit Provenance (`src/budget.mjs`, `agentctl budget`)** — Multi-user attribution, rolling window accounting, and graceful estimate warnings.
+- [x] **Terminal UI Engine (`src/tui.mjs`, `src/key-decoder.mjs`)** — Zero-dependency interactive selection, multi-select, secret masking, and raw keyboard decoding.
+- [x] **Multi-OS CI Matrix Parity** — 100% green suite across Linux, macOS Darwin, and Windows CMD/PowerShell on Node 20, 22, and 24.
+- [x] **Atomic Git Checkpoint & Rollback (`src/ops/checkpoint.mjs`, `agentctl rollback`)** — Pre-flight working tree snapshots and 1-command git restore.
+- [x] **Documentation Sync Gate (`scripts/doc-sync-check.mjs`, `npm run jules:doc-sync`)** — Mechanical enforcement preventing documentation drift across manifests, roadmaps, and tests.
+
+---
+
+## 🎯 Target Milestones (v0.60.0 & v1.0.0)
+
+### v0.60.0: Distributed File Leases & Preemptive DAG Scheduling
+- [ ] **Atomic Filesystem Lease & Heartbeat Protocol (`src/engine.mjs`, `src/flaky-ledger.mjs`)** — Directory-mutex file leasing with heartbeat timestamps, stale-lock detection via PID liveness inspection, and tombstone rotation without third-party daemons or Redis.
+- [ ] **Preemptive Task Cancellation & Interface Fingerprints (`src/dag-engine.mjs`)** — Automatically aborts and yields downstream swarm tasks when upstream exported symbol interfaces diverge from their cryptographic SHA-256 fingerprints.
+- [ ] **POSIX/Win32 Process Group Guillotine (`src/engine.mjs`)** — Tree teardown via `process.kill(-pid, 'SIGKILL')` on POSIX and `taskkill /T /F /PID` on Windows to eliminate orphaned dev-servers and background watchers.
+- [ ] **Unicode Trojan Source & Homoglyph Fencing (`src/security.mjs`)** — Deterministic token scanner using V8 Unicode Property Escapes (`\p{Script=...}`) and NFKC normalization to block invisible Bidi overrides (CVE-2021-42574) and mixed-script homoglyphs.
+
+---
+
+## 🏁 Target Milestone v1.0.0: The Production-Grade Autonomous Engineering Kernel
+*Focus: Long-term API stability, cryptographic compliance, and enterprise deployment guarantees.*
+
+- [ ] **Cryptographic Compliance & SOC2 Audit Exporter (`agentctl audit export`)**:
+  - Export tamper-evident, signed JSON-LD / SPDX receipts of all agent activities linked to the SHA-256 telemetry ledger.
+  - *Foundation shipped:* `agentctl evidence generate|verify|show` (`src/evidence.mjs`) already produces SHA-256 evidence manifests with test-tamper locking.
+- [ ] **Zero-Dependency Core Freezing & Stability Guarantee**:
+  - 100% API stability for `index.mjs` SDK exports, CLI exit codes (0–8), and configuration schema (`.agent/config.yml`).
+- [ ] **High-Concurrency Swarm Benchmarking (500+ Daily Sessions)**:
+  - Stress testing with 50+ concurrent worker slots across 100k+ file repositories with zero lock contention or memory leaks.
+- [ ] **Comprehensive Multi-Language Enterprise Test Matrix**:
+  - Automated CI test fixtures for polyglot environments (Node, Python, Go, Rust, .NET, PHP, Java, Flutter).
+- [ ] **OODA Attempt Diff Retention & Inspection (`.agent/state/ooda/*.patch`, `agentctl patch --attempt <n>`)**:
+  - Retains intermediate working tree diffs and failure traces across OODA repair turns so developers can inspect failed hypotheses when an agent exhausts its retry budget.
+
+---
+
+## 🔮 Post-1.0 Long-Term Horizon (v1.x+)
+
+- **Proactive Telemetry Ingestion (Type III Situational Awareness)**: Ingest dev-server crash logs, APM traces, and Playwright test artifacts into auto-synthesized task envelopes for background diagnosis.
+- **Cross-Repository Swarm Orchestration**: Orchestrate breaking API contract changes across multiple distinct git repositories with atomic synchronization.
+- **Multimodal Visual Verification Loop**: Direct integration with headless browser video/screenshot streams for autonomous visual regression repairs.
+- **Wasm-Powered Structural AST Invariant Engine**: In-memory WebAssembly tree-sitter bindings (zero npm dependencies) for deep multi-language semantic AST verification.

package/bin/agentctl.mjs

@@ -383,6 +383,7 @@ async function main() {
           committed: { type: "boolean" },
           fix: { type: "boolean" },
           "allow-protected": { type: "boolean" },
+          "allow-unreadable-tests": { type: "boolean" },
           // The tamper guard has always had an override — `allowTestModifications`
           // — and it was reachable only from JavaScript. So a legitimate change
           // of spec, which necessarily rewrites what a test expects, hit a
@@ -413,6 +414,7 @@ async function main() {
         mode: selectedMode,
         fix: values.fix,
         allowProtected: values["allow-protected"],
+        allowUnreadableTests: values["allow-unreadable-tests"],
         allowTestModifications: values["allow-test-modifications"],
         allowTestChanges: values["allow-test-change"],
         jsonReport: values["json-report"],
@@ -1611,6 +1613,13 @@ async function main() {
         console.log(`   Stack detected : ${res.stack}`);
         console.log(`   Oracle TestCmd : ${res.testCmd}`);
         console.log(`   Config written : ${res.configPath}`);
+      } else if (res.reason === "NO_ORACLE_POSSIBLE") {
+        // Declining is a usable answer. Writing a config whose very first run
+        // asserts its own impossibility is not: it left the user following
+        // the gate's own repair advice into a dead end.
+        console.error(`❌ No oracle could be generated for this repository.`);
+        console.error(`   ${res.detail}`);
+        process.exit(1);
       } else {
         console.log(`ℹ️ Repository already has a verification oracle (${res.testCmd}). Use --force to overwrite.`);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.67.0",
+  "version": "0.69.0",
   "description": "Zero-dependency safety gatekeeper, test oracle generator, and multi-agent coordination protocol for autonomous coding agents — Google Jules, Claude Code, Codex and Gemini CLI.",
   "repository": {
     "type": "git",
@@ -32,7 +32,10 @@
     "JULES_RULES_TEMPLATE.md",
     ".agent/rules/",
     ".agent/prompts/",
-    ".agent/workflows/"
+    ".agent/workflows/",
+    "CHANGELOG.md",
+    "ROADMAP_V1.md",
+    "AGENTS.md"
   ],
   "scripts": {
     "init": "node bin/init.js",

package/scripts/doc-sync-check.mjs

@@ -331,6 +331,15 @@ function compareSemver(a, b) {
 
 // ---- CLI ----
 const isMain = process.argv[1] && process.argv[1].endsWith("doc-sync-check.mjs");
+// This gate compares the documentation against the test suite, which the
+// published package does not contain. Run from an installed copy it reported
+// six failures about files that were never meant to be there.
+if (isMain && !existsSync(join(process.cwd(), "test"))) {
+  console.error("Documentation sync is a release gate for the repository, not a check on an installed package.");
+  console.error("It compares README/ROADMAP/CHANGELOG against the test suite, which is not shipped.");
+  console.error("Clone the repository to run it. To check an installed copy, run: npm run guard-reach");
+  process.exit(1);
+}
 if (isMain) {
   const argv = process.argv.slice(2);
   const flag = (name) => {

package/src/config.mjs

@@ -626,7 +626,13 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
   const rawTeardown = parsed.teardown_cmd ?? parsed.verify?.teardown;
   const rawBuild = parsed.build_cmd ?? parsed.verify?.build;
   const rawUnit = parsed.verify?.unit;
-  const verifyTimeoutMs = parsed.verify?.timeoutMs ?? parsed.verify?.timeout_ms ?? 60000;
+  // Five minutes, matching the value `init` writes and the README documents.
+  // The engine carries the same number as a fallback, but this loader always
+  // supplies one — so the fallback never fired, and every repository without
+  // an explicit `timeout_ms` kept the old one-minute limit while the
+  // changelog said otherwise. The default has to live where the value is
+  // resolved, not where it is consumed.
+  const verifyTimeoutMs = parsed.verify?.timeoutMs ?? parsed.verify?.timeout_ms ?? 300_000;
   const autoVerify = resolveVerify(root);
 
   const rawTier = String(process.env.JULES_TIER || parsed.tier || FALLBACK_TIER).toLowerCase();
@@ -697,7 +703,7 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
       // Named so `doctor` can tell an operator that the gate they enabled is
       // running one fewer check than they think, and why.
       profileSkipped: profilePlan?.skipped ?? [],
-      timeoutMs: Number.isFinite(Number(verifyTimeoutMs)) ? Number(verifyTimeoutMs) : 60000,
+      timeoutMs: Number.isFinite(Number(verifyTimeoutMs)) ? Number(verifyTimeoutMs) : 300_000,
     },
     evidence: {
       enabled: parsed.evidence?.enabled ?? true,

package/src/engine.mjs

@@ -1,5 +1,6 @@
 import { loadConfig, parseYaml, normalizeScope } from "./config.mjs";
 import { isTestPath } from "./test-paths.mjs";
+import { isPlaceholderTestScript } from "./stack-detector.mjs";
 import { checkCollectionFloor } from "./ops/test-collection.mjs";
 import { checkScope, scanDiff, scanBinaryPayloads, redactSecrets } from "./security.mjs";
 import { changedFiles, diffBytes, diffText, binaryDiffEntries, symlinkChanges, showFromOrigin, runCmd } from "./git.mjs";
@@ -214,6 +215,7 @@ export async function gate(opts = {}) {
               : parsed.verify?.min_tests !== undefined
                 ? parsed.verify.min_tests
                 : config.verify.minTests,
+          tamperGuard: parsed.verify?.tamperGuard || parsed.verify?.tamper_guard || config.verify.tamperGuard,
           scope: parsed.verify?.scope || config.verify.scope || "global",
           timeoutMs: parsed.verify?.timeoutMs || parsed.verify?.timeout_ms || config.verify.timeoutMs,
         };
@@ -328,6 +330,11 @@ export async function gate(opts = {}) {
     root,
     allowTestModifications: opts.allowTestModifications === true,
     allowTestChanges: opts.allowTestChanges,
+    // Read from the base commit like every other trusted field: a repository
+    // opts out of the tamper guard deliberately and on the record, and an
+    // uncommitted edit must not be able to do it.
+    tamperGuard: trustedVerify.tamperGuard,
+    allowUnreadableTests: opts.allowUnreadableTests === true,
   });
   // A binary file reaches the scanner as one summary line, so its contents were
   // never looked at — a NUL byte in front of a token was enough to hide it.
@@ -386,7 +393,11 @@ export async function gate(opts = {}) {
   }
 
   let flakyVerdictResult = null;
-  const verifyTimeout = trustedVerify.timeoutMs || 60000;
+  // Five minutes. A minute was too short for an ordinary suite — a mid-sized
+  // Node repository takes longer than that on cold caches — and the timeout
+  // surfaced as a plain non-zero verification, so the gate told the user their
+  // tests failed when it had killed them. Raise it with verify.timeout_ms.
+  const verifyTimeout = trustedVerify.timeoutMs || 300_000;
 
   // Monorepo scoping: run the suites the change can actually break.
   //
@@ -588,7 +599,22 @@ export async function gate(opts = {}) {
     : { ok: true, count: null, runner: null, reason: null };
   const emptySuite = !collectionFloor.ok;
 
-  const verifyOk = !failingCmd && !testTampered && !missingOracle && !emptySuite;
+  // A command that cannot fail is not an oracle, wherever it is configured.
+  //
+  // `task create` already refuses one — "Unfalsifiable Task Rejected: Task
+  // must include a non-trivial verification test/build command" — while the
+  // gate approved against `verify.test: "true"` and printed an advisory. The
+  // same kit disagreed with itself about the same string. The collection
+  // floor cannot catch this: `true` states no count, and failing on "I could
+  // not tell" would break every unlisted runner. But a command that is
+  // *recognisably* a placeholder is not an unlisted runner.
+  const placeholderOracle =
+    verificationRequired &&
+    !missingOracle &&
+    Boolean(testResult?.command) &&
+    isPlaceholderTestScript(testResult.command);
+
+  const verifyOk = !failingCmd && !testTampered && !missingOracle && !emptySuite && !placeholderOracle;
 
   // What actually broke. Without this the verify phase reported `ok: false` and
   // nothing else — not the stage, not the exit code, not a line of output — so
@@ -635,7 +661,22 @@ export async function gate(opts = {}) {
               "The gate approves a change because verification passed. Zero stages executed is not a pass.",
             ],
           }
-        : emptySuite
+        : placeholderOracle
+          ? {
+              stageId: "placeholder-oracle",
+              command: testResult?.command || null,
+              exitCode: 0,
+              stdout: "",
+              stderr:
+                `The verification command is ${JSON.stringify(testResult.command)}, which cannot fail. ` +
+                "Nothing about this change was checked, so approving it would certify nothing. " +
+                "Point verify.test at a command that runs this repository's tests, or — if this repository " +
+                "intentionally uses only the scope and secret phases — set verify.required: false, which says so.",
+              diagnostics: [
+                "`agentctl task create` already refuses a task with this command; the gate now agrees with it.",
+              ],
+            }
+          : emptySuite
           ? {
               stageId: "empty-suite",
               command: testResult?.command || null,

package/src/git.mjs

@@ -15,6 +15,10 @@ export class GateError extends Error {
   }
 }
 
+// `NAME=value` at the head of a command line: a POSIX environment prefix,
+// not the name of a program.
+const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+
 const DEFAULT_TIMEOUT = 10 * 60 * 1000; // 10 minutes
 const DEFAULT_MAX_BUFFER = 10 * 1024 * 1024; // 10 MB
 
@@ -139,6 +143,8 @@ export function runCmd(command, opts = {}) {
   let args = [];
   let useShell = false;
   let shellCmd = "";
+  /** @type {Record<string,string>|null} */
+  let envOverlay = null;
   // True when `args` came from splitting a whitespace-separated string, which
   // means no element can itself contain whitespace. See the Windows note below.
   let tokenized = false;
@@ -153,6 +159,24 @@ export function runCmd(command, opts = {}) {
       shellCmd = trimmed;
     } else {
       const tokens = trimmed.split(/\s+/).filter(Boolean);
+
+      // A POSIX command may be prefixed with environment assignments, and
+      // half the Python world writes its test command exactly that way:
+      // `PYTHONPATH=src python3 -m pytest`. execFileSync took the first token
+      // as the program and failed with `spawnSync PYTHONPATH=src ENOENT` —
+      // which the gate then reported as a failed verification, so the user
+      // was told their tests broke when the command had never started.
+      //
+      // Peeling the assignments into the child's environment behaves the same
+      // on every platform. Handing the string to a shell would not: cmd.exe
+      // has no such syntax, so the Windows matrix would keep failing.
+      while (tokens.length > 1 && ENV_ASSIGNMENT.test(tokens[0])) {
+        const token = tokens.shift();
+        const eq = token.indexOf("=");
+        if (!envOverlay) envOverlay = {};
+        envOverlay[token.slice(0, eq)] = token.slice(eq + 1);
+      }
+
       binary = tokens[0] || "";
       args = tokens.slice(1);
       tokenized = true;
@@ -177,10 +201,12 @@ export function runCmd(command, opts = {}) {
   // wrapped in cmd.exe with every element quoted per the C-runtime + cmd.exe
   // rules, which preserves argv exactly while still letting the shell resolve
   // the `.cmd` shim (P-07).
+  const childEnv = envOverlay ? { ...(opts.env || process.env), ...envOverlay } : opts.env || process.env;
+
   const winShim = tokenized && process.platform === "win32";
   const winSpawn =
     !useShell && !winShim && process.platform === "win32"
-      ? resolveWindowsSpawn(binary, args, opts.env || process.env)
+      ? resolveWindowsSpawn(binary, args, childEnv)
       : null;
 
   if (!binary && !useShell) {
@@ -194,7 +220,7 @@ export function runCmd(command, opts = {}) {
           cwd,
           encoding: "utf-8",
           stdio: ["ignore", "pipe", "pipe"],
-          env: opts.env || process.env,
+          env: childEnv,
           timeout,
           maxBuffer,
         })
@@ -204,7 +230,7 @@ export function runCmd(command, opts = {}) {
           shell: winShim,
           windowsVerbatimArguments: Boolean(winSpawn && winSpawn.verbatim),
           stdio: ["ignore", "pipe", "pipe"],
-          env: opts.env || process.env,
+          env: childEnv,
           timeout,
           maxBuffer,
         });
@@ -218,8 +244,16 @@ export function runCmd(command, opts = {}) {
     let stdout = (err.stdout || "").toString().trim();
     let stderr = (err.stderr || err.message || "").toString().trim();
 
-    if (isTimeout && !stderr.includes("ETIMEDOUT")) {
-      stderr = `Command execution timed out after ${timeout}ms (ETIMEDOUT)${stderr ? "\n" + stderr : ""}`;
+    if (isTimeout) {
+      // Node's own message for this is `spawnSync sh ETIMEDOUT`, which already
+      // contains the token the old guard tested for — so the explanation was
+      // skipped exactly when it was needed, and the user was left with five
+      // words that name neither the limit nor the way to raise it.
+      stderr =
+        `Command execution timed out after ${timeout}ms (ETIMEDOUT). ` +
+        `The command was killed, not failed: raise verify.timeout_ms in ` +
+        `.agent/config.yml if this suite legitimately takes longer.` +
+        (stderr ? "\n" + stderr : "");
     }
     if (isNobufs && !stderr.includes("ENOBUFS")) {
       stderr = `Command output buffer exceeded limit of ${maxBuffer} bytes (ENOBUFS)${stderr ? "\n" + stderr : ""}`;