jules-orchestrator-kit 0.66.0 → 0.68.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 **1133 unit tests across 163 suites passing in < 15.0s**.
+* **Verified Test Suite:** Tested with **1163 unit tests across 166 suites passing in < 15.0s**.
 
 <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) |

package/ROADMAP_V1.md

@@ -0,0 +1,202 @@
+# 🗺️ 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.68.0 (Current Stable) ──► v0.69.0 (Distributed Swarms & Leases) ──► v1.0.0 (Production Hardened Kernel)
+ (Can It Still Go Red?)      (Multi-Agent DAG & Resource Locks)        (Enterprise Telemetry & SLA)
+```
+
+---
+
+## ✅ Shipped Milestones (v0.20.0 – v0.68.0)
+
+
+### 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"],
@@ -425,7 +427,17 @@ async function main() {
         console.log(`-----------------------------------------------------`);
         for (const p of res.phases) {
           const status = p.ok ? "✅ PASS" : "❌ FAIL";
-          console.log(`  Phase [${p.phase.toUpperCase()}] : ${status}`);
+          // Test tampering shares this phase, and its exit code, with the
+          // secret scanner. The codes are frozen, but reporting an assertion
+          // deletion under a bare "SECRETS" heading sent operators looking for
+          // a credential to rotate. Name what actually failed.
+          const tamperOnly =
+            p.phase === "secrets" &&
+            !p.ok &&
+            (p.findings || []).length > 0 &&
+            (p.findings || []).every((f) => f.type !== "SECRET_DETECTED" && !/SECRET/i.test(f.type || ""));
+          const label = tamperOnly ? "SECRETS (test integrity — no secret found)" : p.phase.toUpperCase();
+          console.log(`  Phase [${label}] : ${status}`);
           if (p.violations) {
             p.violations.forEach((v) => console.log(`     - Violation: ${v.file} (Rule: ${v.rule})`));
           }
@@ -1601,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.66.0",
+  "version": "0.68.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/scripts/guard-reach-check.mjs

@@ -56,6 +56,7 @@ import {
   SCOPE_CANARIES,
   INNOCENT_EDITS,
   UNREADABLE_DIALECTS,
+  CROSS_FILE_CASES,
 } from "../src/guard-policy.mjs";
 
 /**
@@ -185,6 +186,29 @@ const canaryResults = new Map();
   );
 }
 
+{
+  const wrong = [];
+  for (const c of CROSS_FILE_CASES) {
+    const lines = [];
+    for (const f of c.files) {
+      lines.push(`--- a/${f.file}`, `+++ b/${f.file}`, "@@ -1,20 +1,20 @@", ` ${c.context}`);
+      for (const l of f.removed) lines.push(`-${l}`);
+      for (const l of f.added) lines.push(`+${l}`);
+      lines.push(` ${c.context}`);
+    }
+    const got = (checkTestTampering(lines.join("\n")).violations || []).map((v) => v.type).sort();
+    const want = [...c.expect].sort();
+    if (JSON.stringify(got) !== JSON.stringify(want)) {
+      wrong.push(`${c.id}: got ${JSON.stringify(got)}, policy says ${JSON.stringify(want)} (${c.why})`);
+    }
+  }
+  add(
+    "a move across files is judged as a move",
+    wrong.length === 0,
+    wrong.length ? wrong.join("; ") : `${CROSS_FILE_CASES.length} two-file diffs judged as declared`
+  );
+}
+
 // --- 4. Predicate mutants ---------------------------------------------------
 {
   const survivors = [];

package/scripts/run-tests.mjs

@@ -1,11 +1,28 @@
 #!/usr/bin/env node
-import { readdirSync } from "node:fs";
+import { readdirSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import { cpus } from "node:os";
 
 const root = process.cwd();
 const testDir = join(root, "test");
+
+// The published package ships `scripts/` and not `test/`, so running
+// `npm test` inside an installed copy crashed with a raw
+// `ENOENT: no such file or directory, scandir '.../test'`. The suite is not
+// missing; it was never part of the tarball. Say that, rather than leaving
+// someone to work it out from a stack trace.
+if (!existsSync(testDir)) {
+  console.error("No test/ directory here.");
+  console.error("");
+  console.error("If this is an installed copy of jules-orchestrator-kit, that is expected:");
+  console.error("the test suite is not part of the published package. Clone the repository");
+  console.error("to run it:  git clone https://github.com/FullThrottle83/jules-orchestrator-kit");
+  console.error("");
+  console.error("To check an installed copy instead, run:  npm run guard-reach");
+  process.exit(1);
+}
+
 const testFiles = readdirSync(testDir)
   .filter((f) => f.endsWith(".test.mjs"))
   .sort()

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.
@@ -588,7 +595,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 +657,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/guard-policy.mjs

@@ -235,6 +235,94 @@ export const TAMPER_CANARIES = [
     added: ["        $this->markTestSkipped(\"later\");"],
     expect: "TEST_SKIP_INJECTION",
   },
+  // Dialects a second cold-start trial found silent. chai's `.to.equal(` is a
+  // dot chain where RSpec's is a space, so the RSpec branch never reached it;
+  // node-tap's assertions hang off whatever the sub-test callback named its
+  // argument, which is `ct` as often as `t`.
+  {
+    id: "weakening/chai",
+    file: "packages/core/test/signal.test.tsx",
+    context: "// signals",
+    removed: ["    expect(s.value).to.equal(v);"],
+    added: ["    expect(s.value).toBeDefined();"],
+    expect: "ASSERTION_WEAKENED",
+  },
+  {
+    id: "expectation/chai",
+    file: "test/signal.test.js",
+    context: "// signals",
+    removed: ["    expect(s.value).to.equal(3);"],
+    added: ["    expect(s.value).to.equal(-1);"],
+    expect: "ASSERTION_EXPECTATION_CHANGED",
+  },
+  {
+    id: "expectation/node-tap",
+    file: "tests/test-config.js",
+    context: "// config",
+    removed: ["    ct.equal(process.env.BASIC, 'basic')"],
+    added: ["    ct.equal(process.env.BASIC, 'BROKEN_OVERRIDE')"],
+    expect: "ASSERTION_EXPECTATION_CHANGED",
+  },
+  {
+    id: "skip-injection/node-tap-options",
+    file: "tests/test-populate.js",
+    context: "// populate",
+    removed: ["t.test('does not write over keys', ct => {"],
+    added: ["t.test('does not write over keys', { skip: true }, ct => {"],
+    expect: "TEST_SKIP_INJECTION",
+  },
+  // Skipping from inside the test body, which is how every one of these
+  // ecosystems actually does it. The decorator and annotation forms were
+  // covered; the standard library's own method was not, so a test could be
+  // silenced with the most ordinary call in the language.
+  {
+    id: "skip-injection/unittest-body",
+    file: "tests/test_app.py",
+    context: "# app",
+    removed: [],
+    added: ['        self.skipTest("disabled")'],
+    expect: "TEST_SKIP_INJECTION",
+  },
+  {
+    id: "skip-injection/pytest-body",
+    file: "tests/test_app.py",
+    context: "# app",
+    removed: [],
+    added: ['    pytest.skip("not now")'],
+    expect: "TEST_SKIP_INJECTION",
+  },
+  {
+    id: "skip-injection/raise-skiptest",
+    file: "tests/test_app.py",
+    context: "# app",
+    removed: [],
+    added: ['    raise unittest.SkipTest("nope")'],
+    expect: "TEST_SKIP_INJECTION",
+  },
+  {
+    id: "skip-injection/mocha-body",
+    file: "test/app.test.js",
+    context: "// app",
+    removed: [],
+    added: ["  this.skip();"],
+    expect: "TEST_SKIP_INJECTION",
+  },
+  {
+    id: "skip-injection/jest-todo",
+    file: "test/app.test.js",
+    context: "// app",
+    removed: [],
+    added: ['  test.todo("adds two numbers");'],
+    expect: "TEST_SKIP_INJECTION",
+  },
+  {
+    id: "skip-injection/go-skipnow",
+    file: "internal/calc/calc_test.go",
+    context: "// calc",
+    removed: [],
+    added: ["\tt.SkipNow()"],
+    expect: "TEST_SKIP_INJECTION",
+  },
   {
     id: "skip-injection/xctest",
     file: "Tests/CalcTests/CalcTests.swift",
@@ -391,6 +479,15 @@ export const INNOCENT_EDITS = [
     added: ["    3, // the correct answer", "  );"],
     why: "line comments were never stripped — `copyCode(i)` left `pending` at the comment and the copy after the loop put it back",
   },
+  {
+    id: "reformat-assertion-multiline/python",
+    file: "tests/test_encoding.py",
+    context: "# encoding",
+    lead: ["def test_int_bytes(value, expect):", "    enc = int_to_bytes(value)"],
+    removed: ["    assert enc == expect"],
+    added: ["    assert (", "        enc == expect", "    )"],
+    why: "Black and Ruff do this; `assert (` alone on a line names no value, so a line-level count read a reformat as a weakening",
+  },
   {
     id: "rename-helper/node",
     file: "test/calc.test.js",
@@ -551,3 +648,57 @@ export const MULTILINE_CANARIES = [
     expect: "ASSERTION_EXPECTATION_CHANGED",
   },
 ];
+
+/**
+ * Diffs that touch two files at once, where the verdict depends on both.
+ *
+ * Assertion tracking is per file, so moving a test between files — ordinary
+ * refactoring, done constantly — read as deleting every assertion in it and
+ * was reported as CRITICAL tampering. The assertion still exists and still
+ * runs. What the removal check is for is verification that *disappeared*.
+ *
+ * `expect: []` means the whole diff must produce no finding.
+ */
+export const CROSS_FILE_CASES = [
+  {
+    id: "move-a-test-between-files",
+    context: "# ctx",
+    files: [
+      {
+        file: "test/test_app.py",
+        removed: ["    def test_setattr(self):", "        self.assertEqual(5, app.test)", "        self.assertRaises(AttributeError, setattr, app, 't', 6)"],
+        added: [],
+      },
+      {
+        file: "test/test_html.py",
+        removed: [],
+        added: ["    def test_setattr_moved(self):", "        self.assertEqual(5, app.test)", "        self.assertRaises(AttributeError, setattr, app, 't', 6)"],
+      },
+    ],
+    expect: [],
+    why: "a move is not a removal",
+  },
+  {
+    id: "delete-a-test-outright",
+    context: "# ctx",
+    files: [
+      {
+        file: "test/test_app.py",
+        removed: ["    def test_setattr(self):", "        self.assertEqual(5, app.test)", "        self.assertRaises(AttributeError, setattr, app, 't', 6)"],
+        added: [],
+      },
+    ],
+    expect: ["ASSERTION_REMOVAL", "ASSERTION_REMOVAL"],
+    why: "nothing caught it on the way, so verification really did disappear",
+  },
+  {
+    id: "change-it-on-the-way-across",
+    context: "# ctx",
+    files: [
+      { file: "test/test_app.py", removed: ["        self.assertEqual(5, app.test)"], added: [] },
+      { file: "test/test_html.py", removed: [], added: ["        self.assertEqual(99, app.test)"] },
+    ],
+    expect: ["ASSERTION_REMOVAL"],
+    why: "what arrived is a different claim; only an exact arrival is a move",
+  },
+];