{
  "markdown": "# Loop Engineering Bootstrap\n\nLoop Engineering Bootstrap is a bootstrap kit for operating autonomous AI coding agents (Codex / Claude Code) as auditable loops. The v0.2 line is implemented in Python only (Golang was used in v0.1 but has been retired), minimizes pre-execution blocking, and instead makes every run's results visible through a deterministic Run Report and alerts. Durable memory is updated only through validated transactions to an OKF-format LLMWiki.\n\nThe Bootstrap has been self-applied to this repository.\n\n## Core concept\n\nv0.2 consists of four pillars.\n\n1. **Autonomous operation** — Agents can execute runs without sequential human approval. The next turn's input is constructed deterministically from the handoff and Run Report written by the previous run; the model's self-reported memory is not carried forward.\n2. **Auditability** — Each run's operations are recorded in a sanitized, append-only journal, and `audit run` performs inspections in a fixed order to generate a Run Report. A completion claim is made only when the Run Report has been generated.\n3. **alert-not-block** — Pre-execution blocking is limited to an enumerated set of hard blocks (destructive commands, persistent storage of secrets, invalid memory application, and writes outside the repository). Other deviations do not stop the work and are recorded as alerts in the Run Report. A protected-path change is a warn when intent was declared in advance during the run, and critical when undeclared.\n\nPending durable-memory drafts are listed with `python3 -m loopeng memory drafts list`; explicit approval uses `memory approve <id> --quote \"...\"`, while `memory reject` and `memory snooze` retain the audit trail.\n4. **OKF LLMWiki memory** — Durable-memory writes are limited to `okf apply` transactions that pass schema validation, namespace containment, proposal_id, and operation-count and document-size limits. Nothing is deleted; history is retained by reversing status with `DEPRECATE`.\n\n## Components\n\n| Component | What |\n|---|---|\n| `loopeng/` | Python control-layer package (stdlib only). The CLI is `python3 -m loopeng <subcommand>` |\n| `loopeng okf` | `init` / `validate` / `apply` / `reindex` / `log` / `query` / `draft` — initialize, search, draft, and update LLMWiki bundles |\n| `loopeng learning promote` | Generate validated memory drafts from learning backlog (does not apply them) |\n| `loopeng learning feedback` | Turn explicit user feedback about a run into a reviewable skill draft |\n| `loopeng knowledge gaps` | Detect evidence-backed knowledge gaps and suggest LLMWiki reads |\n| `loopeng memory curate` | Apply at most three provisional UPSERTs from autonomous namespaces after audit |\n| `loopeng memory stats` | Summarize LLMWiki mutation windows and non-LLMWiki commits |\n| `loopeng memory efficacy` | Compare signed learning entries with later recurrence and retrieval (`--space current|framework|project|all`) |\n| `loopeng inbox --tui` / `--interactive` | Process inbox items with curses or line-oriented fallback |\n| `loopeng journal add` | Append events to a run (`run-start` / `intent` / `mutation` / `run-end`, etc.) |\n| `loopeng audit run` | Run inspections, generate the Run Report, and write the handoff |\n| `loopeng trace render` / `trace show` | Render deterministic per-run tool-trace Markdown views or show a terminal summary |\n| `loopeng run verify` / `run outcome` | Verify declared acceptance commands or append a human outcome label |\n| `loopeng doctor` | Inspect loop state and apply only safe repairs with `--fix` |\n| `loopeng inbox` | Show pending human approvals, held decisions, and unresolved outcomes |\n| `loopeng run stats` | Display run outcomes and governance-overhead ratios without alerting |\n| `loopeng audit export` | Export a sanitized journal, report, sidecar, and git-diff review packet |\n| `loopeng review intake` / `request` | Deterministically accept an external-agent review or generate its request; `intake --auto` scans the incoming drop-off |\n| `loopeng schedule next` | Generate the next turn's preamble from the previous run's handoff |\n| `loopeng status` | Summarize the latest Run Report and learning backlog |\n| `loopeng review` | Review recent run results, concerns, and premises; `--triage` guides review, `review html --run <id>` renders a packet-backed HTML view with hook timeline and Mermaid-backed DAG image, and `review serve` provides HTTPS-only local delivery |\n| `loopeng retrospective` | Analyze recent runs deterministically and suggest improvements; read-only unless `--record` is supplied |\n| `loopeng hook` | Claude Code / Codex hook entry point for automatic journal capture and pre-execution hard-block enforcement |\n| `./loopeng.py` | Short launcher equivalent to `python3 -m loopeng` |\n| `skills/frame-*` | Thinking-framework skill family (the only distributed skills; edit point: `adapters/shared/skills/`) |\n| `utils/phase1_gate.py` / `utils/phase1_gate_ext.py` | Executable acceptance gates (must not be changed; the sole basis for completion judgment) |\n| `utils/audit_guard.py` | This repository's completion protocol (pre-push audit) |\n\n## Install\n\nSet `LANG` to choose English help; Japanese is used when `LANG` is unset or starts with `ja`.\n\nPython 3.10+ is the prerequisite.\n\n```bash\n# frame-* skill のみ(routing プロファイル)\npython3 install.py --repo /path/to/repository --profile routing\n\n# skill + loopeng 制御層 + state 雛形(full プロファイル)\npython3 install.py --repo /path/to/repository --profile full\n\n# 既存環境の更新。v0.1 の導入痕跡(旧フック・旧ポリシー)を検出した場合は\n# 退避アーカイブへ移して v0.2 へ収束させます(削除はしません)\npython3 install.py --repo /path/to/repository --profile full --update\n```\n\nFull installs record their payload in `.agent-loop/runtime/install-manifest.json`; `python3 -m loopeng doctor` checks installed-file and version integrity (`--against /path/to/kit` compares a neighboring kit).\n\nIn environments where v0.1 was installed, the v0.1 materials are archived under `.loop-engineering-backups/<timestamp>/`. The migration is recorded in a migration report under `.agent-loop/state/reports/`. See `llmwiki/runbooks/install.md` for the operational procedure.\n\n## Run cycle\n\n```bash\ncd /path/to/repository\n# `./loopeng.py` is the equivalent short form of `python3 -m loopeng`.\npython3 -m loopeng okf init llmwiki        # 初回のみ\n\nRUN_ID=$(date +%Y%m%d-%H%M%S)\npython3 -m loopeng journal add --run \"$RUN_ID\" \\\n  --event '{\"kind\":\"run-start\",\"agent\":\"codex\",\"goal\":\"...\"}'\n# ... エージェント作業。protected path に触れる前に intent を宣言し、\n#     各ステップを journal に追記する ...\npython3 -m loopeng okf apply memory-report.json --bundle llmwiki   # メモリ更新がある場合\npython3 -m loopeng journal add --run \"$RUN_ID\" --event '{\"kind\":\"run-end\"}'\npython3 -m loopeng audit run --run \"$RUN_ID\"   # Run Report + handoff を生成\npython3 -m loopeng schedule next               # 次ターンの前文\n```\n\nWhen the Run Report contains critical alerts (such as an undeclared protected-path change or a mutation missing from the journal), it receives a banner requiring human review at the top. The banner does not retroactively invalidate the work, but acceptance of completion should be decided after review.\n\n## Documentation map\n\n| Doc | What |\n|---|---|\n| `docs/ARCHITECTURE.md` | v0.2 architecture and control policy, including hard-block enforcement points. |\n| `docs/RUN_REPORT.md` | Run Report schema and journal event conventions. |\n| `docs/OKF_LLMWIKI.md` | Durable-memory rules and transactions for OKF LLMWiki. |\n| `llmwiki/runbooks/install.md` | Profiles, updates, and convergence migration from v0.1. |\n| `docs/LOOP_INPUT_GUIDE.md` | Human input required for autonomous runs. |\n| `docs/RELEASE_AUDIT.md` | Completion protocol and pre-push audit guard. |\n| `docs/DESIGN_PHILOSOPHY.md` | Design principles (single declaration point, mechanism first, and so on). |\n| `docs/v0.2-phase1/` | v0.2 redesign implementation instructions and audit records (historical materials). |\n\n## Development\n\nDevelopment of this repository follows these disciplines: changes are performed as journaled runs, and completion is claimed through a Run Report. Release-bound changes must pass the audit record from `utils/audit_guard.py record` before being pushed. The acceptance gates (`utils/phase1_gate.py` / `utils/phase1_gate_ext.py`) must remain GREEN, and the gates themselves must not be changed.\n\n## Status\n\nv0.2 series (active development). The version restarts from the v15 line (v0.1 design) and is not compatible with v0.1. The v0.1 governance mechanisms (Gatekeeper / Sensemaker / Loop Brief, the `route:` / `brief:` / `direct:` entry points, the Go implementation, and OTel/systemd residency) are retired and replaced by convergence migration with `--update`. Implemented in this release: shared hooks, `review:`/`review dag`, and audit-record absorption. Ongoing extensions:\n\n<!-- ongoing-start -->\nnone\n<!-- ongoing-end -->\n\nMemory retrieval follows `index.md → okf query → top K (default 5) document reads`; do not bulk-read `llmwiki/`.\nExplicit feedback can be recorded with `learning feedback`; it creates a proposal under `.agent-loop/state/skill-drafts/` and never overwrites a skill source automatically. `knowledge gaps` reports observable signals such as recurrence, unresolved acceptance, or pending learning, and is included in the next-turn context when present.\n`retrospective` is a read-only cross-run analysis. It separates facts, recurring patterns, data-quality gaps, knowledge gaps, and suggested actions; it never applies skill or memory changes automatically. Use `--record` only to append a `review_type: retrospective` review event.\nCommands that accept `--run` also accept `latest`, `latest-due`, and `latest-fail`; the resolved run ID is printed to stderr. `latest-due` excludes runs already accepted by `review intake`.\n\nReviews use a deliberate same-family compromise: Codex reviews declare `self-family` and must be performed in a new session, then pass human TUI meta-review with a random evidence spot check. One in every five due reviews remains reserved for an `external` reviewer; `review calibration` reports the comparison.\n`okf query` defaults to the current framework/project space; use `--space all` for an explicit cross-space read. `memory stats` and `memory efficacy` likewise support `--space` and report only the selected space.\nProvisional entries are observations; prefer established entries as the basis for constraints and decisions. `memory curate` may apply only bounded provisional UPSERTs in autonomous namespaces; other drafts require explicit user instruction.\n\nLicensed under the MIT License.\n",
  "bytes": 10549,
  "sha": "2a7b35b059f4a2dfb229aa43b5e14364955a0fe5ffca6458540c5941758bc493",
  "repo_slug": "fumihito/loopeng-bootstrap",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_fumihito_loopeng_bootstrap_llmwiki_index_b013b345/readme"
}