holo-codex 0.1.0

package/docs/examples/generic-loop-repo-hygiene.md

@@ -0,0 +1,168 @@
+# Generic Loop Example: Repo Hygiene Audit
+
+This example shows how to use `generic-loop` for a repository hygiene audit. It is a usage sample, not a new workflow engine. The loop produces an auditable Markdown report, pauses at human gates, and leaves evidence in artifacts, timeline, and the Dashboard.
+
+Use this when you want a repeatable non-PR workflow such as checking docs, config, install notes, test entrypoints, and maintainer workflow consistency.
+
+Do not use this for code PR delivery, automatic cleanup, arbitrary DAG orchestration, production operations, or any workflow that should bypass human approval.
+
+## Clean Repo Setup
+
+Start from a clean target repository:
+
+```bash
+git status --short
+pnpm agent-loop init
+pnpm agent-loop status --json
+```
+
+Then edit `.agent-loop/config.json` in the target repository:
+
+```json
+{
+  "repoId": "owner/repo",
+  "baseBranch": "main",
+  "plansDir": "docs/plans",
+  "loopShape": "generic-loop",
+  "workflowProfile": "repo_hygiene_loop",
+  "roleProfile": "default_pr_roles",
+  "requiredChecks": []
+}
+```
+
+Do not add `protectedPaths` unless you intend to replace the defaults. The default protected paths keep `.git/`, `.agent-loop/`, `.claude/`, `AGENTS.md`, `CLAUDE.md`, env files, and secret-like paths out of worker changes.
+
+`repo_hygiene_loop` writes only report-style artifacts under the built-in allowed roots, currently `docs` and `reports`. Keep `.agent-loop/` out of commits; it is runtime state.
+
+## Goal
+
+Use a concrete goal, for example:
+
+```text
+Audit this repository for local install, docs, test command, handoff, and dashboard example drift. Produce a Markdown repo hygiene audit report with findings, severity, evidence, and recommended action. Do not edit source code or perform cleanup.
+```
+
+The important part is the boundary: this loop can inspect the repo and write a report, but cleanup should remain explicit and scoped.
+
+## Command Flow
+
+Run until the first human gate:
+
+```bash
+pnpm agent-loop run --until=gate --json
+pnpm agent-loop observe --json
+```
+
+For a fresh generic-loop run, expect a goal confirmation gate:
+
+```json
+{
+  "kind": "generic_goal_needs_confirmation",
+  "state": "DEFINE_GOAL",
+  "allowedNextStates": ["COLLECT_CONTEXT", "PLAN_WORK", "STOPPED"]
+}
+```
+
+This snippet shows the key fields. The full gate details also include profile metadata, `expectedDeliverable`, `defaultNextState`, and the required approval payload.
+
+Approve it after confirming the goal and boundary:
+
+```bash
+pnpm agent-loop approve-gate <gate-id> \
+  --next-state COLLECT_CONTEXT \
+  --note "Goal and report-only boundary confirmed."
+pnpm agent-loop resume --json
+```
+
+The loop should collect context, write a plan artifact, execute the audit report, self-review it, and then stop again at `generic_human_gate` before delivery:
+
+```bash
+pnpm agent-loop observe --json
+pnpm agent-loop timeline --limit 20 --json
+pnpm agent-loop workers --events --json
+```
+
+If the report is acceptable:
+
+```bash
+pnpm agent-loop approve-gate <gate-id> \
+  --next-state DELIVER \
+  --note "Repo hygiene report approved for delivery."
+pnpm agent-loop resume --json
+```
+
+If the report needs changes:
+
+```bash
+pnpm agent-loop approve-gate <gate-id> \
+  --next-state EXECUTE_STEP \
+  --note "Add missing install and dashboard evidence before delivery."
+pnpm agent-loop resume --json
+```
+
+## Expected Artifacts
+
+The run should register at least these artifact records. The Dashboard Artifact Viewer and JSON audit export include artifact paths. `timeline --source artifact` shows artifact entries by name, kind, hash, and artifact id.
+
+| Kind | Typical name | Purpose |
+| --- | --- | --- |
+| `generic-context` | `context.md` | Captures collected context and profile metadata. |
+| `generic-plan` | `plan.md` | Captures the plan, expected deliverable, required evidence, and review checklist. |
+| `generic-deliverable` | `deliverable.md` | Captures the final approved handoff for the repo hygiene report. |
+| worker result | worker-generated Markdown or JSON artifact | Contains the detailed audit report and worker evidence. |
+
+The report should contain severity, evidence, and recommended action. It should not include raw secrets, private prompt text, or unrelated cleanup patches.
+
+## Timeline And Audit Validation
+
+Validate the audit path with:
+
+```bash
+mkdir -p reports
+pnpm agent-loop timeline --source gate --limit 20 --json
+pnpm agent-loop timeline --source artifact --limit 20 --json
+pnpm agent-loop audit-export --run <run-id> --format markdown --output reports/repo-hygiene-audit.md
+pnpm agent-loop audit-export --run <run-id> --format json --output reports/repo-hygiene-audit.json
+```
+
+Expected evidence:
+
+- A `generic_goal_needs_confirmation` gate before work starts.
+- A `generic_plan_ready` decision after planning.
+- Worker timeline entries for execute and self-review steps.
+- Artifact timeline entries for context, plan, and deliverable records.
+- Artifact paths in the Dashboard Artifact Viewer or `reports/repo-hygiene-audit.json`.
+- A `generic_human_gate` before delivery.
+- A `generic_loop_completed` event when the run reaches `COMPLETE`.
+
+## Dashboard Checks
+
+Open the Dashboard:
+
+```bash
+pnpm agent-loop dashboard
+```
+
+In Mission Control and related views, confirm:
+
+- The profile shows `loopShape=generic-loop` and `workflowProfile=repo_hygiene_loop`.
+- Deliverable readiness replaces PR merge readiness.
+- Gate Center shows the active generic gate and allowed next states.
+- Artifacts include context, plan, and deliverable records.
+- Timeline contains state, decision, gate, worker, and artifact entries for the run.
+- Worker Runs shows planner, implementation, and reviewer roles, but the supervisor still owns Git and lifecycle actions.
+
+## Recovery Notes
+
+If a worker fails, inspect before recovering:
+
+```bash
+pnpm agent-loop observe --json
+pnpm agent-loop workers --events --json
+pnpm agent-loop recover --json
+pnpm agent-loop resume --json
+```
+
+If the worker requests a broader scope, the run should open `generic_scope_change_requested`. Approve only if the broader scope still belongs to this audit. Otherwise send it back to `PLAN_WORK` or stop the run.
+
+Generic-loop completion returns the run to a non-running status with `COMPLETE` as the terminal state. To run another audit, start a new run instead of resuming a completed one.

