feat: upgrade Codex plugin to RLCR v2

Author: jake

.github/workflows/codex-plugin.yml

@@ -22,6 +22,17 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
+      - name: Install development checks
+        run: python3 -m pip install pyright==1.1.411 ruff==0.16.2
+
+      - name: Lint and check formatting
+        run: |
+          ruff check .
+          ruff format --check .
+
+      - name: Type-check controller
+        run: pyright
+
       - name: Run native RLCR tests
         run: python3 tests/test-codex-native-rlcr.py
 
@@ -31,10 +42,11 @@ jobs:
           python3 -m json.tool plugins/jakeshea-humanize-rlcr/.codex-plugin/plugin.json >/dev/null
           python3 -m json.tool plugins/jakeshea-humanize-rlcr/hooks/hooks.json >/dev/null
           python3 -m json.tool plugins/jakeshea-humanize-rlcr/schemas/review-v1.json >/dev/null
+          python3 -m json.tool plugins/jakeshea-humanize-rlcr/schemas/plan-contract-v1.json >/dev/null
 
       - name: Check controller syntax
         run: |
           python3 -m py_compile \
             plugins/jakeshea-humanize-rlcr/controller/*.py \
             plugins/jakeshea-humanize-rlcr/scripts/rlcr.py \
-            plugins/jakeshea-humanize-rlcr/skills/humanize-rlcr/scripts/rlcr.py
+            plugins/jakeshea-humanize-rlcr/skills/*/scripts/rlcr.py

NOTICE.md

@@ -10,6 +10,15 @@ The repository descends from:
   its upstream plugin metadata.
 - GAAC (GitHub-as-a-Context), credited by the upstream Humanize project.
 
+The v2 redesign also studied `humanfia/humanize2` at commit
+`72bfb030d423eaecb2ec7589c000483320cfc95e` (Apache-2.0) on 2026-08-26. Its
+layering, flow/session, cycle persistence, resuming, reporting, tracing, and
+security documentation informed the architecture decision in
+`docs/adr/0001-humanize2-pattern-adoption.md`. No Humanize2 source code,
+assets, dependency, or executable flow was copied into this plugin; the v2
+controller is an independent MIT implementation of selected public design
+ideas.
+
 The former Claude Code, Kimi, Gemini, BitLesson, monitoring, and dashboard
 implementation was removed from the `for-codex-plugin-only` branch after the
 native Codex plugin became self-contained. Original authorship and the complete

README.md

@@ -1,7 +1,9 @@
 # JakeShea Humanize RLCR
 
 A personal, Codex-only fork of Humanize for bounded plan implementation with
-independent review loops.
+independent review loops. Version 2 selectively adopts Humanize2's layered
+run/cycle, resumability, focused-flow, and traceability patterns while keeping a
+smaller fail-closed Codex plugin boundary.
 
 This repository is not the official PolyArch Humanize distribution. Its Codex
 identities are deliberately namespaced to avoid collisions with any future
@@ -10,6 +12,8 @@ official plugin:
 - Plugin: `jakeshea-humanize-rlcr`
 - Marketplace: `jakeshea-humanize`
 - Skill: `$jakeshea-humanize-rlcr:humanize-rlcr`
+- Planning skill: `$jakeshea-humanize-rlcr:humanize-plan`
+- Review-only skill: `$jakeshea-humanize-rlcr:humanize-review`
 
 ## What RLCR does
 
@@ -24,7 +28,20 @@ the same committed artifact:
 
 Both lanes must accept the same immutable artifact digest. Blocking findings
 become a continuation prompt; Codex corrects them, commits, and stops again.
-The loop is bounded by review rounds, calls, failures, timeouts, and wall time.
+The loop is bounded by review rounds, calls, failures, timeouts, wall time, and
+measured Codex token usage.
+
+RLCR v2 additionally provides:
+
+- optional `rlcr.plan.v1` contracts whose required criteria are checked by the
+  controller;
+- named deterministic evidence bound to the exact candidate commit;
+- independent per-lane caching, so a valid lane is not rerun when its peer
+  fails transiently;
+- typed failures, safe live-review cancellation, explicit session adoption,
+  and one-way v1 history migration;
+- recoverable hash-chained events, run history, Markdown/JSON reports, and
+  Chrome/Perfetto traces.
 
 ## Requirements
 
@@ -33,18 +50,62 @@ The loop is bounded by review rounds, calls, failures, timeouts, and wall time.
 - Git.
 - Python 3.10 or newer. Windows hooks use the standard `py -3` launcher.
 
