{"id":50949989,"url":"https://github.com/scottconverse/agent-pipeline-codex","last_synced_at":"2026-06-18T00:30:55.153Z","repository":{"id":357254123,"uuid":"1236052768","full_name":"scottconverse/agent-pipeline-codex","owner":"scottconverse","description":"Codex Desktop App plugin for manifest-driven multi-stage agentic pipeline runs","archived":false,"fork":false,"pushed_at":"2026-05-24T19:58:05.000Z","size":1207,"stargazers_count":3,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-24T21:26:03.207Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://scottconverse.github.io/agent-pipeline-codex/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scottconverse.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-11T22:55:13.000Z","updated_at":"2026-05-24T19:57:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/scottconverse/agent-pipeline-codex","commit_stats":null,"previous_names":["scottconverse/agent-pipeline-codex"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/scottconverse/agent-pipeline-codex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottconverse%2Fagent-pipeline-codex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottconverse%2Fagent-pipeline-codex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottconverse%2Fagent-pipeline-codex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottconverse%2Fagent-pipeline-codex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scottconverse","download_url":"https://codeload.github.com/scottconverse/agent-pipeline-codex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottconverse%2Fagent-pipeline-codex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34471638,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-18T00:30:54.675Z","updated_at":"2026-06-18T00:30:55.124Z","avatar_url":"https://github.com/scottconverse.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-pipeline-codex\n\n[![CI](https://github.com/scottconverse/agent-pipeline-codex/actions/workflows/ci.yml/badge.svg)](https://github.com/scottconverse/agent-pipeline-codex/actions/workflows/ci.yml)\n\nA Codex Desktop App plugin that orchestrates multi-stage agentic work: **manifest -\u003e research -\u003e plan -\u003e test-write -\u003e execute -\u003e policy -\u003e verify -\u003e drift-detect -\u003e critique -\u003e auto-promote -\u003e manager**, with human-approval gates at manifest, plan, and manager-decision (the last auto-fires on clean runs at v0.5+). Built from real lessons across CivicCast, CivicSuite, AgentSuiteLocal and other projects where autonomous agent runs go wrong silently and \"manager-PROMOTE\" failures slip past CI.\n\n**Current release: v0.9.1** (baseline isolation for release-rehearsal failures and hangs). [CHANGELOG](CHANGELOG.md) | [User Manual](USER-MANUAL.md) | [Architecture](ARCHITECTURE.md) | [Landing page](https://scottconverse.github.io/agent-pipeline-codex/) | [Discussions](https://github.com/scottconverse/agent-pipeline-codex/discussions)\n\n## Why this plugin exists\n\nAgentic work fails in predictable ways:\n\n- The agent doesn't understand the project's conventions, so it improvises and the work silently diverges from the spec.\n- The agent claims tests pass without running them against a fresh dependency set.\n- The agent merges in-flight work while a scope question is open.\n- The agent picks architectural decisions silently rather than surfacing them.\n\nThis plugin enforces a structural pattern that catches every one of those:\n\n1. **Manifest + scope-lock gate** - every run starts with an explicit, human-approved manifest plus a scope lock naming the canonical release-plan rung, proof statement, allowed terms, and forbidden future-rung terms.\n2. **Director-decisions gate** - the researcher surfaces open questions; the human picks; choices are recorded as binding constraints before the planner runs.\n3. **Plan gate** - the planner produces a plan; the human approves or sends back.\n4. **Execute readiness gate** - before the runner may advance from execute to policy/verify, `implementation-report.md` must prove the full manifest Definition of Done is ready, not merely that a backend or test slice passed. The report needs a machine-readable `**DoD readiness: READY**` line and a zero-blocker DoD checklist covering expected outputs, DoD clauses, project UX/docs/testing gates, and prior blockers.\n5. **Policy stage** - automated checks block the run if the manifest fails strict schema validation (v0.5), the scope lock disagrees with the canonical release plan (v0.5.9), execute readiness is missing or blocked, any change falls outside `allowed_paths`, edited paths or commit messages belong to another rung, docs contradict the locked rung, the diff contains TODO/FIXME/HACK markers, or an existing ADR was modified.\n6. **Verifier stage** - independent fresh-context check against every manifest exit criterion.\n7. **Manager gate** - final PROMOTE/BLOCK/REPLAN decision, must cite verifier evidence verbatim.\n\n8. **Control-loop gate** - before any final response, stop, deferral, or skipped action during an authorized run, `.agent-runs/\u003crun-id\u003e/active-control-state.md` must record a valid stop condition, `scripts/policy/check_pipeline_control_loop.py --run \u003crun-id\u003e` must pass, `scripts/policy/final_response_gate.py --require-active-run` must print `final_response_gate: ALLOW`, and `scripts/policy/agent_decision_gate.py` must allow the specific decision through the shared `stop_validator.py`. Green CI, successful push, draft PR status, stale state, unverified blocker risk, and a recommended next action are not stop conditions.\n\n## Install\n\nInstall through the Codex Desktop App plugin flow once the repository is published, or clone it locally and add the local path to your Codex plugin configuration:\n\n```bash\ngit clone https://github.com/scottconverse/agent-pipeline-codex.git ~/agent-pipeline-codex-plugin\n```\n\nBefore calling the plugin installed, run the release verifier and prove the\nCodex runtime can see it:\n\n```bash\npython scripts/verify_plugin_release.py --live\n```\n\nThat gate must print `PLUGIN-RELEASE-VERIFY: PASSED`, including the nested\n`PLUGIN-INSTALL-ACCEPTANCE: PASSED` live check. Repository tests, standalone\nskill copies, and docs deployment are not install proof.\n\nThe live gate first verifies deterministic source and installed-cache state,\nthen runs repeated fresh Codex probes. One transient model enumeration miss is\npreserved in the transcript but does not fail the release if another fresh\nprobe sees the complete namespaced plugin surface and no plugin-specific loader\nwarning appears.\n\nFresh-session prompts must verify the namespaced plugin skills, not only the\nstandalone skill names. The expected names are:\n\n- `agent-pipeline-codex:agent-pipeline`\n- `agent-pipeline-codex:intake`\n- `agent-pipeline-codex:pipeline-init`\n- `agent-pipeline-codex:new-run`\n- `agent-pipeline-codex:run-pipeline`\n- `agent-pipeline-codex:audit-init`\n- `agent-pipeline-codex:show-run-status`\n- `agent-pipeline-codex:validate-manifest`\n\nIf a session only sees `agent-pipeline`, `pipeline-init`, or `run-pipeline`\nwithout the `agent-pipeline-codex:` prefix, it may be seeing stale standalone\nskills under `$CODEX_HOME/skills`; that is not proof the current plugin is\nactive.\n\nFor headless CI that cannot see the local Codex Desktop registry, use the\nsource-only gate:\n\n```bash\npython scripts/verify_plugin_release.py --source-only\n```\n\n## First use in a new project\n\nDrop into the project root (or a fresh empty directory) and ask Codex to use the `pipeline-init` skill:\n\n```\nUse pipeline-init for this project.\n```\n\nThe plugin asks one question - what do you have? - and accepts one of three inputs:\n\n1. **A PRD or spec document.** Paste the path or contents. The plugin reads it, derives the project's conventions, scaffolds `AGENTS.md` + `.pipelines/` + `scripts/policy/` + a `.gitignore` entry, and produces a project-orientation summary.\n2. **A repo URL** (or a local path to an existing repo). The plugin clones (or reads), inspects `README`, `AGENTS.md`, `pyproject.toml` / `package.json`, `.github/workflows/`, `docs/adr/`, and recent commits. Produces a project-orientation summary, flags missing pieces, installs `.pipelines/` + `scripts/policy/`.\n3. **A project description paragraph or two.** Plugin reads it, asks \"scaffold a new project from this, or use as context for an existing repo?\" and routes to (1) or (2) accordingly.\n\nAfter init, your project has:\n\n```\n.pipelines/\n|-- feature.yaml                    # stage sequence for new functionality\n|-- bugfix.yaml                     # stage sequence for bug fixes\n|-- module-release.yaml             # six-phase release pipeline (v0.2+)\n|-- manifest-template.yaml          # blank template with field docs\n|-- scope-lock-template.yaml        # blank canonical rung/scope lock\n|-- directive-template.yaml         # optional v0.6 directive contract template\n|-- action-classification.yaml      # opt-in: enables the v0.4 judge layer\n|-- self-classification-rules.md    # pre-authorized cases the executor handles solo\n`-- roles/\n    |-- researcher.md\n    |-- planner.md\n    |-- test-writer.md\n    |-- executor.md                 # has the v0.5 pre-edit fact-forcing gate\n    |-- verifier.md                 # emits v0.5 parseable criteria count line\n    |-- drift-detector.md           # v0.5 - manifest contract vs assembled state\n    |-- critic.md                   # v0.5 - adversarial cold read, six lenses\n    |-- manager.md                  # v0.5 auto-promote-aware\n    |-- judge.md                    # v0.4 - used only when judge layer is opt-in\n    |-- preflight-auditor.md        # v0.2 module-release Phase 0\n    |-- local-rehearsal.md          # v0.2 module-release Phase 2\n    |-- cross-agent-auditor.md      # v0.3 audit-handoff\n    `-- implementer-pre-push.md     # v0.3 audit-handoff\nscripts/policy/\n|-- check_manifest_schema.py        # v0.5 - strict manifest contract validator\n|-- check_scope_lock.py             # v0.5.9 - canonical rung lock validator\n|-- check_directive_conformance.py  # v0.6 - manifest/scope directive conformance\n|-- check_plan_against_directive.py # v0.6 - plan assertion auto-approval gate\n|-- check_allowed_paths.py          # generic, manifest-driven\n|-- check_rung_file_ownership.py    # v0.5.9 - future-rung path/commit blocker\n|-- check_release_docs_consistency.py # v0.5.9 - docs vs release-plan consistency\n|-- final_response_gate.py          # pre-final continuation gate\n|-- agent_decision_gate.py          # stop/skip/defer decision gate + ledger\n|-- pipeline_continue.py            # executable next-action navigator\n|-- stop_validator.py               # v0.5.10 - shared stop-condition truth validator\n|-- check_decision_ledger.py        # schema validator for decision-ledger.ndjson\n|-- show_run_status.py              # read-only run state summary\n|-- check_no_todos.py               # generic, configurable scan dirs\n|-- check_adr_gate.py               # generic, ADRs are append-only\n|-- auto_promote.py                 # v0.5 - six-condition machine-checkable promote\n`-- run_all.py                      # runner\n.agent-runs/                        # gitignored - pipeline run artifacts\nhooks/                               # plugin-bundled v0.7 lifecycle hooks\n```\n\n## v0.8.0: Intake drafting\n\nIf you know the work in plain English but do not have a manifest yet, start\nwith the separate intake skill:\n\n```\nUse intake for Add account deletion to settings, including tests, docs, and a clear rollback path.\n```\n\n`intake` creates draft run artifacts and stops. It does not validate the\nmanifest, approve scope, run agents, or start implementation. It writes:\n\n- `intake.md` - the verbatim source description plus conservative interpretation\n- `manifest.yaml` - a draft manifest with uncertain scope left as TODOs\n- `scope-lock.yaml` - a draft scope lock that refuses to invent release-plan authority\n- `intake-questions.md` - missing answers that must be resolved before validation\n\nThe hard boundary is unchanged: draft intake is not approval. The next step is\nto complete the TODOs and run `agent-pipeline-codex:validate-manifest`; only\nthen should `agent-pipeline-codex:run-pipeline` start.\n\n## v0.9.0: Persistent run memory\n\nThe trusted hook layer now includes a file-backed memory foundation for active\nruns. When hooks can identify `.agent-runs/\u003crun-id\u003e/active-control-state.md`,\nthey write compact receipts under:\n\n```text\n.agent-runs/\u003crun-id\u003e/memory/\n|-- events.jsonl          # all memory-worthy hook events\n|-- turns.jsonl           # user prompts submitted during the active run\n|-- decisions.jsonl       # tool warnings, denials, and approval decisions\n|-- open_loops.jsonl      # failed-tool guidance and invalid-stop continuations\n|-- memory_probe.log      # proof that hooks fired and saw the run\n`-- handoff_current.md    # compact wake-up summary regenerated from JSONL\n```\n\n`SessionStart` injects `handoff_current.md` alongside the active run context on\nthe next startup/resume, so a new Codex session wakes up with the run state,\nrecent warnings, open loops, and resume checklist without depending on chat\nmemory. This is deliberately local and deterministic: no daemon, no vector\ndatabase, and no external service are required.\n\nThe JSONL files are memory receipts, not approval authority. Before relying on\nremembered state, re-run the relevant manifest, scope, directive, policy, or\nrelease checks. A future optional adapter can mirror these receipts into a\nlocalmem MCP server for semantic search and longer-term retention, but the\nbuilt-in memory layer stands on its own.\n\n## v0.9.1: Baseline isolation for release rehearsal\n\n`local-rehearsal.md` now inserts Step 2.5 after the local `verify-release.sh`\nrun. On any failure or hang, the role requires a quick branch-vs-merge-base\ncheck before deeper debugging so the agent can tell whether it is fixing its\nbranch or chasing a pre-existing main-branch flake.\n\n`verifier.md` cross-references the same rule when a verifier test run fails or\nhangs in a way the implementation report did not show. The durable behavior is\nrole text, not a chat-side reminder.\n\n## Running a pipeline\n\nOnce a project is initialized:\n\n```\nUse intake for Add account deletion to settings with tests and docs.\n                                           # draft intake.md + manifest/scope-lock\nUse new-run for feature my-task-slug.      # initialize blank manifest + scope-lock skeletons\n                                           # (you fill in both, then:)\nUse validate-manifest for 2026-05-09-my-task-slug.\n                                           # fix schema issues before agent work starts\nUse run-pipeline for feature 2026-05-09-my-task-slug.\n                                           # orchestrates the full sequence,\n                                           # stops at human gates and on failure,\n                                           # resumable from .agent-runs/\u003crun-id\u003e/run.log\nUse show-run-status for 2026-05-09-my-task-slug.\n                                           # read-only status when you need orientation\n```\n\nThree human-approval gates per run: manifest, plan, manager-decision. Each is a one-question prompt: APPROVE or describe what should change.\n\nBefore starting a run, validate the manifest and scope lock with the same\nchecks used by the policy stage:\n\n```bash\npython scripts/policy/validate_manifest.py --run 2026-05-09-my-task-slug\npython scripts/policy/check_scope_lock.py --run 2026-05-09-my-task-slug\n```\n\nThe validators report exact violations and the fix path before the pipeline\nspends agent time on a fuzzy manifest or the wrong canonical rung.\n\n## v0.2: The `module-release` pipeline\n\nFor work whose end-state is a published release artifact (module version bump, dependency migration), use `module-release` instead of `feature`. It adds two stages that prevent the most expensive class of failure: cascading discovery of pre-existing CI infrastructure bugs during the remote release run.\n\n```\nUse new-run for module-release my-module-v1.2.0-migration.\nUse run-pipeline for module-release 2026-05-11-my-module-v1.2.0-migration.\n```\n\nThe pipeline runs six phases:\n- **Phase 0 - Preflight auditor.** Audits the module's release workflow before any product code is touched. YAML parse, workflow run health, referenced scripts exist, local `verify-release.sh` on fresh state, cross-platform reality check, diagnostic instrumentation, audit-punchlist correlation. Bugs found are bundled into ONE PR. See `pipelines/roles/preflight-auditor.md`.\n- **Phase 1 - Scoped product work.** The executor role with pre-authorized self-classification rules (LIVE-STATE / FROZEN-EVIDENCE / SHAPE-GUARD / OWN-MODULE-VERSION for grep hits; MECHANICAL-CI-BUG / CONTRACT-CHANGE / ENVIRONMENTAL / NOVEL for failures) so the agent doesn't halt-and-ask on routine cases. See `pipelines/self-classification-rules.md`.\n- **Phase 2 - Local release rehearsal.** Mirrors the CI environment and runs the release sequence locally on fresh state before tag push. The workflow becomes the *execution* mechanism, not the *discovery* mechanism. See `pipelines/roles/local-rehearsal.md`.\n- **Phase 3 - Remote release + umbrella reconciliation.** Tag push, release workflow watch, umbrella PR through the project's release-lockstep gate.\n- **Phase 4 - Verifier.** Independent fresh-context check of all release artifacts and durable docs.\n- **Phase 5 - Manager.** Final PROMOTE/BLOCK/REPLAN with verifier evidence cited verbatim.\n\nHuman gates at Phase 0 results review, Phase 2 rehearsal-ok, and Phase 5 release-ok.\n\n**Operator reference:** `docs/module-release-handbook.md` covers initial setup, expected timing per sprint type, and an honest \"what this pipeline does NOT prevent\" section. Originating failure receipts are documented in the handbook so future operators understand why each stage exists.\n\n## v0.3: Dual-AI audit-handoff discipline\n\nFor projects where one AI implements and a second AI audits, v0.3 adds a complementary discipline that catches drift the pipeline doesn't:\n\n```\nUse audit-init for this project.\n```\n\nThis scaffolds three artifacts:\n1. `\u003cPROJECT\u003e_AUDIT_GATE.md` (out-of-repo) - short mandatory gate the auditing agent reads every verification turn.\n2. `\u003cPROJECT\u003e_AUDIT_PROTOCOL.md` (out-of-repo) - long reference protocol with the 10-section output shape, status-word rules, and a known drift patterns catalog.\n3. `\u003cproject\u003e/docs/process/5-lens-self-audit.md` (in-repo, via PR) - shared discipline both agents read. The implementer runs a hostile 5-lens self-audit before every push (Engineering / UX / Tests / Docs / QA), plus a post-push SHA-propagation step.\n\nPlus per-agent wiring (Codex project instructions feedback file on the Codex side; the equivalent project-context or skill-registration mechanism on the other AI's side) so each agent reads the right artifact on session start.\n\nThe discipline is symmetric - any AI can play either role. The plugin runs in Codex Desktop App; the second AI can be any tool that exposes a project-context or standing-instructions surface.\n\n**Stacking with v0.2:**\n- Pipeline (v0.2) catches execution-cascade failures: pre-existing CI bugs, tag-move dances, halt-and-ask loops.\n- Audit-handoff (v0.3) catches drift failures: wrong endpoint, stale CHANGELOG, \"Closed\" without evidence, status-word abuse.\n\nThe two address different failure modes. Use both for projects with two AI systems.\n\n**Operator reference:** `docs/audit-handoff-handbook.md`.\n\n## v0.4: Judge layer\n\nReal-time action-level supervision **inside** the executor stage. This is not a new pipeline stage; it is opt-in infrastructure that intercepts the executor's tool calls, classifies each one by risk, and spawns a judge subagent for the dangerous ones. Built from the Lindy case study (May 2026, Nate Jones, \"LLM-as-Judge\"): an agent that sent 14 unauthorized emails because manual confirmation prompts had trained the operator to click \"okay\" reflexively. Prompts don't hold across long context; the architectural fix is a second agent whose sole loyalty is the manifest.\n\n```\n# Opt in by creating .pipelines/action-classification.yaml in your project.\n# The orchestrator detects the file at run start and uses Handler 3a\n# (classify -\u003e judge -\u003e execute) instead of Handler 3 for the executor stage.\n# No other commands change.\n```\n\n### What it does\n\nEvery tool call the executor proposes is classified against `.pipelines/action-classification.yaml` and routed by risk class:\n\n- `read_only` (e.g. `cat`, `grep`, `git log`) -\u003e execute + log.\n- `reversible_write` (e.g. `str_replace_editor`, `git commit`, `cp`) -\u003e execute + log.\n- `external_facing` (e.g. `git push` to non-main, `gh pr create`, `curl -X POST`) -\u003e STOP, spawn judge.\n- `high_risk` (e.g. `rm -rf`, `git push --force`, `git push main`, `DROP TABLE`, `npm publish`) -\u003e STOP, spawn judge, and require human confirm even after the judge ALLOWs.\n\n### The four verdicts\n\nThe judge subagent receives the manifest, the matched action policy, prior judge decisions for this run, and the structured action proposal - but **not** the executor's internal reasoning chain. Context isolation is the mechanism: the judge cannot be persuaded by the same chain of inferences that produced the over-broad action.\n\n- **`allow`** - within scope, evidence supports the justification. Proceed.\n- **`block`** - outside scope, violates policy, or unsupported by evidence. Halt.\n- **`revise`** - legitimate basis, wrong form. Send concrete revision instruction back to the executor (e.g. \"push to feature branch, not main\"). Max 3 revision cycles per action; auto-escalate after.\n- **`escalate`** - requires human judgment (money, credentials, legal, or judge confidence \u003c 0.7). Pipeline pauses for a specific human question.\n\n### Two new artifacts per run (when judge layer is active)\n\n- **`judge-log.yaml`** - chronological log of every action: tool, arguments, class, disposition (auto_allow / judged_allow / judged_revise / judged_block / judged_escalate / human_confirmed / human_blocked), judge reason, revision instruction. Verifier and manager read this.\n- **`judge-metrics.yaml`** - counts by class and disposition, `escalation_rate`, `judge_invocations`, `revision_cycles`. The escalation rate is the operator's tuning signal - too low means rules too permissive, too high means trust is being eroded by reflexive APPROVE clicking.\n\n### Opt-in by file presence\n\nIf `.pipelines/action-classification.yaml` does not exist in your project, the executor stage runs exactly as in v0.3 and earlier - no judge, no `judge-log.yaml`, no behavioral change. The presence of the file at run start opts that run into the judge layer. Operators choose whether to enable it per-project (or per-branch, since it's a file in the repo).\n\n**Stacking with v0.2 and v0.3:**\n\n- Pipeline (v0.2) catches execution-cascade failures - pre-existing CI bugs, tag-move dances, halt-and-ask loops.\n- Audit-handoff (v0.3) catches drift failures - wrong endpoint, stale CHANGELOG, status-word abuse.\n- **Judge layer (v0.4) catches unauthorized actions in real time** - destructive commands, external writes, force pushes, and credential-touching operations evaluated against the manifest at the action boundary instead of after the fact.\n\n**Operator reference:** USER-MANUAL.md Section \"The judge layer (v0.4)\".\n\n## v0.7.0: Hooked pipeline autonomy\n\nv0.7.0 adds optional Codex lifecycle hooks. When Codex is configured with\n`[features].plugin_hooks = true`, the plugin can add active-run context at\nsession start, warn on stale standalone skill names, preflight risky tool\ncalls, deny clearly unsafe approval requests, add corrective context after\nfailed tools, and continue instead of stopping when `active-control-state.md`\nsays the run is not at a valid stop condition.\n\nHooks do not replace the directive contract, judge layer, policy scripts, or\nhuman fallback gates. They move existing pipeline discipline closer to Codex's\nruntime lifecycle. The default mode is warn/context; hard blocks are limited to\nconcrete safety violations such as destructive commands, force pushes, secret\nexposure, out-of-scope active-run writes, and invalid pipeline stops.\n\nLocal hooks work with a normal signed-in Codex session. Codex access tokens are\ndocumented only for ChatGPT Business and Enterprise workspaces, so they are\noptional for CI automation and not required for local Max/Pro-style operation.\n\n## v0.5: Single-AI hardened\n\nSix structural changes that make the pipeline run with **one AI** while still blocking drift and rogue-agent failures. Built from the design question: \"can the pipeline do both action-level judge AND post-hoc audit with one AI?\" Answer is yes - at the cost of accepting some correlated single-model-family blind spots, with explicit mitigations.\n\n### What changed\n\n- **Critic stage** (`pipelines/roles/critic.md`) - adversarial cold read of every artifact in a fresh context. Walks six lenses (engineering, UX, tests, docs, QA, scope). Emits a parseable `**Findings:**` count line. Structural substitute for cross-family verification.\n- **Drift-detector stage** (`pipelines/roles/drift-detector.md`) - compares manifest contract against assembled final state. Catches durable doc drift, status-word abuse, cross-file inconsistency, ledger top-totals vs row counts. Emits parseable `**Drift:**` count line.\n- **Pre-edit fact-forcing in executor** - before the first edit per file, the executor must produce importers/callers, public API affected, schema, and the manifest goal quoted verbatim. Forces investigation that catches blast-radius surprises before they hit the verifier.\n- **Expanded judge classification** - five new `high_risk` patterns: `npm install -g`, `sudo`, non-editable non-user `pip install`, `git commit` with BREAKING in message.\n- **Machine-checkable auto-promote** (`scripts/auto_promote.py`) - six conditions checked from the artifact stack: verifier-clean, critic-clean, drift-clean, policy-passed, judge-clean, tests-passed. When all six pass, the manager gate auto-fires; when any fails, the human gate remains.\n- **Strict manifest schema validation** (`scripts/check_manifest_schema.py`) - minimum-length `goal` and `definition_of_done`, non-empty `expected_outputs` / `non_goals` / `rollback_plan`, forbidden status words banned from manifest contracts, broad `allowed_paths` requires non-empty `forbidden_paths`. Fuzzy manifests fail at the start of the run, not after they cascade.\n\n### How the pipeline shape changes\n\nPre-v0.5: `manifest -\u003e research -\u003e plan -\u003e test-write -\u003e execute -\u003e policy -\u003e verify -\u003e manager`\n\nv0.5: `manifest -\u003e research -\u003e plan -\u003e test-write -\u003e execute -\u003e policy -\u003e verify -\u003e drift-detect -\u003e critique -\u003e auto-promote -\u003e manager`\n\nThe new three stages add ~10-20 minutes of wall-clock per run depending on artifact size. The auto-promote stage typically lands the manager decision in \u003c30 seconds when the six conditions are green, eliminating the third human gate on clean runs.\n\n### Honest limit\n\nSingle-model-family blind spots correlate. If both the executor and the critic share a wrong assumption that fits the manifest, both sign off and auto-promote fires green. Dual-AI (v0.3) is the only structural defense against this. **Recommended mitigation:** periodic sample audit by a different model family on a weekly cadence. The v0.3 `audit-init` discipline still applies; v0.5 does not replace it.\n\n### Stacking with v0.2, v0.3, v0.4\n\n- v0.2 catches execution-cascade failures (pre-executor).\n- v0.3 catches drift failures via cross-family audit (post-executor, separate session).\n- v0.4 catches unauthorized actions in real time (during executor).\n- **v0.5 catches the drift class without needing a second AI** (during verify -\u003e drift-detect -\u003e critique -\u003e auto-promote).\n\nThe four stack. Most projects run v0.4 + v0.5 by default and reach for v0.3 when they have two model families available.\n\n**Operator reference:** USER-MANUAL.md Section \"v0.5 single-AI hardening\" + ARCHITECTURE.md Section 8 \"Single-AI hardening (v0.5)\".\n\n## v0.6.0: Directive contracts\n\nv0.6.0 closes the directive-conformant re-approval loop. Operators can add\n`.agent-runs/\u003crun-id\u003e/directive.yaml` before a run to pre-declare the exact\nmanifest, exact scope lock, plan acceptance assertions, and manager acceptance\nassertions. The runner binds the directive hash into `run.log`, auto-approves\nthe manifest and plan gates only when on-disk artifacts mechanically conform,\nand extends auto-promote from six conditions to six plus the directive's\nmanager assertions.\n\nManual fallback is preserved: absent directives, malformed directives,\nmismatches, failed assertions, and hash tampering keep or restore the existing\ninteractive gate. Judge-layer high-risk confirmations and `escalate` prompts\nremain human surfaces because a directive cannot know future tool calls.\n\n## v0.5.10: Evidence-bound stop validation\n\nv0.5.10 closes the stale-control-state escape hatch by centralizing stop\ntruth in `stop_validator.py`. `final_response_gate.py`,\n`pipeline_continue.py`, and `agent_decision_gate.py` now call the same validator\ninstead of each trusting `active-control-state.md` independently. Human gates\nare valid only at manifest, plan, or manager stages; failed-gate stops must be\nbacked by current `run.log` evidence when a log exists; stale scope-repair\nstates cannot authorize stopping after a passing `scope-lock-receipt.txt`; and\nunrecorded blocker claims require an evidence file, not just plausible text.\n\n## v0.5.9: Canonical rung authority\n\nv0.5.9 adds the missing guard between \"the agent is authorized to continue\"\nand \"the agent is working on the right thing.\" A run now carries\n`.agent-runs/\u003crun-id\u003e/scope-lock.yaml`, which binds the work to a specific\nsection of the canonical release plan. The policy stage blocks missing locks,\nrelease-plan mismatches, future-rung paths, contradictory docs, and commit\nsubjects that belong to another rung.\n\nBefore starting rung work from a prompt, the orchestrator runs:\n\n```bash\npython scripts/policy/agent_decision_gate.py --run \u003crun-id\u003e --intent start_rung_work --claimed-rung \u003crung\u003e --prompt-text \"\u003cuser wording\u003e\"\n```\n\nIf the user says \"Begin v0.6 publish-dashboard work\" while the release plan\nsays v0.6 is \"Summary + signed records,\" the gate returns `SCOPE_CONFLICT`.\nThe agent stops before edits and requires an explicit scope amendment. It may\nnot infer that the release ladder changed.\n\n## What this plugin will NOT do\n\n- It will not propose broad autonomous mode. Hooks add guardrails around explicit pipeline authority; every gate remains explicit or mechanically directive-bound.\n- It will not silently expand scope. The policy stage blocks any change outside `allowed_paths`.\n- It will not silently change rungs. The scope-lock gates block prompt, path, docs, and commit-message conflicts with the canonical release plan.\n- It will not skip tests. AGENTS.md hard-rule \"never skip tests\" is enforced as a project default.\n- It will not promote a run if the verifier marked any criterion NOT MET. Manager hard rule.\n\n## Project-specific customization\n\nAfter `pipeline-init`, the files installed in your repo are yours to edit. Add project-specific policy checks alongside the generic ones (e.g., a CivicCast-style `check_ffmpeg_wrapper.py`). Customize the role files to reference your project's specific ADRs, AGENTS.md sections, test patterns. The plugin's workflow skills work against whatever's in your repo's `.pipelines/` and `scripts/policy/` directories.\n\n## Documentation\n\n- `skills/*/SKILL.md` - Codex skill entrypoints for onboarding, new-run, validation, run-pipeline, status, and audit-init\n- `commands/pipeline-init.md` - the full onboarding workflow logic\n- `commands/new-run.md` - the run-init workflow logic\n- `commands/validate-manifest.md` - manifest schema preflight\n- `commands/run-pipeline.md` - the orchestrator workflow logic (includes v0.4 Handler 3a judge interception and v0.5 Handler 4 auto-promote-aware manager)\n- `commands/show-run-status.md` - read-only run status workflow\n- `commands/audit-init.md` - scaffolds the v0.3 dual-AI audit-handoff infrastructure\n- `pipelines/roles/*.md` - what each role does, what's forbidden\n- `pipelines/manifest-template.yaml` - every manifest field with inline docs\n- `pipelines/scope-lock-template.yaml` - canonical rung/scope lock template\n- `scripts/auto_promote.py` - v0.5 six-condition promote-eligibility checker (`--version` to confirm release)\n- `scripts/check_manifest_schema.py` - v0.5 manifest validator (`--version` to confirm release)\n- `scripts/check_scope_lock.py` - canonical release-plan rung validator\n- `scripts/check_rung_file_ownership.py` - future-rung path and commit-subject blocker\n- `scripts/check_release_docs_consistency.py` - docs vs locked rung consistency gate\n- `scripts/validate_manifest.py` - standalone manifest preflight wrapper for source and scaffolded projects\n- `scripts/check_decision_ledger.py` - schema-v1 decision-ledger validator\n- `scripts/show_run_status.py` - read-only status summary over run.log and active-control-state\n- `.pipelines/templates/workflow-cost-directives.md` - canonical GitHub Actions cost-discipline contract\n- `USER-MANUAL.md` - end-to-end operator reference, every command + gate + troubleshooting case\n- `ARCHITECTURE.md` - diagrams, file layout, artifact data flow, extension points\n- `CHANGELOG.md` - every release with rationale, what changed, what didn't\n\n## Lessons baked in\n\nThis plugin's defaults reflect failures from prior projects. Notably:\n\n- Halts apply to ALL repo state changes, including in-flight cleanup work\n- Auto mode never overrides explicit stops\n- \"Tests pass locally\" is not evidence; CI on a fresh dep set is\n- Manifest amendments are corrections, not expansions, and the pattern of needing them means the manifest template should use directory-level path granularity for same-module test paths\n- The manager must cite verifier evidence verbatim; encouragement and summarization are forbidden in the role file\n\n## License\n\nApache 2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscottconverse%2Fagent-pipeline-codex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscottconverse%2Fagent-pipeline-codex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscottconverse%2Fagent-pipeline-codex/lists"}