package/docs/install.md

@@ -0,0 +1,190 @@
+# HOLO-Codex Install
+
+English: Install the local-first plugin, configure MCP/hook integration, then initialize `.agent-loop/` state.
+
+中文：先安装本地优先插件，配置 MCP/hooks，再初始化 `.agent-loop/` 状态。
+
+See also: [README](../README.md) / [中文 README](../README.zh-CN.md) / [Local Release Readiness](./local-release-readiness.md).
+
+## npm Install
+
+```bash
+npm install --global holo-codex
+```
+
+Initialize and bind a target repository:
+
+```bash
+agent-loop --repo /path/to/repo init
+agent-loop install-hooks --repo /path/to/repo
+agent-loop --repo /path/to/repo doctor
+agent-loop --repo /path/to/repo status
+```
+
+The npm package provides the `agent-loop` CLI. `agent-loop install-hooks` installs or refreshes the hook router and target repository binding without reinstalling the global CLI. Use source `agent-loop local install` only when you want the pnpm-based snapshot/rollback install workflow.
+
+## Source Install
+
+```bash
+git clone https://github.com/tizerluo/HOLO-Codex.git
+cd HOLO-Codex
+pnpm install
+pnpm build:hooks
+```
+
+Development CLI options:
+
+```bash
+# From this repository
+pnpm agent-loop status
+
+# Safe local install with snapshot/rollback
+# Replace /path/to/repo with the repository you want HOLO-Codex to supervise.
+pnpm agent-loop local install --repo /path/to/repo
+agent-loop --repo /path/to/repo status
+```
+
+The canonical public source is `https://github.com/tizerluo/HOLO-Codex`. Use source install when developing HOLO-Codex, auditing the checkout, or testing local changes before a release. If pnpm reports that the global bin directory is not in `PATH`, add that directory to `PATH` before installing or use a shell profile managed by `pnpm setup`.
+
+For the full fresh-machine checklist, including MCP env, hooks, dashboard login, and smoke tests, use [Local Release Readiness](./local-release-readiness.md).
+
+## Enable The Plugin
+
+Add HOLO-Codex as a local Codex plugin marketplace. For npm installs:
+
+```bash
+codex plugin marketplace add "$(npm root -g)/holo-codex"
+```
+
+For source installs:
+
+```bash
+codex plugin marketplace add /path/to/HOLO-Codex
+```
+
+Then enable `autonomous-pr-loop` in Codex config using the local marketplace entry.
+
+Plugin enablement and global CLI installation are separate. The marketplace entry enables Codex plugin/MCP/skill integration; the global install only exposes the `agent-loop` shell command.
+
+## Configure MCP
+
+The plugin ships `plugins/autonomous-pr-loop/.mcp.json` with a stdio MCP server named `autonomous-pr-loop`.
+Mutating MCP tools require a shared token. Set it in the Codex MCP server environment and pass the same value as `token` when calling mutating tools:
+
+```bash
+export AGENT_LOOP_MCP_TOKEN="change-me"
+```
+
+Manual fallback:
+
+```bash
+codex mcp add autonomous-pr-loop \
+  --cwd /path/to/HOLO-Codex/plugins/autonomous-pr-loop \
+  -- pnpm exec tsx ./mcp-server/src/index.ts
+```
+
+When using the global CLI from another repository, keep `AGENT_LOOP_REPO_ROOT=/path/to/repo` in the MCP server environment so mutating tools bind the intended target repository.
+
+## Initialize Local State
+
+Current development packaging exposes both the repository-local command and the global command. Run either from the target repository, or pass `--repo <path>` to bind a target workspace:
+
+```bash
+pnpm agent-loop init
+pnpm agent-loop doctor
+pnpm agent-loop status
+pnpm agent-loop --repo /path/to/repo status
+pnpm agent-loop --repo /path/to/repo dashboard
+agent-loop --repo /path/to/repo status
+agent-loop --repo /path/to/repo dashboard
+```
+
+`--repo` is parsed as a global flag before command dispatch; do not use the literal `--repo` as the value of another command option.
+
+`doctor` reports whether hooks are installed and whether config/storage/tool checks pass.
+
+Runtime state is stored in the target repository's `.agent-loop/` and must not be committed.
+
+## Configure Hooks
+
+Plugin hook auto-loading is not assumed. For a fresh target repository, initialize local state first, then install the hook router and target binding:
+
+```bash
+agent-loop --repo /path/to/repo init
+agent-loop install-hooks --repo /path/to/repo
+```
+
+This installs one stable HOLO-Codex hook router into `~/.codex/hooks.json`, preserves existing user hooks, and records the target repository binding under `~/.codex/agent-loop/hook-bindings.json`.
+
+Multi-repo note: multiple target repositories can share the same `CODEX_HOME`; hook events are routed by Codex cwd/worktree/session context before any repo state is written or policy is applied. Use a separate `CODEX_HOME` only when you want a fully isolated sandbox.
+
+When starting real PR delivery work in that repository, bind after init/hooks:
+
+```bash
+agent-loop --repo /path/to/repo delivery bind --issue ISSUE --title "..." --url https://github.com/OWNER/REPO/issues/ISSUE
+```
+
+## Upgrade, Reinstall, Or Uninstall
+
+Upgrade or reinstall the global CLI from the plugin repository:
+
+```bash
+git pull --ff-only
+pnpm install
+pnpm build:hooks
+pnpm agent-loop local install --repo /path/to/repo
+agent-loop --repo /path/to/repo doctor
+```
+
+Rollback a local install with the snapshot path printed by install:
+
+```bash
+agent-loop local rollback --snapshot /path/to/snapshot
+```
+
+Rollback preserves malformed current hook files as `hooks.json.broken-<timestamp>` or `hook-bindings.json.broken-<timestamp>` before restoring the snapshot, so operators can inspect the broken file after recovery.
+
+Inspect and prune old local-install snapshots:
+
+```bash
+agent-loop local snapshots
+agent-loop local snapshots prune --keep 10
+agent-loop local snapshots prune --keep 10 --apply
+```
+
+`prune` is dry-run by default. It deletes only valid old `local-install-*` snapshots when `--apply` is present; malformed snapshots are skipped with warnings.
+
+Manual fallback: remove the global CLI package with `pnpm remove --global holo-codex`. Older local installs may still appear as `codex-auto-pr-loop-plugin`; inspect global packages with `pnpm list --global --depth 0` and remove the matching `agent-loop` provider. Hook router entries live in `~/.codex/hooks.json`; target bindings live in `~/.codex/agent-loop/hook-bindings.json` and can be removed with `agent-loop hooks unbind --repo /path/to/repo`.
+
+For npm installs, remove the target binding first and then uninstall the global package:
+
+```bash
+agent-loop hooks unbind --repo /path/to/repo
+# If no target repositories still use HOLO-Codex hooks, remove the
+# HOLO-Codex router entries from ~/.codex/hooks.json before uninstalling.
+npm uninstall --global holo-codex
+```
+
+Detailed upgrade, reinstall, uninstall, and global CLI resource checks are in [Local Release Readiness](./local-release-readiness.md).
+
+## Dashboard And Local Observability
+
+Start the dashboard from this repository or through the global command:
+
+```bash
+pnpm agent-loop --repo /path/to/repo dashboard
+agent-loop --repo /path/to/repo dashboard
+```
+
+The command prints a loopback URL on stdout and a fallback session token on stderr. Open the URL to load the local dashboard; loopback sessions unlock themselves through a same-origin bootstrap, and the browser sends the session token through the `x-agent-loop-token` header for dashboard mutations. The manual token login screen remains as a fallback for static UI, old links, or recovery.
+
+Useful local observability commands:
+
+```bash
+agent-loop --repo /path/to/repo timeline --limit 20
+agent-loop --repo /path/to/repo workers --events
+agent-loop --repo /path/to/repo observe
+agent-loop --repo /path/to/repo audit-export --run RUN_ID --format markdown
+```
+
+Theme and locale are browser-local display preferences. They do not change `.agent-loop/config.json` or SQLite state.