-## Install this checkout
+## Install or upgrade the plugin
+
+The plugin is published by this repository's `jakeshea-humanize` marketplace.
+The current release has version prefix `0.2.0+codex.`; the suffix is a cache
+stamp that changes whenever the local plugin is rebuilt.
+
+### First install from a local checkout
+
+Register the repository marketplace once, then install the plugin:
 
 ```bash
 codex plugin marketplace add /absolute/path/to/humanize
 codex plugin add jakeshea-humanize-rlcr@jakeshea-humanize
 ```
 
-Open a new Codex conversation, run `/hooks`, inspect and trust the bundled
-hook, then invoke:
+Verify that Codex reports it as installed and enabled:
+
+```bash
+codex plugin list --json
+```
+
+### First install directly from GitHub
+
+```bash
+codex plugin marketplace add JakeFlasher/humanize --ref for-codex-plugin-only
+codex plugin add jakeshea-humanize-rlcr@jakeshea-humanize
+```
+
+### Upgrade an existing installation
+
+Finish or cancel an active RLCR run before upgrading because an in-flight run
+intentionally refuses changed controller semantics. For a local checkout, pull
+or edit the source and reinstall its cache-stamped snapshot:
+
+```bash
+git pull --ff-only
+codex plugin add jakeshea-humanize-rlcr@jakeshea-humanize
+codex plugin list --json
+```
+
+Do not add the marketplace again if `codex plugin marketplace list` already
+shows `jakeshea-humanize`. For a Git-backed marketplace, refresh it first:
+
+```bash
+codex plugin marketplace upgrade jakeshea-humanize
+codex plugin add jakeshea-humanize-rlcr@jakeshea-humanize
+```
+
+After either installation or upgrade, open a **new Codex conversation** so the
+new skills and hook snapshot are loaded. Run `/hooks`, inspect and trust the
+bundled Stop hook, then invoke one of the explicit skills:
 
 ```text
 $jakeshea-humanize-rlcr:humanize-rlcr implement path/to/plan.md
+$jakeshea-humanize-rlcr:humanize-plan create a plan and contract for this change
+$jakeshea-humanize-rlcr:humanize-review review this committed change against path/to/plan.md
 ```
 
 For installation from another machine, update, removal, and troubleshooting,
@@ -57,11 +118,11 @@ see [Install for Codex](docs/install-for-codex.md).
 plugins/jakeshea-humanize-rlcr/
 ├── .codex-plugin/plugin.json          Plugin identity and UI metadata
 ├── hooks/hooks.json                   Native synchronous Stop hook
-├── controller/                        State machine, review runner, storage
+├── controller/                        Layered state, policy, evidence, review, reporting
 ├── prompts/                           Independent reviewer lane prompts
-├── schemas/review-v1.json             Structured reviewer output contract
+├── schemas/                           Review and plan-contract schemas
 ├── scripts/rlcr.py                    Direct controller entrypoint
-└── skills/humanize-rlcr/              Explicit Codex skill and wrapper
+└── skills/                             Plan, review-only, and full-loop skills
 tests/test-codex-native-rlcr.py         Protocol, concurrency, and safety tests
 ```
 
@@ -76,6 +137,9 @@ ${JAKESHEA_HUMANIZE_RLCR_STATE_HOME:-${XDG_STATE_HOME:-~/.local/state}/jakeshea-
 
 ```bash
 python3 tests/test-codex-native-rlcr.py
