Crucible

Project page on Ghost Who Codes

Crucible is a Codex-first Java CLI for evidence-driven long-horizon work. The canonical durable work model is work .... The older task ... and watchdog ... commands remain available as compatibility and operator surfaces, but they should not be treated as separate lifecycle authorities.

Current surfaces:

• work ... is the canonical dossier and event model for new integrations
• watchdog ... is bounded evidence capture without dossier lifecycle state
• task ... is a deprecated legacy long-horizon harness

For the shortest workflow, start with QUICKSTART.md. For the full operator guide, see USAGE.md.

Crucible supports Linux and macOS. Windows is not supported.

Development

Crucible is a Maven project on JDK 25.

mvn clean verify

just ci runs the same repository verification entrypoint. The active CLI lives under src/main/java/.

Single-Root Workspaces

For the new work flow, workspace selection is wrapper-owned but still single-root:

• a wrapper may create or choose a dedicated checkout or worktree
• once selected, Crucible must be invoked against that checkout as the only root
• the chosen root must contain both WORKFLOW.md and docs/exec-plans/
• split-root syncing between one checkout for dossier files and another for code edits is intentionally unsupported

In practice, that means a wrapper should switch into the target worktree first, then run crucible work ... there. If a wrapper needs to stay outside the worktree, it may pass only --project-root pointing at that worktree.

Crucible treats the explicit --project-root checkout as the launch checkout. When --project-root is omitted, it falls back to the current shell checkout.

Do not reintroduce split-root work launches. If a dedicated worktree is needed, make it the only root that work prepare, work run, work inspect, work review, work reopen, branch merge, and work archive use.

Crucible also serializes checkout-scoped Codex runs. If work run, task run, task review, task escalate, or watchdog run / watchdog resume is already active in a checkout, a second run in that same checkout fails fast until the first one exits.

Core Model

• events.jsonl is the only durable machine authority for a work item.
• Crucible derives its reducer view in memory when commands run.
• Review.md is renderer-owned for work ...; the legacy task harness also renders Execution.md.
• Journal.md is the human-readable work log for work ....
• The accepted work ... source of truth is a cohesive Brief.md plus Contract.md pair, not milestone or phase authority.
• Plan.md is durable and advisory. It can drift as the agent learns, but that drift is diagnostic rather than a control-plane failure.
• Stable requirement IDs, validation IDs, governance artifact references, and reopen facts are part of the canonical work model.

Primary Workflow

Prefer work ... for new repository integrations and ongoing product work:

crucible --project-root /path/to/repo work create my-work \
  --brief docs/Brief.md \
  --contract docs/Contract.md \
  --policy ai/policy/greenfield.policy.md \
  --policy ai/policy/architectural-principles-ddd.policy.md
crucible --project-root /path/to/repo work plan my-work
crucible --project-root /path/to/repo work prepare my-work
crucible --project-root /path/to/repo work run my-work --review-budget 1
crucible --project-root /path/to/repo work inspect my-work
crucible --project-root /path/to/repo work review my-work
crucible --project-root /path/to/repo branch merge --work-id my-work --branch codex/my-work
crucible --project-root /path/to/repo work archive my-work

The canonical Contract.md for work ... should declare:

• ## Requirement IDs for durable outcome obligations
• ## Validation IDs with stable IDs mapped to executable commands
• optional ## Governance Artifacts for architecture or policy documents that native guards may require
• ## Completion Checklist for review and requirement obligations

Starter authoring examples live under docs/examples/work/.

During execution, Crucible records validation supersession, guard outcomes, and reopen facts append-only in events.jsonl. work inspect and work review render those named obligations rather than replaying free-form shell strings. work review also snapshots the reviewed validation evidence into docs/exec-plans/active/<work-id>/review-evidence/ so later merge and archive gates do not depend on ignored target/ artifacts. The independent review runs read-only by default, writes its JSON result in an isolated review-output directory, and is rejected if it mutates repository or dossier state. branch merge --work-id ... --json and work archive ... --json expose the same review-evidence assessment with stable issue codes for agent integrations.

The installed wrapper layer exposes the same canonical flow. The run wrapper already performs one independent review pass by default; use the review wrapper later only when you want to rerun that gate without another execution pass:

./<harness root>/agents/codex/create-long-horizon-work.sh \
  my-work \
  --brief docs/Brief.md \
  --contract docs/Contract.md
./<harness root>/agents/codex/prepare-long-horizon-work.sh my-work
./<harness root>/agents/codex/run-long-horizon-work.sh my-work
./<harness root>/agents/codex/merge-work-branch.sh my-work --branch codex/my-work
./<harness root>/agents/codex/archive-long-horizon-work.sh my-work

./<harness root>/agents/codex/review-long-horizon-work.sh my-work

When human review reopens the work, keep the repair loop in work ...:

crucible --project-root /path/to/repo work reopen my-work \
  --summary "Human review requested one more repair pass." \
  --finding "Encode the missing invariant in a focused regression test."

Add --run-repair-loop when the same command should immediately launch the prepared repair pass. Otherwise Crucible prints the next work run command.

Legacy Task Workflow

task ... is deprecated. It remains available only for legacy harness consumers or migration work:

crucible --project-root /path/to/repo task adapt-proposal --source docs/raw.md --output-dir docs/task-proposal
crucible --project-root /path/to/repo task init my-task \
  --proposal-dir docs/task-proposal \
  --policy ai/policy/greenfield.policy.md \
  --policy ai/policy/architectural-principles-ddd.policy.md
crucible --project-root /path/to/repo task plan my-task
crucible --project-root /path/to/repo task checkout my-task --worktree
crucible --project-root /path/to/repo task prepare my-task
crucible --project-root /path/to/repo task run my-task --mode auto
crucible --project-root /path/to/repo task checkpoint my-task
crucible --project-root /path/to/repo task review my-task
crucible --project-root /path/to/repo branch merge my-task
crucible --project-root /path/to/repo task archive my-task

task adapt-proposal survives as a migration helper for old proposal-driven task scaffolds. New work ... flows should start directly from Brief.md and Contract.md.

Current Surfaces

Use work ... when you want the canonical dossier and engine model:

• WORKFLOW.md and docs/exec-plans/ as the primary repo contract
• bounded iterative execution in one shared engine
• append-only validation, reopen, repair-loop, and guard evidence in events.jsonl
• deterministic work prepare, independent work review, and explicit merge/archive gates keyed by stable IDs

Use task ... only when you still need the full audited legacy harness during an explicit migration window:

• task-local Prompt.md, Completion.md, optional Policy.md, Plan.md, Implement.md, Execution.md, Review.md, and events.jsonl
• events.jsonl as the only durable machine authority
• deterministic checkout, preflight, bounded execution, final review, merge, and archive gates

Use watchdog ... when you want bounded autonomous continuation without the task-local lifecycle surface:

• repo-addressed task input from a task or brief markdown file
• bounded repeated execution with wrapper-owned stop decisions
• per-iteration diff, validation, inspection, review, repair, and audit artifacts under target/codex-watchdog/runs/<run-id>/
• no merge automation and no model-authored lifecycle authority

Work Runtime Boundaries

The work ... runtime keeps a hard ownership split between four internal modules:

• WorkDispatchService owns launch eligibility, clean-tree preflight, repository/workspace/run provenance, latest-run selection, and handoff into the shared engine.
• RunEvidenceRecorder owns dossier snapshots, validation and guard event ordering, reopen reasons, run.json, and final engine.run.recorded emission.
• ReviewEvidenceAuthority owns durable review-readiness assessment for merge and archive, including source-branch provenance and required-validation snapshot rules.
• WorkflowContractSchema owns WORKFLOW.md parsing, defaults, allowed values, effective validation specs, and effective handoff rules.

Native Guards

Workflow contracts may enable native guard modules under ## Guard Modules. The first shipped guard is architecture_guard.

When enabled, architecture_guard blocks candidate completion for architecture-sensitive repository changes unless at least one declared governance artifact was updated in the same bounded run. Guard evidence is based on files touched by the executor; stale dirty files present before execution and validation side effects do not satisfy the guard.

If you provide an explicit watchdog completion contract, its policy and requirement obligations are treated as part of the captured snapshot and will block terminal completion until a later run captures updated task/contract inputs with those obligations resolved.

Example watchdog flow:

crucible --project-root /path/to/repo watchdog run \
  --task docs/watchdog-task.md \
  --policy ai/policy/greenfield.policy.md \
  --check "mvn -q -DskipTests test" \
  --max-iterations 3
crucible --project-root /path/to/repo watchdog report \
  --run-dir target/codex-watchdog/runs/<run-id>
crucible --project-root /path/to/repo watchdog resume \
  --run-dir target/codex-watchdog/runs/<run-id> \
  --max-iterations 5

Historical product-proof walkthroughs live in:

• ai/archived/demos/STRICT_HARNESS_DEMO.md
• ai/archived/demos/WATCHDOG_DEMO.md

Dossier Contract

The accepted operator-facing Brief.md and Contract.md pair should describe:

• the desired change
• the intended outcome
• stable requirement IDs when the task benefits from explicit obligation tracking
• hard constraints and repo boundaries
• relevant context or references
• validation expectations when known

Crucible rejects proposal documents that treat milestones, phases, or ordered implementation slices as operator-facing contract authority.

Execution Policy

Model policy lives in execution_policy.

work ... uses WORKFLOW.md execution defaults for the coding pass and accepts explicit review overrides such as --review-model and --review-reasoning-effort. execution_policy is still primarily for legacy task/adaptation surfaces.

Example:

{
  "execution_policy": {
    "default": {
      "model": "gpt-5.4",
      "reasoning_effort": "xhigh"
    },
    "adapt_proposal": {
      "model": "gpt-5.4-mini",
      "reasoning_effort": "medium"
    },
    "task_review": {
      "model": "gpt-5.4",
      "reasoning_effort": "high"
    }
  }
}

Repo policy layers through the managed base, installed template, and repo-local override stack.

Reusable Policy Files

Reusable work policy belongs in markdown policy files passed with repeated --policy flags on work create, task init, and watchdog run.

This is meant for cross-task constraints that should outlive any one brief, such as greenfield vs brownfield rules, migration layout rules, or durable architectural principles.

Crucible snapshots those files into the local work surface so later planning, execution, review, and resume prompts do not depend on the original file locations. The current snapshot artifact is:

• docs/exec-plans/active/<work-id>/Policy.md for work ...
• <task_root>/<task-slug>/Policy.md for task ...
• target/codex-watchdog/runs/<run-id>/Policy.md for watchdog ...

The current markdown format recognizes:

• ## Must
• ## Must Not
• ## Checklist

When multiple policy files are supplied, Crucible rejects direct contradictions between ## Must and ## Must Not items before execution starts.

An ordinary repo layout might keep source policies under ai/policy/, but the source path is operator-chosen; only the snapshotted Policy.md artifact is part of Crucible's local runtime surface.

Deterministic Gates

• work create seeds the canonical dossier from Brief.md, Contract.md, and optional reusable policy files.
• work plan prints the current advisory Plan.md.
• work prepare is the deterministic preflight for dossier, workspace, runtime, prompt-contract readiness, effective validation IDs, and operator-facing merge commands.
• work run owns one bounded execution pass; --review-budget adds wrapper-owned independent review relaunches without moving lifecycle authority into the model.
• work resume uses the same shared engine path as work run after a prior incomplete or reopened run.
• work reopen records human review findings as durable repair context for the next run and can immediately launch that repair loop with --run-repair-loop.
• work review is the final independent review gate for outcome, validation, and merge readiness, with durable validation artifacts as the evidence base.
• branch merge --work-id ... --branch ... is gated by git facts plus the latest merge-ready independent review.
• work archive is the post-merge or post-handoff dossier move.
• task checkout owns branch and optional worktree setup in the deprecated legacy harness.
• task prepare is a launch preflight that validates the legacy task stack, branch assumptions, Codex availability, required runtime assets, and obvious repo-adaptation drift before bounded execution starts.
• task run owns one bounded execution pass and a narrow run-result contract in the legacy harness.
• task checkpoint is deterministic reconciliation, not model-authored state regeneration.
• task review is the single final human review gate for outcome, validation, and merge readiness, with durable validation artifacts as the evidence base.
• watchdog run, watchdog resume, and watchdog report provide a separate bounded continuation line with saved inspection, review, repair, and audit artifacts but no durable lifecycle state authority.
• branch merge is gated by git facts plus the latest merge-ready final review.
• task archive is a post-merge doc move.