oh-my-copilot 5.5.0 → 5.6.2

package/docs/HOOKS.md

@@ -399,6 +399,24 @@ or
 
 `cancel` removes state files for all active modes: ralph, autopilot, team, and any others; it also clears legacy/retired `ultrawork` state.
 
+#### Git Guardrails (`git-guardrails.mjs`)
+
+A PreToolUse hook (matcher: `Bash`) that checks shell command positions and blocks destructive Git operations from agent-driven Bash calls with an authority message. It scans commands separated by shell chains and newlines, so a destructive command is still blocked when it follows a safe command. Quoted arguments and ordinary text commands such as `echo git push` are not mistaken for Git invocations. Git's global options before the subcommand are skipped, including `-C <dir>`, `-c key=value`, `--git-dir`/`--work-tree` (in `=` or separate-word form), `--no-pager`/`-P`, and the other flags `git help git` lists, so `git --no-pager push` is blocked like `git push`.
+
+- **Enable**: Set `OMC_GIT_GUARDRAILS=1` to enable in any session. The guard also auto-enables when the canonical state resolver finds an active ralph, autopilot, team, or ultragoal state owned by the current session. If the payload has no session ID, auto-enable fails open rather than borrowing another session's legacy state. `OMC_GIT_GUARDRAILS=0` disables both activation paths; otherwise the hook fails open when no active mode is found.
+- **Blocked operations**: non-dry-run `git push`, `git reset --hard`, non-dry-run `git clean -f/--force`, forced branch deletion (`git branch -D`, `-d --force`, or `--force --delete` in either order), and `git checkout .` / `git checkout -- .` or `git restore .` (working-tree discard). The hook ignores Git option-looking arguments after `--`; those are refspecs or pathspecs, not options.
+- **Safe operations**: `git push --dry-run` / `git push -n`, clean dry-runs (`git clean -n`, including `git clean -n -- -f`), soft resets, non-forced branch deletes (`-d`), and path-specific checkout/restore commands such as `git checkout ./path` and `git restore ./file` pass. Malformed, absent, or command-less payloads fail open. An unset guard variable outside an active mode also fails open after a bounded stdin read; explicit `=0` exits before reading stdin.
+- **Message**: the hook refuses with “You do not have authority for this operation” and names the two legitimate exits — the user runs it themselves, or explicitly sets `OMC_GIT_GUARDRAILS=0`. When auto-enabled by an active mode, the refusal names the mode.
+- **Prove it bites**: before trusting the guardrail in a session, feed it a planted violation once and watch it block (see the `refit` skill's landing rule). An installed guardrail nobody has seen fire is decoration, not protection.
+
+#### Stale Run Reporter (`stale-run-reporter.mjs`)
+
+A SessionStart hook: the unattended-run **watchdog**. It scans the resolved `.omg` state root for persistent unattended-mode state files — ralph, autopilot, team, ultragoal — left `active: true` with a stale mtime (the signature of a run whose process died mid-flight), and surfaces them as advisory `[STALE RUN]` context naming the mode, approximate age, and state path.
+
+- **Threshold**: 2 hours of mtime silence (matching the persistent-mode freshness window); tunable via `OMC_STALE_RUN_HOURS`.
+- **Coverage**: both layouts — legacy `.omg/state/<mode>-state.json` and session-scoped `.omg/state/sessions/<sessionId>/<mode>-state.json`. The starting session's own state is excluded; malformed state files are ignored, never findings.
+- **Doctrine**: the watchdog observes and reports only. It never mutates state, never resumes a run, and never infers approval — reclaiming a dead run (`/oh-my-copilot:cancel` to clean up, or re-entering the mode to resume from artifacts) is always a human decision.
+
 
 ---
 
@@ -593,3 +611,220 @@ stopomc
 ```
 /oh-my-copilot:team 3:executor "build a fullstack todo app"
 ```
+
+---
+
+## Jev Judgment Points
+
+**Jev** is a System One API (TypeSafe) that provides calibrated decision-making for OMC's orchestration points. It replaces keyword lists and heuristics for critical decisions like skill triggering, model-tier routing, loop continuation, and context pruning.
+
+### Zero Egress by Default
+
+Jev is **zero egress** — nothing is sent anywhere without explicit configuration:
+- No `TYPESAFE_API_KEY` → Jev is disabled; all points run heuristic twins
+- No `OMC_JEV` configuration → no points are opted in; even with a key, zero requests are sent
+- Heuristic fallback → if Jev times out, is unavailable, or over budget, every point runs its heuristic twin and workflows never block on Jev
+
+### Configuration
+
+Enable Jev with two environment variables:
+
+```bash
+# 1. Authenticate to TypeSafe (required, but not sufficient on its own)
+export TYPESAFE_API_KEY="your-api-key"
+
+# 2. Explicitly opt in to judgment points
+export OMC_JEV="point1,point2:active,all"
+```
+
+#### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TYPESAFE_API_KEY` | (absent) | API key for TypeSafe System One. Required to enable Jev; the key alone does not enable any points. |
+| `OMC_JEV` | (absent) | Per-point opt-in: `point`, `point:active`, `all` (every point, shadow), or `all:active` (every point, active). Comma-separated; unknown point names are ignored. |
+| `OMC_JEV_TIMEOUT_MS` | `2000` | Per-call timeout in milliseconds (single round-trip measured at 465–605 ms; default allows margin). |
+| `OMC_JEV_MAX_REQUESTS` | `0` (unlimited) | Maximum Jev requests per process. When reached, heuristic twins run for remaining calls. |
+| `OMC_JEV_EXCERPT_CHARS` | `200` | Maximum string length sent in state and shadow log. Recursively bounds all strings in the judgment payload. |
+| `OMC_JEV_ENDPOINT` | `https://api.typesafe.ai/v1/systemone` | Override for stub servers or tests. |
+| `OMC_JEV_LOG_DIR` | `.omg/state/jev` | Shadow-log directory override (test only). |
+| `OMC_JEV_QUIET` | (unset) | Set to `1` to silence the env-activation stderr warning. |
+| `OMC_JEV=off` | — | Master switch: disables every point regardless of key or other config. |
+
+#### Point Activation Syntax
+
+`OMC_JEV` accepts comma-separated entries with three syntax forms:
+
+```bash
+# Shadow mode (Jev runs but decision is not used, heuristic twin is authoritative)
+export OMC_JEV="intent,model-routing,task-size"
+
+# Active mode (Jev decision is used if blocking; non-blocking points fire-and-record)
+export OMC_JEV="intent:active,model-routing:active"
+
+# Wildcard: all registered points in shadow
+export OMC_JEV="all"
+
+# Wildcard: all registered points in active
+export OMC_JEV="all:active"
+
+# Master disable
+export OMC_JEV="off"
+```
+
+Unknown point names are ignored. Activation unions across sources: code-time `ACTIVATED_POINTS` (empty in every release) plus env `:active` suffix; either source activates a point.
+
+### Shadow vs. Active Mode
+
+Each judgment point operates in one of three states:
+
+| State | Behavior | When It Occurs |
+|-------|----------|----------------|
+| **off** | Point does not run; heuristic twin is used | No `TYPESAFE_API_KEY`, `OMC_JEV=off`, or point not opted in |
+| **shadow** | Both Jev and heuristic run; Jev answer is logged but NOT acted on; heuristic is authoritative; fire-and-forget for non-blocking points | Point is opted in but not activated; Jev unavailable, times out, or over budget |
+| **active** | Jev answer IS acted on; blocking points gate behavior, non-blocking points wait (bounded by `OMC_JEV_TIMEOUT_MS`) | Point is opted in and activated via env `:active` or code-time `ACTIVATED_POINTS` |
+
+Once a point is opted in (e.g., `OMC_JEV="model-routing"`), it automatically degrades to shadow if Jev is unavailable, times out, or exceeds the request budget — no workflow blocks on Jev. In active mode, non-blocking points wait for Jev up to `OMC_JEV_TIMEOUT_MS` (default 2000ms); if Jev fails, the heuristic twin is used and the call returns immediately.
+
+### Shadow Log Location
+
+Every Jev call—whether shadow or active—is recorded in the shadow log:
+
+```
+.omg/state/jev/<point>-shadow.jsonl
+```
+
+Each line is a JSON record with:
+- `ts`: ISO timestamp
+- `point`: judgment-point name
+- `state`: the payload sent to Jev (bounded to `OMC_JEV_EXCERPT_CHARS`)
+- `mode`: `"shadow"` or `"active"`
+- `jev_answer`: Jev's response (if successful)
+- `twin_answer`: the heuristic twin's result
+- `match`: `true` if Jev and twin agree
+- `error`: error message (if the call failed)
+- `latencyMs`: round-trip time
+
+Use shadow logs to collect evidence for promotion decisions (ticket 07) and to debug mismatches.
+
+### Heuristic Fallback on Failure
+
+Jev never blocks the workflow:
+
+- **Timeout**: If a call exceeds `OMC_JEV_TIMEOUT_MS`, the heuristic twin runs immediately.
+- **Over budget**: If `OMC_JEV_MAX_REQUESTS` is reached, all remaining calls use heuristic twins.
+- **Unavailable**: If the API is unreachable or returns an error, heuristic twin is used and the failure is logged.
+- **Blocking points**: Even in active mode, if Jev fails, the heuristic twin's decision is used and the workflow continues.
+
+### Judgment Points Registry
+
+Every registered judgment point with its lifecycle hook, decision type, and blocking behavior:
+
+| Point Name | Event | Hook | Decision | Type | Blocking | Activated* |
+|------------|-------|------|----------|------|----------|------------|
+| `intent` | UserPromptSubmit | keyword-detector | Is this an Intent-intake request? | Noul (yes/no) | No | — |
+| `skill-trigger` | UserPromptSubmit | keyword-detector | Which skill should this prompt trigger? | Choice (cancel/ralph/autopilot/…) | No | — |
+| `task-size` | UserPromptSubmit | task-size-detector | Is this small/medium/large? | Choice (small/medium/large) | No | — |
+| `model-routing` | PreToolUse | delegation-enforcer | Which model tier (haiku/sonnet/opus)? | Choice (haiku/sonnet/opus) | No | — |
+| `slop-warning` | PreToolUse | jev-slop-warning | Does this tool input have advisory language? | Noul (yes/no) | No | — |
+| `context-pruning` | PostToolUse | post-tool-verifier | How stale is this context candidate? | Score (fresh/recent/aging/stale) | No | — |
+| `loop-continuation` | Stop | persistent-mode | Is task complete? + Progress level? | Noul + Score | **Yes** | — |
+| `ralph-verdict` | Stop | ralph | Does completion satisfy PRD criteria? | Noul (yes/no) | **Yes** | — |
+| `learner-extraction` | Stop | learner | Does this message have extractable memory? | Noul (yes/no) | No | — |
+| `simplifier-trigger` | Stop | code-simplifier | Is this change simplification-worthy? | Noul (yes/no) | No | — |
+
+**Activated**: asterisk (`*`) means the point is in `ACTIVATED_POINTS` (empty in all releases; promoted by ticket 07). Use `OMC_JEV=<point>:active` to activate via environment instead.
+
+**Advisory vs. Blocking**:
+- **Advisory points** (Blocking=No): Jev answers are recorded in shadow log but do not affect workflow. Useful for collecting calibration data.
+- **Blocking points** (Blocking=Yes): In active mode, Jev's yes/no answer gates behavior (e.g., ralph stops when `ralph-verdict` decides completion is met). Timeout, unavailability, or budget exhaustion reverts to heuristic twin.
+
+### Request Budget and Latency
+
+Set limits to control cost and latency:
+
+```bash
+# Limit to 100 requests per process
+export OMC_JEV_MAX_REQUESTS=100
+
+# Raise timeout for slow networks
+export OMC_JEV_TIMEOUT_MS=5000
+
+# Truncate large state excerpts
+export OMC_JEV_EXCERPT_CHARS=500
+```
+
+Once the request budget is exhausted, all remaining points run heuristic twins.
+
+### Example Configurations
+
+#### Shadow Mode (Collect Data)
+
+Run every point in shadow to collect calibration evidence:
+
+```bash
+export TYPESAFE_API_KEY="sk-..."
+export OMC_JEV="all"  # All points in shadow; heuristic is authoritative
+```
+
+Review shadow logs at `.omg/state/jev/` to see how well Jev matches your heuristics.
+
+#### Active Model Routing Only
+
+Activate Jev only for model-tier decisions:
+
+```bash
+export TYPESAFE_API_KEY="sk-..."
+export OMC_JEV="model-routing:active"  # Only this point, active
+```
+
+#### Production (All Points Active)
+
+When evidence shows Jev outperforms heuristics on all points:
+
+```bash
+export TYPESAFE_API_KEY="sk-..."
+export OMC_JEV="all:active"  # All points, active; Jev decides
+export OMC_JEV_MAX_REQUESTS=1000  # Cost control
+```
+
+#### Disable Jev Globally
+
+```bash
+export OMC_JEV="off"  # Master switch
+```
+
+Or simply omit `TYPESAFE_API_KEY`.
+
+### Debugging
+
+#### Check What Was Decided
+
+Read the shadow log for a point:
+
+```bash
+cat .omg/state/jev/model-routing-shadow.jsonl | jq '.'
+```
+
+#### Verify Jev is Running
+
+Look for stderr output on point activation:
+
+```
+[jev] model-routing: ACTIVE via env — Jev decides
+```
+
+If this does not appear, the point is not activated or Jev is disabled.
+
+#### Quiet the Warning
+
+```bash
+export OMC_JEV_QUIET=1  # Suppress the activation message
+```
+
+### References
+
+- **Decision Model**: [Jev Issue #3669](https://github.com/Yeachan-Heo/oh-my-claudecode/issues/3669) — user stories and design
+- **Degradation Contract**: [ADR 03665](adr/03665-jev-degradation-contract.md) — how Jev fails gracefully
+- **Env Activation**: [ADR 03672](adr/03672-env-activated-active-mode.md) — `:active` syntax and union semantics
+- **Script-Side Points**: [ADR 03671](adr/03671-script-side-judgment-channel.md) — hook-script integration points

package/docs/MIGRATION.md

@@ -8,6 +8,8 @@ This guide covers all migration paths for oh-my-copilot. Find your current versi
 
 - [Unreleased: Team Instance Ownership](#unreleased-team-instance-ownership)
 - [Unreleased: Cancellation Scope](#unreleased-cancellation-scope)
+- [v5.6.1 → v5.6.2: Postinstall Hook](#v561--v562-postinstall-hook)
+- [v5.5.0 → v5.6.1: Fork Upgrade Guide](#v550--v561-fork-upgrade-guide)
 - [v5.1.0 → v5.5.0: Fork Upgrade Guide](#v510--v550-fork-upgrade-guide)
 - [v4.13.102 → v5.0.0: Fork Upgrade Guide](#v413102--v500-fork-upgrade-guide)
 - [v4.x → v5.0: Workflow Retirement](#v4x--v50-workflow-retirement)
@@ -120,6 +122,136 @@ locations and descendants of system temp/OS roots are never used as roots.
 
 ---
 
+## v5.6.1 → v5.6.2: Postinstall Hook
+
+Fork **v5.6.2** ports upstream oh-my-claudecode `dev` 4280efb1f..486b85bbb.
+There is nothing to migrate: no config, command or skill changes.
+
+- Update with `npm install -g oh-my-copilot@5.6.2` or
+  `copilot plugin update oh-my-copilot@omc`.
+- `npm install` now runs `scripts/postinstall-contained-fs.mjs`. On macOS it
+  builds the contained-fs native addon if it is missing; if Node headers or
+  Xcode Command Line Tools are unavailable it prints a warning and you can
+  build later with `node scripts/build-contained-fs.mjs` from the package
+  root. On Linux and Windows it does nothing. The hook always exits 0, so it
+  never fails the install.
+
+---
+
+## v5.5.0 → v5.6.1: Fork Upgrade Guide
+
+This section covers the upgrade from fork **v5.5.0** to fork **v5.6.1**. The
+release ports upstream oh-my-claudecode v5.6.0, v5.6.1 and `dev` through
+4280efb1f, and it runs the new unattended-run commands on Copilot under a
+scoped permission profile. Nothing is renamed or removed, so there are no
+breaking changes.
+
+### TL;DR
+
+1. Update the package (`npm install -g oh-my-copilot@5.6.1`) or the plugin
+   (`copilot plugin update oh-my-copilot@omc`). No config edits are required.
+2. If you export `COPILOT_ALLOW_ALL`, note that unattended children now
+   ignore it (see [Behaviour change](#copilot_allow_all-on-unattended-children)).
+3. Optional: try `omg factory init`, `omg intake run` and `omg ralph afk`.
+   They need the host binary on PATH and `gh` authenticated.
+
+### New commands
+
+| Command | What it does |
+|---|---|
+| `omg factory init [--no-narrow] [--force] [--cwd <dir>]` | Seeds `.omg/factory-routes.json`, the chain-routing source of truth. Refuses unless `.omg/state/` and `docs/design/` exist, and never overwrites a table without `--force`. |
+| `omg factory listen --repo <owner/name,...> [--port 7788] [--host 127.0.0.1] [--cwd <dir>]` | Tracker intake daemon. Requires `OMC_FACTORY_HMAC_SECRET`; binds to 127.0.0.1 unless `--host` says otherwise. |
+| `omg factory status [--json]` | Read-only audit of factory chains. |
+| `omg intake run [--headless] [--allow-docket-only] [--host-bin <bin>] [--cwd <dir>]` | One headless harbor sweep. Refuses without a verified notification channel unless `--allow-docket-only` is passed. |
+| `omg intake schedule --cron <expr> [--off] [--cwd <dir>]` | Installs (or with `--off` removes) the sweep in cron, or in Task Scheduler on Windows (`*/N * * * *` and `M H * * *` only). |
+| `omg ralph afk "<task>" [--verify <command>]...` | Launches an isolated headless ralph run. `--verify` is repeatable. |
+| `omg ralph verify [--write-baseline] [--session <id>] [--json]` | The only command that records or judges the feedback baseline. |
+| `omg ralph from-map --map <repo#number> [--repo <name>] [--execute] [--launch] [--finalize] [--session <id>] [--json]` | Plans, claims and launches a ralph run from a wayfinder map. |
+
+### What these commands need on Copilot
+
+- **The host binary on PATH.** Factory links and ralph AFK runs spawn
+  `copilot` (or `claude` under Claude Code). `omg intake run --host-bin <bin>`
+  overrides the binary; the value is validated like the team launch contract.
+- **`gh` authenticated** for the repository. `omg intake run` refuses when
+  `gh repo view` or `gh label list` fails, and AFK sessions talk to the
+  tracker through `gh`.
+- **The AFK permission profile.** Factory links and `omg ralph afk|from-map`
+  launch Copilot with:
+
+  ```text
+  --no-ask-user
+  --allow-tool=shell(gh issue view)  --allow-tool=shell(gh issue comment)
+  --allow-tool=shell(gh issue edit)  --allow-tool=shell(gh pr view)
+  --allow-tool=shell(gh pr list)     --allow-tool=shell(gh label list)
+  --allow-tool=write  --allow-url=github.com
+  --deny-tool=write(.git)  --deny-tool=write(package.json)  --deny-tool=shell(git push)
+  ```
+
+  Deny beats allow, so the session cannot edit git plumbing, rewrite
+  `package.json` (which would turn an allowed `npm test` into arbitrary
+  shell) or push. Ralph AFK runs also get
+  `--allow-tool=shell(omg ralph verify)`. Each declared `--verify` command
+  becomes one `--allow-tool=shell(<command>)` rule; on Copilot a command that
+  is a bare program or an interpreter flag (for example `node -e`) is
+  refused, because a prefix rule would admit arbitrary code.
+- `omg intake run` launches Copilot with `-p <prompt> --no-ask-user` and no
+  allow rules, plus `OMC_GIT_GUARDRAILS=1`.
+
+### `COPILOT_ALLOW_ALL` on unattended children
+
+This is the one behaviour change. `COPILOT_ALLOW_ALL` is no longer forwarded
+by the session-end `COPILOT_*` passthrough, and every AFK child (factory
+links, `omg ralph afk|from-map`, `omg intake run`) is started with
+`COPILOT_ALLOW_ALL=false`. Before, an exported value widened the AFK profile
+to unrestricted shell. Interactive sessions and `omg team` workers are not
+affected.
+
+### New environment variables
+
+| Variable | Default | Effect |
+|---|---|---|
+| `OMC_GIT_GUARDRAILS` | unset | `1` blocks `git push`, `git reset --hard`, `git clean -f`, `git branch -D` and `git checkout/restore .` in every session; `0` turns the hook off even during an unattended mode. Unset, it is on only while ralph, autopilot, team or ultragoal is active. |
+| `OMC_STALE_RUN_HOURS` | `2` | Age after which the SessionStart watchdog reports an `active: true` unattended run as stale. It reports only; it never resumes or clears state. |
+| `OMC_HOST_LOAD_THRESHOLD` | 80% of CPU cores | CPU load above which expensive operations wait. |
+| `OMC_FREE_MEMORY_THRESHOLD` | `256` (MB) | Free memory below which expensive operations wait. |
+| `OMC_MAX_SIBLING_SESSIONS` | `8` | Live sibling OMC sessions above which expensive operations wait. |
+| `OMC_HOST_LOAD_GATE_DISABLED` | unset | Any value disables the host-load gate. The gate also proceeds when metrics are unavailable. |
+| `OMC_TEAM_WORKER_ENV_PASSTHROUGH` | unset | Comma-separated variable names forwarded to team workers, for custom provider credentials. Reserved and invalid names are rejected. |
+| `OMC_FACTORY_HMAC_SECRET` | unset | Required by `omg factory listen` to verify tracker events. |
+
+### `team.roleRouting.<role>.reasoningEffort`
+
+`roleRouting` entries take a per-role `reasoningEffort`. The fork forwards it
+only to providers with a verified CLI flag: claude workers (`--effort`) and
+codex workers (`model_reasoning_effort`). **Copilot workers ignore it**,
+because Copilot CLI has no verified reasoning-effort flag.
+
+### Windows launch change
+
+On Windows, factory links and ralph AFK runs no longer put the prompt on a
+command line. The prompt goes to the host binary on stdin (`copilot` reads a
+piped prompt without `-p`, verified on Copilot CLI 1.0.91; `claude` keeps
+`-p`), and a `gh --body` becomes `--body-file -`. Native `.exe` binaries are
+spawned directly with an argument array; only `.cmd`/`.bat` npm shims go
+through `COMSPEC`, with quoting that refuses `%`. Nothing to configure, but
+wrappers that inspected the child's argv for the prompt will no longer find
+it there.
+
+### Known limitations
+
+- **Copilot factory chains stop after one link.** Copilot CLI has no
+  `--session-id`, so the next link cannot be pinned; `omg factory status` and
+  the watchdog report the stalled chain.
+- **git-guardrails under Copilot on Windows is not live-verified.** The hook
+  is projected and unit-tested, but its PreToolUse payload has not been
+  exercised in a live Copilot session on Windows. Plant a violation (for
+  example ask for `git push`) before relying on it.
+
+See [CHANGELOG.md](../CHANGELOG.md) for the full port summary.
+
+---
+
 ## v5.1.0 → v5.5.0: Fork Upgrade Guide
 
 This section covers the upgrade from fork **v5.1.0** to fork **v5.5.0**. The

package/docs/REFERENCE.md

@@ -2,7 +2,7 @@
 
 Complete reference for oh-my-copilot. For quick start, see the main [README.md](../README.md).
 
-For v5.5.0, the plugin ships 20 agents, 61 skills, 21 command files, and one configured MCP server exposing exactly 55 tools.
+For v5.6.2, the plugin ships 20 agents, 61 skills, 21 command files, and one configured MCP server exposing exactly 55 tools.
 
 ---
 
@@ -132,6 +132,31 @@ If both configurations exist, **project-scoped takes precedence** over global:
 | `OMC_DISABLE_MULTIREPO`    | _(unset)_            | Set to `1` to disable workspace-marker resolution and fall back to git-root + cwd resolution order. `OMC_STATE_DIR` is still honoured. See [Rollback / disable multi-repo](#rollback--disable-multi-repo-omc_disable_multirepo) below.                                       |
 | `DISABLE_OMC`              | _(unset)_            | Set to `1` or `true` to disable all OMC hooks |
 | `OMC_SKIP_HOOKS`           | _(unset)_            | Comma-separated list of hook names to skip                                                                                                                                                                                                                                  |
+| `OMC_GIT_GUARDRAILS`       | _(unset)_            | `1` force-enables the destructive-git PreToolUse guard in any session; `0` always disables it (immediate exit, wins over everything). With the variable unset, the guard is on by default while an active unattended mode (ralph/autopilot/team/ultragoal) is detected.      |
+| `OMC_RUN_BUDGET_TOKENS`    | _(unset)_            | Opt-in session token budget for unattended modes. Ralph and autopilot compare spend at iteration/phase boundaries (via the `trace_summary` tool): warn at 90%, stop with a resumable budget report at 100%. Advisory today — the model reads the tool output.               |
+| `OMC_STALE_RUN_HOURS`      | `2`                  | Stale-run watchdog threshold in hours. A SessionStart hook reports unattended-mode state files left `active: true` with no mtime progress for this long (the signature of a crashed run). Advisory only — the watchdog never mutates state or resumes runs.                |
+| `OMC_HOST_LOAD_THRESHOLD` | _(dynamic)_ | CPU load threshold (1-minute average). Gate blocks operations when load exceeds this. Default: 80% of available cores. Set to negative value to disable. |
+| `OMC_FREE_MEMORY_THRESHOLD` | `256` | Free memory threshold in MB. Gate blocks operations when free memory falls below this. Set to negative value to disable. |
+| `OMC_MAX_SIBLING_SESSIONS` | `8` | Maximum concurrent OMC sessions before gating expensive operations. Set to negative value to disable. |
+| `OMC_HOST_LOAD_GATE_DISABLED` | _(unset)_ | Set to any value to disable the host load gate entirely. |
+
+#### Host Load Gate
+
+OMC monitors host resources (CPU load, free memory, concurrent sessions) to prevent resource exhaustion when multiple sessions are active. When thresholds are exceeded, expensive operations (browser launches, test runners, package installs) are gated with a back-off message.
+
+**Behavior**:
+- **Fail-open**: if metrics are unavailable, the gate allows operations immediately (never deadlocks)
+- **Configurable thresholds**: set environment variables or override via code
+- **Disable-able**: set `OMC_HOST_LOAD_GATE_DISABLED=1` to bypass gating entirely
+
+**Example**: limit concurrent sessions to 4 and free memory to 512 MB:
+
+```bash
+export OMC_MAX_SIBLING_SESSIONS=4
+export OMC_FREE_MEMORY_THRESHOLD=512
+```
+
+**Timeout**: gates wait up to 30 seconds by default before allowing operations (fail-open).
 
 #### Centralized State with `OMC_STATE_DIR`
 

package/docs/adr/03672-env-activated-active-mode.md

@@ -1,3 +1,20 @@
 # Env-activated active mode: one env line enables every judgment point
 
-Judgment points default to shadow, and the only path to active was the compile-time `ACTIVATED_POINTS` set, which is empty in every release — so Jev shipped but never decided anything. Promotion was designed as evidence-driven (shadow collection, jev-eval agreement report, ticket 07 promotion), but evidence cannot exist before someone can run Jev for real, and the compile-time set made that impossible without a code change: Jev was permanently inert. We widen the model: `OMC_JEV` entries accept an `:active` suffix (`OMC_JEV=task-size:active`, or `all:active` for every point, `all` for all-shadow), env activation unions with code activation, and a warn-once stderr line (`[jev] <point>: ACTIVE via env — Jev decides`) makes the behavioral flip observable. Degrade-never-block is unchanged: timeout, HTTP error, invalid response, request cap, and circuit-open still fall back to the heuristic twin, and the shadow log keeps recording in active mode so the evidence chain continues. Rejected alternatives: a separate `OMC_JEV_ACTIVE` env (two opt-in channels fork the opt-in semantics); a global `OMC_JEV_MODE=active` (too coarse — would flip gate-type points like ralph-verdict with no per-point control). Status: accepted.
+Judgment points default to shadow, and the only path to active was the compile-time `ACTIVATED_POINTS` set, which is empty in every release — so Jev shipped but never decided anything. Promotion was designed as evidence-driven (shadow collection, jev-eval agreement report, ticket 07 promotion), but evidence cannot exist before someone can run Jev for real, and the compile-time set made that impossible without a code change: Jev was permanently inert.
+
+## Solution
+
+`OMC_JEV` entries accept an `:active` suffix: `OMC_JEV=task-size:active`, or `all:active` for every point, `all` for all-shadow. Env activation unions with code-time `ACTIVATED_POINTS` activation, and a warn-once stderr line (`[jev] <point>: ACTIVE via env — Jev decides`) makes the behavioral flip observable.
+
+**Active mode behavior**:
+- Blocking points: Jev answer gates behavior; timeout/error falls back to heuristic twin
+- Non-blocking points (script-side): spawn synchronously and await Jev result (bounded by `OMC_JEV_TIMEOUT_MS`, default 2000ms); on timeout/error, use heuristic twin immediately
+- Script hooks (pre-tool-enforcer, keyword-detector): when Jev provides an answer in active mode, that answer overrides the heuristic (model injection, skill override, etc.)
+
+**Degrade-never-block**: Unchanged. Timeout, HTTP error, invalid response, request cap, and circuit-open still fall back to the heuristic twin. Shadow log keeps recording in active mode so the evidence chain continues.
+
+**Rejected alternatives**:
+- Separate `OMC_JEV_ACTIVE` env (two opt-in channels fork the opt-in semantics)
+- Global `OMC_JEV_MODE=active` (too coarse — would flip gate-type points like ralph-verdict with no per-point control)
+
+Status: accepted and implemented.

package/docs/design/FACTORY-FINAL-DESIGN.md

@@ -0,0 +1,114 @@
+# Software Factory — Final Design
+
+**Status:** design contract; synthesized from the Patterns-of-Work foundation (13 terms), the mattpocock/skills v1.3 borrowings, and the shipped enforcement layer (#4117, #4142, #4143, #4113)
+**Owner:** Yeachan-Heo (decisions marked **[OWNER]**)
+**Predecessors:** #4113 (dark-factory gaps), #4141 (P2 contract), #4142 (run ledger), #4143 (intake CLI), T6 acceptance (8/8)
+
+## 0. Design stance
+
+The Patterns-of-Work vocabulary is the factory's specification: each of the 13 terms is a foundation stone, each stone yields one design rule, and the factory stands on all 13 or it is not done. The goal shape is a **software factory** — triggers start sessions, humans sit at named gates — with **dark-factory mode structurally prevented for merges** (review-approve is always human). Borrowings from mattpocock/skills v1.3 are adopted as mechanics, never as text.
+
+## 1. The full loop
+
+```
+TRIGGERS                 CHAIN                      SESSION (AFK link)              GATES                    LEDGERS                 REFLECTION
+issue created/labeled ──▶ listener ──▶ spawn-next ──▶ headless session ──▶ SessionEnd ──▶ gradeGate ──▶ run ledger ──▶ chain ends ──▶ refit
+cron (intake schedule) ──▶                          (AFK profile:                  (reason → outcome)  (human/auto)  (closeout     (stall      (mechanical →
+CI failure ─────────────▶ [to build: check-run route]  narrow tools,               SessionEnd enqueuer (3 criteria,   flag)         watchdog    checks; judgment
+session ended ──────────▶ chain enqueuer ──▶         budget guard,                route table SSOT)   4 gates)                     (30 min)    → standards)
+                                        checks+review gates)
+```
+
+Humans sit only at the graded gates; everything between gates runs AFK.
+
+## 2. Foundation stones → design rules → state
+
+| Stone | Design rule | Mechanism | State |
+|---|---|---|---|
+| Human-in-the-loop | humans can sit anywhere; which decisions stay human is the main design question | 4 named gates, graded by `gradeGate` | ✅ shipped |
+| AFK | before: kill ambiguity (grilling/spec/assumption protocol); during: checks + narrow tools; after: a PR worth reviewing | assumption protocol (#4113), `AFK_ALLOWED_TOOLS`, budget-guard, PR ending | ✅ shipped |
+| Automated check | the only verification during AFK; **flaky = broken**; chain advances only on green checks | per-skill doctrine; **chain-level check gate: to build**; win32 flaky spawn tests: **to fix/bound** | ⚠️ partial |
+| Automated review | fresh-context reviewer, scoped prompt, **filter before the human gate — not a gate** | code-reviewer agent exists; **not a chain stage: to build** | ⚠️ partial |
+| Human review | **the diff is the primary source; the summary is not** | review-approve gate is human; **diff-first requirement: to build** | ❌ violates stone |
+| Vibe coding | the stance the factory makes explicit; visibility of dark vs gated areas | factory status view (#4180) | 🟡 open PR |
+| Design concept | concept before fixation; spec too early durably captures misalignment | intent stage (non-engineer intake → review → accepted) | ✅ T6-validated |
+| Grilling | one decision at a time, recommended answers | deep-interview (ambiguity scoring, frontier batching) | ✅ shipped |
+| Prototyping | when words are too low-fidelity | loft | ✅ shipped |
+| DX | the human contrast; informs where AX investment differs | — | — |
+| AX | the environment is the only support in AFK runs | state-root fix (#4115), skill map (#4116), narrow tool profile, lean inventory | ✅ shipped |
+| Software factory | triggers start sessions; **start small** (narrow loop → trust → widen); 4 trigger classes | listener (issue) ✅, intake schedule (cron) ✅, session-end enqueuer ✅, **CI-failure route: to build**, **narrow starter loop: to build** | ⚠️ 3/4 triggers |
+| Dark factory | structurally prevented for merges; made visible where it exists | review-approve always human (gradeGate); status view (#4180) | ✅ prevented + visible |
+
+## 3. Component design (shipped vs to build)
+
+### 3.1 Trigger layer
+
+- **Issue webhook** ✅ — listener daemon: HMAC, repo whitelist, intake label gate, serial.
+- **Cron** ✅ — `omg intake schedule` (host-native timer, no daemon) → headless sweep.
+- **Session end** ✅ — chain enqueuer: reason → outcome → route table → next link.
+- **CI failure** ⚠️ **to build** — check-run failure webhook → listener route → diagnose/fix session (`diagnose:ci-failure` route entry). Same HMAC/whitelist path as issue intake.
+- **Narrow starter loop** ⚠️ **to build** — `omg factory init --narrow`: one cron trigger + one session type + one reviewable PR (the "one lint rule a night" shape). The start-small configuration ships as the default; the full-pipeline route table is the widening, gated on the narrow loop's review track record.
+
+### 3.2 Chain layer
+
+- Route table SSOT ✅ (`.omg/factory-routes.json`, #4176). **`omg factory init` to build** — seeds the route table (narrow loop by default, full pipeline as widening), validates harbor labels and shipyard prerequisites, documents the format; makes `DAILY_CHAIN_LIMIT` configurable (env override, default 10).
+- Gate grading ✅ (3 criteria + mechanical checks; intent-accept and review-approve always human).
+- Guardrails ✅ (serial single-session, daily cap); **cap configurability included in factory init**.
+- Watchdog ✅ (stall detection → `harbor:need-info`); stall naming + status view in #4180.
+
+### 3.3 Session layer (the AFK link)
+
+- **Before** ✅ — grilling (deep-interview), design-concept building (intent), prototyping detour (loft), assumption protocol.
+- **During** ✅/⚠️ — budget guard (shipped); AFK tool profile (shipped); **tdd-driven implementers to build**: factory build-stage links mandate the tdd skill (implement-spec v1.3 mechanic — implementers call tdd, never free-form); **integration disciplines to build**: base-reset at start + integration-tip pull before reporting (implement-spec v1.3 mechanics — bounds drift to one work session); **check gate to build**: the link's checks must run green before the SessionEnd reports success.
+- **After** ✅/⚠️ — ends in a PR worth reviewing (diff attached); run ledger + reconciliation (shipped).
+
+### 3.4 Gate layer
+
+- gradeGate ✅ — 3 criteria; intent-accept and review-approve structurally human.
+- **Diff-first human review to build** — a review-approve signoff must attach the diff or changed-file list (primary source); summary-only signoffs are recorded as invalid. Fixes the one foundation-stone violation (stone 5).
+- **Automated review stage to build** — before review-approve, a fresh-context reviewer agent (scoped system prompt: security/contract/performance per change type) runs as a filter; the human gate sees the filtered findings plus the diff. The filter never replaces the gate.
+
+### 3.5 Ledger layer
+
+- Run ledger ✅ (#4142), enforcement shadow log ✅ (#4117), chain ledger ✅ (#4153 family), reconciliation ✅.
+- **Factory status view** — #4180 (open): names silent stalls, shows dark vs gated areas per the vibe-coding stone.
+
+### 3.6 Reflection layer
+
+- refit ✅ (user-invoked; categories match the retro skill's).
+- **Chain-termination → refit trigger to build** — implement-spec v1.3 places retro as the step that "closes the loop; the next build starts from a better environment". The factory route table gains a terminal edge: chain end → refit suggestion (advisory). Mechanical mistakes become checks; judgment calls become standards — the loop Matt draws, wired into our chain.
+
+## 4. Borrowings from mattpocock/skills v1.3 (mechanics only, never text)
+
+| Borrowing | Source | Lands in |
+|---|---|---|
+| Integration-branch goal framing | implement-spec v1.3 | build-stage link doctrine |
+| Tracker pointer (ticket status source) | implement-spec v1.3 | chain ledger `tracker` (already shipped) |
+| tdd-driven implementers | implement-spec v1.3 | build-stage link gate |
+| Worktree base-reset + tip-pull | implement-spec v1.3 | build-stage link conventions |
+| Draft PR after first merge (empty branch can't open one) | implement-spec v1.3 | PR timing in the chain |
+| Retro closes the loop | retro graduated + ask-matt placement | chain-termination → refit trigger |
+| pr is model-invoked | pr graduated | our pr skill stays model-invocable |
+| Glossary naming (`GLOSSARY.md`, collision with agent-context) + `GLOSSARY-MAP.md` multi-context map | v1.3 rename | **[OWNER]** breaking rename of `CONTEXT.md` |
+| Start-small narrow loop | software-factory essay | `omg factory init --narrow` default |
+| Retro's environment categories | retro skill | refit (already absorbed, #4110) |
+
+## 5. Defect register (foundation-stone violations and gaps)
+
+1. **Stone 5 violation** — review-approve accepts summary-only signoffs. Fix: diff-first requirement (§3.4).
+2. **Stone 4 gap** — no automated-review stage in the chain. Fix: §3.4.
+3. **Stone 3 poisoning** — win32 flaky spawn tests; no chain-level check gate. Fix: bound or fix (§3.3).
+4. **Stone 12 gap** — CI-failure trigger missing. Fix: §3.1.
+5. **Start-small missing** — full-pipeline route table as the only config. Fix: narrow starter default (§3.1).
+6. **Adoption gaps** — route-table authoring story, cap configurability, shipyard prerequisite check. Fix: `omg factory init` (§3.2).
+
+## 6. Sequencing
+
+1. Land #4180 + #4179 (visibility + AFK verify commands).
+2. **This contract's implementation waves**: (a) diff-first review doctrine + automated-review stage; (b) chain check gate + win32 bounding; (c) `omg factory init` + CI-failure trigger; (d) narrow starter loop config.
+3. Shadow accumulation on real usage → promotion per protocol (≥20 samples, zero false blocks) **[OWNER]**.
+4. T7 acceptance: full pipeline chained on a real repository — the actual "fully implemented" verdict.
+
+## 7. Non-goals
+
+No dark-factory mode for merges (structurally prevented). No auto-resume. No inferred approvals. No production-monitoring daemon (ecosystem seam). No daemon beyond the opt-in listener.