package/docs/local-release-readiness.md

@@ -0,0 +1,206 @@
+# HOLO-Codex Local Release Readiness Checklist
+
+This checklist prepares HOLO-Codex for day-to-day use through the published npm package or the public GitHub source checkout.
+
+## Fresh Machine Setup
+
+Install from npm:
+
+```bash
+npm install --global holo-codex
+agent-loop --help
+agent-loop --repo /path/to/target-repo init
+agent-loop install-hooks --repo /path/to/target-repo
+agent-loop --repo /path/to/target-repo doctor
+```
+
+Use the source checkout when developing or auditing the release:
+
+```bash
+git clone https://github.com/tizerluo/HOLO-Codex.git
+cd HOLO-Codex
+pnpm install
+pnpm build:hooks
+pnpm agent-loop local install --repo /path/to/target-repo
+agent-loop --help
+```
+
+For npm installs, `agent-loop install-hooks` installs or migrates router hooks and binds the target repo without reinstalling the global CLI. For source installs, `agent-loop local install` snapshots `~/.codex/hooks.json` and `~/.codex/agent-loop/hook-bindings.json`, installs the global CLI, installs or migrates router hooks, binds the target repo, checks for accidental manifest churn, and prints the rollback command. If pnpm reports that the configured global bin directory is not in `PATH`, add that directory to `PATH` before source local install or run `pnpm setup` for your shell.
+
+Enable the local Codex plugin separately from the global CLI install. For npm installs:
+
+```bash
+codex plugin marketplace add "$(npm root -g)/holo-codex"
+```
+
+For source installs:
+
+```bash
+codex plugin marketplace add /path/to/HOLO-Codex
+```
+
+Then enable `autonomous-pr-loop` in Codex from the local marketplace entry.
+
+Configure the MCP token in the Codex MCP server environment. Mutating MCP tools must receive the same token in their `token` input:
+
+```bash
+export AGENT_LOOP_MCP_TOKEN="change-me"
+```
+
+When configuring the MCP server manually, keep the MCP cwd at the plugin directory and bind the intended target repository with `AGENT_LOOP_REPO_ROOT`:
+
+```bash
+codex mcp add autonomous-pr-loop \
+  --cwd /path/to/HOLO-Codex/plugins/autonomous-pr-loop \
+  --env AGENT_LOOP_MCP_TOKEN="$AGENT_LOOP_MCP_TOKEN" \
+  --env AGENT_LOOP_REPO_ROOT=/path/to/target-repo \
+  -- pnpm exec tsx ./mcp-server/src/index.ts
+```
+
+Initialize one target repository:
+
+```bash
+agent-loop --repo /path/to/target-repo init
+agent-loop --repo /path/to/target-repo doctor
+agent-loop --repo /path/to/target-repo status
+agent-loop install-hooks --repo /path/to/target-repo
+agent-loop --repo /path/to/target-repo doctor
+```
+
+Runtime state is written to the target repository's `.agent-loop/` directory. Do not commit `.agent-loop/`, SQLite files, tokens, or dashboard session output.
+
+## Upgrade Or Reinstall
+
+For npm installs:
+
+```bash
+npm update --global holo-codex
+agent-loop install-hooks --repo /path/to/target-repo
+agent-loop --repo /path/to/target-repo doctor
+agent-loop --repo /path/to/target-repo status
+```
+
+For source checkouts:
+
+```bash
+cd /path/to/HOLO-Codex
+git pull --ff-only
+pnpm install
+pnpm build:hooks
+pnpm agent-loop local install --repo /path/to/target-repo
+agent-loop --repo /path/to/target-repo doctor
+agent-loop --repo /path/to/target-repo status
+```
+
+Re-run `install-hooks` after updates because router hook commands include the current plugin install path and compiled hook runner paths. The target binding remains in `~/.codex/agent-loop/hook-bindings.json` and is refreshed by the same command.
+
+If `doctor` reports stale or missing compiled hooks, run:
+
+```bash
+pnpm build:hooks
+agent-loop install-hooks --repo /path/to/target-repo
+```
+
+## Uninstall Global CLI
+
+For npm installs:
+
+```bash
+agent-loop hooks unbind --repo /path/to/target-repo
+# If no target repositories still use HOLO-Codex hooks, remove the
+# HOLO-Codex router entries from ~/.codex/hooks.json before uninstalling.
+npm uninstall --global holo-codex
+```
+
+For source local installs, use the rollback snapshot printed by install:
+
+
+```bash
+agent-loop local rollback --snapshot /path/to/snapshot
+```
+
+If rollback encounters malformed current hook state, it preserves the bad file as `hooks.json.broken-<timestamp>` or `hook-bindings.json.broken-<timestamp>` before restoring the snapshot. Keep these files only long enough for manual inspection.
+
+Inspect and safely prune old install snapshots:
+
+```bash
+agent-loop local snapshots
+agent-loop local snapshots prune --keep 10
+agent-loop local snapshots prune --keep 10 --apply
+```
+
+`local snapshots prune` is a dry-run unless `--apply` is present. It skips malformed snapshots and reports warnings instead of deleting them.
+
+Manual source fallback: if pnpm reports the package name differently or rollback cannot remove the global command, inspect global packages and remove the matching `agent-loop` provider:
+
+```bash
+pnpm list --global --depth 0
+pnpm remove --global holo-codex
+```
+
+Older local source installs may still be listed as `codex-auto-pr-loop-plugin`; remove that package name when it is the provider shown by `pnpm list --global --depth 0`.
+
+Remove a target binding when that repository should no longer participate in the Codex hook loop:
+
+```bash
+agent-loop hooks unbind --repo /path/to/target-repo
+```
+
+The router entries live in `~/.codex/hooks.json`; target bindings live in `~/.codex/agent-loop/hook-bindings.json`. Remove router entries only when no target repository should use agent-loop hooks.
+
+Remove the local plugin marketplace entry through Codex plugin management if you no longer want Codex to see the plugin. Do not delete `.agent-loop/` from a target repo unless you intentionally want to discard its local loop state.
+
+## Global CLI Resource Smoke
+
+From any directory outside the target repository, verify that global CLI commands bind the target repo while loading plugin resources from the plugin repository:
+
+```bash
+agent-loop --repo /path/to/target-repo status --json
+agent-loop --repo /path/to/target-repo observe --json
+agent-loop --repo /path/to/target-repo dashboard
+agent-loop install-hooks --repo /path/to/target-repo
+agent-loop local doctor --repo /path/to/target-repo
+```
+
+Expected results:
+
+- `status --json` reports the target repository's `.agent-loop/state.sqlite`.
+- `observe --json` reports the target dashboard URL and current run/gate state.
+- `dashboard` serves the plugin dashboard UI, prints the loopback URL on stdout, and prints the session token on stderr.
+- `install-hooks` writes one router hook command per Codex hook event, removes legacy per-repo agent-loop hook entries, and records the target repo binding in `~/.codex/agent-loop/hook-bindings.json`.
+- `local doctor` reports the first `agent-loop` on `PATH`, whether it points to the expected package root, router hook dist drift, legacy entries, binding counts, stale/temp bindings, registry lock state, and self-link manifest pollution.
+- MCP server cwd remains the plugin MCP directory; `AGENT_LOOP_REPO_ROOT` binds mutating tools to the target repo.
+- Schemas remain package resources under `plugins/autonomous-pr-loop/schemas/`.
+
+## Operator Smoke Tests
+
+Before using the loop on real work, run:
+
+```bash
+agent-loop --repo /path/to/target-repo doctor
+agent-loop --repo /path/to/target-repo status --json
+agent-loop --repo /path/to/target-repo observe --json
+agent-loop --repo /path/to/target-repo timeline --limit 20
+agent-loop --repo /path/to/target-repo workers --events
+```
+
+Dashboard smoke:
+
+```bash
+agent-loop --repo /path/to/target-repo dashboard
+```
+
+Open the printed loopback URL and confirm Mission Control loads the target repository without manual token entry. The stderr token is a fallback local session secret for static UI or recovery only; do not paste or store it in docs, logs, PR bodies, commits, issue comments, artifacts, or screenshots.
+
+MCP smoke:
+
+- `loop_status` returns the same target repo state as `agent-loop --repo /path/to/target-repo status --json`.
+- Mutating tools without a token return `needs_secret_or_login`.
+- Mutating tools with the configured token bind the repository named by `AGENT_LOOP_REPO_ROOT`.
+
+## Out Of Scope
+
+- automatic upgrade or uninstall scripts.
+- shell completion.
+- hosted service, daemon, or GitHub webhooks.
+- multi-version local marketplace management.