+ruff check .
+ruff format --check .
+pyright
 python3 -m json.tool .agents/plugins/marketplace.json >/dev/null
 ```
 
@@ -96,18 +160,28 @@ codex plugin add jakeshea-humanize-rlcr@jakeshea-humanize
   neutralized before trusted Git reads.
 - Plan, schema, prompt, manifest, and cumulative patch snapshots are integrity
   checked before and after review.
+- Start commit ancestry is enforced, and plan contract, run configuration,
+  evidence manifest, and cumulative patch all contribute to artifact identity.
+- Evidence commands run as explicit argv without a shell, at a clean commit;
+  failed, stale, missing, or tampered records cannot authorize review.
+- Live cancellation uses attempt-scoped process registrations and
+  PID-reuse-resistant kernel identities before signaling a process group.
 - Hooks are guardrails, not a complete isolation boundary. The two reviewers
   use independent contexts but the same model family; deterministic tests and
   human judgment remain necessary.
 - Strict mode currently blocks repositories containing Git submodules.
 
-See [Architecture](docs/architecture.md) for the state machine and trust model.
+See [Architecture](docs/architecture.md) for the state machine and trust model,
+[the Humanize2 adoption ADR](docs/adr/0001-humanize2-pattern-adoption.md) for
+the merge decision, [research foundations](docs/research-foundations.md) for
+the paper-to-control mapping, and [the v2 migration guide](docs/migration-v2.md)
+for upgrades.
 
 ## Provenance and license
 
 This personal fork descends from PolyArch Humanize, which itself credits the
-GAAC project. The prior Claude Code implementation was removed from this branch
-after the Codex-native plugin became self-contained; it remains recoverable in
-Git history. See [NOTICE](NOTICE.md).
+GAAC project. Humanize2 was studied at a pinned Apache-2.0 revision, but no
+Humanize2 source was copied or linked into this MIT plugin. See
+[NOTICE](NOTICE.md).
 
 Licensed under the [MIT License](LICENSE).

docs/adr/0001-humanize2-pattern-adoption.md

@@ -0,0 +1,70 @@
+# ADR 0001: Selective Humanize2 pattern adoption
+
+- Status: Accepted
+- Date: 2026-08-26
+- Decision owners: JakeShea Humanize RLCR maintainers
+
+## Context
+
+The prior Humanize repository stopped being the active design center. Its
+successor, [humanfia/humanize2](https://github.com/humanfia/humanize2), is a
+new Python orchestration product with flows, multiple agent backends, machines,
+providers, resumable cycles, a TUI, and trace collection. This plugin is much
+narrower: it is a personal Codex-only completion gate driven by one native Stop
+hook.
+
+Research and comparison were performed against Humanize2 commit
+[`72bfb030d423eaecb2ec7589c000483320cfc95e`](https://github.com/humanfia/humanize2/commit/72bfb030d423eaecb2ec7589c000483320cfc95e),
+authored 2026-08-26. The source at that revision is Apache-2.0. The review
+covered its normative specifications, layer rules, flow/session model,
+concurrency, cycle persistence, resuming, security, reporting, and tracing.
+
+## Decision
+
+Adopt concepts that strengthen a bounded Codex plugin while implementing them
+independently in the existing standard-library controller:
+
+| Humanize2 pattern | RLCR v2 application |
+| --- | --- |
+| Named layers with a directed dependency graph | Domain, configuration, contracts, consensus, evidence, processes, review, storage, reporting, and CLI modules |
+| A run captures what it drives before the first turn | Immutable `rlcr.run-config.v1` snapshot and digest |
+| Concurrent work means independent sessions | Two fresh reviewer processes, one per named lane, launched concurrently |
+| A cycle is an inspectable directory | Private per-run snapshots, rounds, evidence, hash-chained events, history, and reports |
+| Resuming is explicit persisted state | Typed phases, crash recovery, infrastructure resume, and explicit session adoption |
+| Trace output is portable | Chrome/Perfetto JSON export from controller events |
+| Focused flows carry focused skills | Separate explicit plan, review-only, and full RLCR skills |
+| Agent capabilities are checked before work | Codex CLI flag preflight and immutable model/effort policy |
+
+Preserve or strengthen the original plugin boundaries:
+
+- reviewers receive a controller-materialized cumulative patch, not a mutable
+  flow definition;
+- repository content is evidence and never executable orchestration;
+- reviewer children are read-only, approval-free, strict-configured, and have
+  hooks, plugins, apps, skills, subagents, image generation, browser use, and
+  web search disabled;
+- deterministic evidence is explicit argv execution at a clean commit and is
+  cryptographically bound to that commit;
+- acceptance remains controller-owned exact consensus, never model prose.
+
+## Deliberately not adopted
+
+- Executable Python flows or third-party flow repositories. Loading repository
+  orchestration code would violate this plugin's untrusted-repository model.
+- Multi-provider accounts, dynamic model discovery, or cross-model fallback.
+  RLCR intentionally pins `gpt-5.6-sol:xhigh`; silent fallback would change the
+  review policy mid-run.
+- Remote anchors, containers, a TUI, telemetry, or unattended general-purpose
+  agent execution. They are outside a local completion-gate plugin's scope.
+- Humanize2 source code or package dependencies. The implementation is a
+  clean-room adaptation of public design ideas, remains MIT, supports Python
+  3.10+, and uses only the standard library at runtime.
+
+## Consequences
+
+The controller has more modules and persisted metadata, but its trust boundary
+is narrower and more auditable. Older run snapshots remain readable through a
+one-way migration view; active runs still refuse a changed runtime and must be
+restarted. The two lanes reduce single-context failure but do not provide
+model-family diversity, so deterministic checks and human judgment remain
+release requirements.