ultra-builder-pro-cli 0.25.0 → 0.26.0

package/docs/SKILL-AUTHORING.md

@@ -1,75 +1,96 @@
 # Skill authoring contract
 
-Ultra Builder Pro keeps one portable source workflow and adapts only runtime metadata
-or host invocation details. This contract follows OpenAI Skills guidance and the Agent
-Skills progressive-disclosure format:
-
-- <https://learn.chatgpt.com/docs/build-skills>
-- <https://learn.chatgpt.com/docs/customization/overview>
-- <https://agentskills.io/specification>
-- <https://agentskills.io/skill-creation/best-practices>
-
-## Surface ownership
-
-| Content | Owner |
-|---|---|
-| Repeatable task procedure and conditional references | `skills/<name>/SKILL.md` |
-| Codex display, invocation policy, and dependencies | `skills/<name>/agents/openai.yaml` after adaptation |
-| Host launcher | `commands/<name>.md` |
-| Durable repository or user engineering policy | `AGENTS.md` or the host equivalent |
-| Deterministic lifecycle enforcement | one hook implementation |
-| Live external data or actions | MCP server or connector |
-| Bounded delegated role | `agents/<name>.md` |
-
-Do not duplicate a rule across these surfaces.
-
-## Portable `SKILL.md`
-
-Source frontmatter contains only `name` and `description`. The description says what
-the Skill does and when it should activate. The body uses imperative, outcome-oriented
-steps and includes only information an agent cannot reliably infer from the task,
-repository, or host policy.
-
-Keep the main file compact. Move conditional domain detail to `references/`, reusable
-deterministic work to `scripts/`, and output material to `assets/`. Reference a file
-only from the main workflow or one directly relevant reference.
-
-## Language
-
-The standards do not prohibit Chinese. Ultra source prompts use English as a project
-policy because one source is transformed for Claude Code, Codex, OpenCode, Kimi Code,
-and Grok Build. The host or user instruction controls the response language; a workflow must not
-hard-code the user's output language unless language is itself part of the task.
-
-Maintainer documentation may use the language appropriate for its audience. English
-source prompts are a portability rule, not a claim that multilingual Skills are invalid.
-
-## Content that does not belong in a Skill prompt
-
-- release notes, migration history, old-version behavior, or implementation diary;
-- host tool inventories, model pins, package paths, and dependency metadata shared by
-  only one runtime;
-- generic engineering doctrine already owned by user or repository instructions;
-- one-off project facts, volatile external facts, or copied datasets;
-- duplicated command bodies, hook policy, MCP schemas, or private memory behavior;
-- arbitrary coverage, confidence, complexity, option-count, or severity thresholds;
-- pattern matching that turns TODOs, mocks, catch blocks, or line counts directly into
-  findings without a reachable impact;
-- tutorial-style old/new or good/bad comparisons that do not change the workflow;
-- menus of hypothetical alternatives when one repository default already satisfies the
-  contract.
-
-Comparison is appropriate only when the task requires a real decision or verification:
-compare credible alternatives against shared constraints, accepted specification
-against delivered behavior, or independent analyses against authoritative evidence.
-
-## Review checklist
-
-1. Does the description state a precise use condition?
-2. Is every instruction reusable for this Skill rather than copied global policy?
-3. Is host-specific metadata outside the portable prompt?
-4. Does each conditional reference earn its context cost?
-5. Are judgments evidence-based rather than threshold-based?
-6. Are commands thin and agents bounded?
-7. Do positive and negative trigger evals cover accidental activation?
-8. Do source, five generated runtimes, and package contents pass validation?
+Ultra Skills are portable model-facing methods. They describe outcomes, evidence, and
+owner boundaries; host-specific discovery and invocation policy belong in adapters.
+
+## Role selection
+
+Choose exactly one role before writing:
+
+- **user-invoked**: a complete owner-selected workflow with a durable outcome;
+- **model-invoked**: a reusable discipline used by at least two canonical workflows;
+- **router**: read-only diagnosis that recommends the smallest next public route.
+
+A user workflow may recommend but must not invoke another user workflow. A discipline
+with only one real caller should be inlined.
+
+## Portable frontmatter
+
+Source `SKILL.md` frontmatter contains only:
+
+```yaml
+---
+name: lower-case-hyphen-name
+description: What this produces and the concrete situations that trigger it.
+---
+```
+
+Adapters generate Claude/Grok/Kimi invocation flags and Codex `agents/openai.yaml`.
+Do not put host paths, dependency declarations, plugin policy, or release history in
+source frontmatter.
+
+## Required shape
+
+Every Skill has one outcome-led title and these semantic sections:
+
+```text
+## Before you start
+## Definition of done
+## <workflow-specific process>
+## When the owner decides
+## References
+```
+
+User workflows begin by reading `.ultra/tasks.json`, the unfinished task's
+`context_file` and Resume Note, `CONTEXT.md`, and relevant decisions. They name the
+files they write and read them back. Completion criteria must be observable without a
+semantic validator.
+
+Use positive leading words consistently: tracer bullet, seam, deep module, red,
+frontier, and fog of war. Explain a branch by its checkable result, not the model's
+reason for choosing it.
+
+## Progressive disclosure
+
+Keep resident `SKILL.md` short enough to load on every invocation. Move focused detail
+into `references/` and deterministic validation or waiting into `scripts/`.
+
+- Load one research step or review lens at a time.
+- Keep one canonical copy of grilling, TDD, review, domain language, and autonomy rules.
+- Cross-reference another model-invoked Skill by relative path.
+- Do not hide the primary workflow in a script.
+- A script may check paths, schemas, counts, hashes, process status, or other mechanical
+  facts; it may not decide semantic completeness.
+
+Rule-side executable examples live with the consuming Skill. They are never copied
+wholesale into project authority.
+
+## Language and host neutrality
+
+Model-facing Skills, references, scripts, comments, and identifiers are English.
+Shared Skills never mention `.claude`, `.codex`, `.opencode`, `.kimi`, `.grok`, or a
+host-only question surface. Use “host-native question surface” and put the translation
+in the adapter.
+
+## Safety boundary
+
+The owner decides intent, acceptance, reductions, material risk, irreversible actions,
+and external effects. The model owns investigation, design, decomposition, evidence
+interpretation, reversible implementation detail, and final expression.
+
+Semantic gaps are diagnostics. A Skill must not invent a hard gate based on counters,
+regexes, similarity, context estimates, or workflow position. Every real hard effect
+guard names its invariant, authoritative input, blocked effect, and reachable repair.
+
+## Validation
+
+For every changed Skill:
+
+1. run the Skill Creator validator;
+2. resolve every relative reference in the source and installed artifact;
+3. verify its role metadata on all five hosts;
+4. test the accepted workflow with representative valid and adversarial inputs;
+5. confirm no retired runtime vocabulary or host-specific path entered portable text.
+
+The repository's `tests/skill-authoring.test.cjs` and
+`tests/v026-contract.test.cjs` mechanize the portable parts of this contract.

package/docs/WORKFLOW-LIFECYCLE.md

@@ -1,230 +1,134 @@
 # Ultra Builder Pro workflow lifecycle
 
-Ultra is an adaptive capability graph, not an automatically chained pipeline. The
-current Skill inspects authority and recommends a next capability. The user explicitly
-starts that capability. Skills own semantic procedure; the seven-tool MCP kernel owns
-persistence and mechanical safety across Claude Code, Codex, OpenCode, Kimi Code, and
-Grok Build.
-
-## Capability graph
-
-```mermaid
-flowchart TD
-    START["Project"] --> INIT["ultra-init"]
-    INIT --> RESEARCH["ultra-research"]
-    RESEARCH --> THINK["ultra-think when a material decision remains"]
-    THINK --> RESEARCH
-    RESEARCH --> CHANGE["ultra-change"]
-    CHANGE --> ROUTE{"What does this Change actually need?"}
-    ROUTE -->|"Evidence gap"| CR["bounded ultra-research"]
-    CR --> ROUTE
-    ROUTE -->|"Implementation"| PLAN["ultra-plan"]
-    PLAN --> DEV["ultra-dev for one owned Task"]
-    DEV --> MORE{"More executable Tasks?"}
-    MORE -->|"Yes"| DEV
-    MORE -->|"No"| ASSESS{"What evidence is still warranted?"}
-    ROUTE -->|"No implementation; current evidence is sufficient"| ASSESS
-    ASSESS -->|"Risk-selected verification"| TEST["ultra-test"]
-    ASSESS -->|"Independent review"| REVIEW["ultra-review"]
-    ASSESS -->|"Caller accepts current packet and explicit omissions"| DELIVER["ultra-deliver"]
-    TEST -->|"implementation gap"| DEV
-    TEST -->|"review warranted"| REVIEW
-    TEST -->|"caller accepts evidence"| DELIVER
-    REVIEW -->|"implementation issue"| DEV
-    REVIEW -->|"contract issue"| PLAN
-    REVIEW -->|"accepted"| DELIVER
-    DELIVER --> CHANGE
-    STATUS["ultra-status"] -.-> INIT
-    STATUS -.-> CHANGE
-    DOCTOR["ultra-doctor"] -.-> INIT
-    DOCTOR -.-> CHANGE
-```
+Ultra v0.26 has no fixed runtime state machine. Skills define checkable entry and exit
+criteria; repository files record facts; the host model chooses the route.
 
-The graph is guidance, not database authorization. The host model selects the evidence
-needed by the actual Change route and records every deliberate omission in the delivery
-handoff. When implementation occurs, its Plan, Task contract, and Context remain
-mandatory execution authority; Research, Test, and Review are used according to the
-actual evidence and risk rather than as universal archive gates. `ultra-status` is
-read-only. `ultra-doctor` repairs mechanical authority only.
-
-## Shared command contract
-
-Every public Skill follows the same boundary:
-
-1. read the current `ultra.context`;
-2. inspect checkout/runtime facts directly;
-3. identify the smallest unresolved semantic choice;
-4. recommend a route and ask only when user intent is not already explicit;
-5. persist normalized facts through typed `ultra.record`;
-6. update the owning semantic/evidence files;
-7. save or accept the stage through `ultra.checkpoint`;
-8. read back current authority;
-9. report diagnostics and recommend, but do not launch, the next Skill.
-
-No command records ceremonial steps merely to satisfy SQLite.
-
-## Capability ownership
-
-| Skill | Semantic owner | Durable output |
-|---|---|---|
-| `ultra-init` | repository classification, scope, Git/runtime bootstrap | initialized local authority and empty/imported team checkpoint |
-| `ultra-research` | adaptive evidence coverage and accepted baseline | baseline specs, research evidence, Decision Records, baseline checkpoint |
-| `ultra-think` | one load-bearing owner decision or bounded diagnosis | normalized Decision Record and applied references |
-| `ultra-change` | feature/fix/refactor/incident contract | active Change intent, classification, delta and decision scope |
-| `ultra-plan` | Task contracts, topology, ownership, acceptance coverage | accepted Plan checkpoint, deterministic plan files, team checkpoint |
-| `ultra-dev` | one owned vertical Task implementation | Worker Packet output, task outcome, implementation evidence checkpoint |
-| `ultra-test` | risk-selected executable validation | test report and accepted test checkpoint |
-| `ultra-review` | independent spec fidelity and engineering quality | specialist artifacts, coordinated summary, accepted review checkpoint |
-| `ultra-deliver` | documentation/spec reconciliation and local archive | delivery evidence, converged baseline, immutable archive, team checkpoint |
-| `ultra-status` | current Context rendering | no state mutation |
-| `ultra-doctor` | mechanical health, migration, backup and repair | diagnostic/repair report; no product decision |
-
-## Context and decisions
-
-One canonical Context Envelope flows through Skill, Hook, Session, Agent, and compact
-recovery. Accepted Decision Records are always visible, including when no workflow is
-active. A new session therefore resumes from accepted intent rather than reconstructing
-it from conversation.
-
-Decision history is append-only through supersession:
+## Capability flow
 
 ```text
-proposed -> accepted -> superseded
-         -> rejected
-```
+ultra-init
+    ├─ unresolved external claims ─► ultra-research
+    └─ bounded requested outcome ──► ultra-change
 
-The status of a proposal never grants execution authority. The accepted record, its
-digest, applied references, and the owning checkpoint do.
+ultra-change ─► ultra-plan ─► ultra-dev (per task) ─► ultra-test ─► ultra-deliver
+                     ▲                 │                    │
+                     └── replan ◄──────┘                    └── findings return to owner/model
 
-## Checkpoints, not fixed steps
+ultra-status    read-only router at any point
+ultra-delegate  orthogonal bounded execution on another CLI
+```
 
-Stage authority is revisioned:
+Arrows are recommendations, not automatic invocation. The owner explicitly selects
+each public workflow.
 
-```text
-draft revision N
-  -> accepted revision N
-  -> accepted revision N+1 supersedes N
-```
+## Common entry contract
 
-Semantic diagnostics remain recorded but do not reject the model's explicit
-checkpoint conclusion. A structural, digest, path, publication, or concurrency
-conflict keeps the same draft mutable. Plan export is part of Plan checkpoint
-publication, so changing a Task contract before acceptance cannot invalidate an
-already-recorded “export step.” There is no locked intermediate run to cancel or
-manually repair.
+Every user-invoked Skill reads, in order:
 
-Accepted checkpoints are immutable evidence. New facts create a replacement draft.
-Only archive history is terminal; subsequent product work opens a new Change.
+1. `.ultra/tasks.json`;
+2. the unfinished task's `context_file` and closing `## Resume Note`;
+3. `CONTEXT.md` and relevant `.ultra/decisions/`;
+4. the active Change, specifications, evidence, and Git state relevant to its scope.
 
-## Change lifecycle
+Missing files produce a precise recovery or initialization recommendation. They do not
+cause the Skill to invent a state transition.
 
-Live v0.24 writes only:
+## Initialization
 
-```text
-active -> archived
-   |
-   -> cancelled
-```
+`ultra-init` distinguishes owner authorization from claims requiring evidence. It
+creates the file skeleton, preserves unknowns as `[NEEDS CLARIFICATION]`, initializes
+Git when absent, and records only repository-observable brownfield facts. It does not
+perform research or launch another workflow.
 
-`blocked`, `ready`, and `needs_attention` are derived diagnostics, not absorbing Change
-states. An active Change may be revised. The Deliver Skill inspects the relevant Task,
-Context, test, review, documentation, and delivery evidence, decides semantic
-sufficiency, and records deliberate omissions. Archive validates the explicit handoff,
-current authority, reconciliation structure, and safe recoverable filesystem/DB
-transaction without enforcing a fixed stage sequence. Archived bytes remain immutable.
+## Research
 
-Older `ready` or `blocked` rows are readable migration history. They do not authorize
-new work until migration/revalidation derives current checkpoint authority.
+`ultra-research` maps unresolved claims to the smallest useful subset of seventeen
+focused references. Reports are written immediately. Three material checkpoints can
+change later scope; the owner resolves those checkpoints. The final distillate records
+Git blob hashes of the specifications it summarizes.
 
-## Task and Session lifecycle
+## Change reconciliation
 
-Task durable outcomes remain portable:
+`ultra-change` first compares requested behavior with product truth and current code.
+It classifies changes by the resulting commitments:
 
-```text
-pending -> in_progress -> completed
-   |          |              |
-   |          -> blocked     -> in_progress (explicit reopen)
-   -> blocked
-   -> cancelled
-```
+- expansion and correction may proceed inside accepted intent;
+- a reduction waits for explicit owner authority.
 
-`in_progress`, Worker ownership, leases, PIDs, heartbeats, worktrees, and completion
-commit backfill are checkout-local. They are not published to Git.
-Reopening a completed Task clears the local completion/session fields, preserves the
-prior completion commit in an append-only `task_reopened` event, and requires a new
-durable outcome before it can be completed again.
+The output is one active Change intent with observable outcome, acceptance, seams,
+non-goals, and trace anchors.
 
-`ultra.session acquire` atomically:
+## Planning
 
-1. checks a real lease/CAS conflict;
-2. compiles or reuses the exact Context Envelope;
-3. creates an immutable Worker Packet;
-4. allocates the lease/worktree;
-5. returns packet path/digest and exact execution boundary.
+`ultra-plan` confirms the scope posture and public seams, then writes a task graph and
+one context file per task. Feature tasks are tracer bullets. A contract task precedes
+cross-process or cross-top-level-boundary implementations; integration checkpoints
+appear after several slices. Cycles and broken trace paths are repaired before handoff.
 
-A missing semantic detail is diagnostic, not a transport failure. A genuine lease,
-digest, unsafe path, or concurrent authority conflict fails closed. Optional
-orchestration can dispatch only a Change-owned Task with an accepted Plan checkpoint
-and assigned Worker Packet.
+## Task development
 
-## Team sync
+`ultra-dev` writes the implementation plan into the task context before code. It uses
+`ultra-tdd` on confirmed seams, records six evidence dimensions, and keeps ledger and
+context status synchronized. The closing Resume Note is rewritten even when work stops
+early.
 
-`.ultra/tasks/tasks.json` is a tracked, digest-chained team checkpoint. It carries
-portable baseline, Change, Decision summary/reference, accepted Stage Checkpoint, Task
-contract, dependency, and durable outcome records. It excludes local execution state.
+Task review uses six independent lenses. Findings move through stable JSON artifacts,
+not intermediate worker chatter. Refactoring happens after the evidence makes real
+duplication or coupling visible.
 
-`ultra.sync` supports:
+## Whole-system audit
 
-- `inspect`: side-effect-free condition and migration advice;
-- `migrate`: exact-byte backup-first legacy conversion;
-- `import`: schema/digest/ancestry/CAS validation and clean fast-forward;
-- `publish`: reconcile incoming Git authority, then publish one new generation.
+`ultra-test` runs once after the ledger is complete. It checks anti-patterns, coverage,
+wiring, E2E behavior, performance, and security. It names the exact Git commit and
+never turns an orphan, failed command, stub, or omission into permission to alter scope.
 
-Same-record concurrent edits return a typed conflict. Ultra does not silently choose
-one intent. Imported accepted baseline authority requires checkout-local source/spec
-revalidation before descendant publication.
+## Delivery
 
-Metadata-only Ultra commits do not make a baseline stale. Source or specification
-drift remains visible and may require revalidation.
+`ultra-deliver` reconciles actual outcome, specifications, documentation, current test
+report, aggregate review, build, version impact, omissions, and rollback. It archives
+the Change with `git mv` after local reconciliation.
 
-## Hook lifecycle
+Commit, push, tag, publication, release, and deployment are independent external
+effects. Readiness grants none automatically.
 
-Hooks do not drive the capability graph. They:
+## Status routing
 
-- inject a bounded Context Envelope where the host consumes it;
-- protect the team checkpoint and generated projections from direct writes;
-- save/restore minimal compact recovery state;
-- record minimal lifecycle identifiers;
-- return advisory Stop context.
+`ultra-status` infers the smallest next route from observable files:
 
-When a host ignores Hook stdout, the adapter records health/events only and every Skill
-reads `ultra.context` explicitly. Hook limitations are never presented as successful
-context injection.
+- no healthy skeleton → init;
+- unresolved evidence-bearing claim → research;
+- requested outcome without active Change → change;
+- active Change without executable ledger → plan;
+- pending or in-progress task → dev;
+- completed ledger without current report → test;
+- current report and unarchived Change → deliver.
 
-## Recovery
+It also checks installation provenance, stale reports, old in-progress work, and
+unresolved markers. It does not mutate artifacts.
 
-Use `ultra.context` first; legacy input must return a discoverable migration action
-instead of blocking diagnosis. Use `ultra.sync migrate` for semantic conversion and
-`ultra.doctor { repair: true }` for mechanical backup/recovery.
+## Artifact closure
 
-Migration supports v4.4/v4.5 projections and v0.22/v0.23 database/ledger authority.
-It is exact-byte backup-first, transactional, and fail-closed on conflict. Legacy
-workflow/dialogue rows survive as history but do not authorize current work.
+Every durable output has a later reader:
 
-Repair never invents a product choice, edits a semantic artifact to make it pass, or
-asks the user to hand-edit SQLite.
+- init's north star and specification skeletons are read by all later workflows;
+- research reports are traced into specifications, Change reconciliation, planning,
+  and delivery;
+- Change intent is consumed through planning, development, audit, review, status, and
+  delivery;
+- task ledger and contexts are the common resume input, while task evidence feeds
+  review, whole-system audit, and delivery;
+- the current test report is consumed by status and delivery;
+- delivery moves with the Change into archive and remains historical evidence.
 
-## Hard-error boundary
+`ultra-status` intentionally writes nothing. Review, Hook, compact, and delegation
+files are derived observations with explicit rebuild or rerun paths. No route creates
+an unowned drift log, Change plan, technical-debt report, or second delivery summary.
 
-Only these classes fail the tool call:
+## Interruption and cross-host continuation
 
-- database/schema corruption;
-- unsafe path, symlink, or identity swap;
-- actual digest, CAS, or lease concurrency conflict;
-- missing/incompatible native runtime;
-- permission failure;
-- archive/publish/deploy or another irreversible external-effect failure.
+Before stopping, the active task context records current facts, exact verification,
+open questions, Completion, and a closing Resume Note. The next session or host repeats
+the common entry contract and compares the working tree with those claims.
 
-Evidence gaps, incomplete exploration, stale optional context, missing reports, or
-other semantic insufficiency are structured diagnostics. The model remains responsible
-for investigating, revising, accepting, or explicitly recording an omission.
+This path remains valid when hooks and `ubp` are disabled. A compact snapshot may be
+used as a hint, then checked against canonical files and Git.

package/hooks/README.md

@@ -1,42 +1,22 @@
-# Ultra Builder Pro workflow hooks
+# Ultra Builder Pro hooks
 
-These Hooks observe only Ultra-owned state. Session health/context recognizes an
-initialized `.ultra/.runtime/state.db` and reads the canonical Context Envelope.
-Direct writes to the MCP-owned Git checkpoint and checkout-local projections remain
-blocked; context, compact, stop, and agent lifecycle behavior is recovery-oriented and
-does not turn semantic diagnostics into refusal gates.
+Ultra ships five small file-first hooks. Every hook first looks for a `.ultra/`
+directory and exits silently when the workflow is not active.
 
-| Lifecycle | Hook | Purpose |
+| Hook | Lifecycle | Purpose |
 |---|---|---|
-| Session start | `health_check.py` | Read-only integrity, incident, projection, session, and change-artifact checks |
-| Shared helper | `context_envelope.py` | Read the same bounded Context Envelope used by MCP, Skills, Sessions, and Workers |
-| Session start | `workflow_context.py` | Inject the compact envelope with accepted intent, never raw interaction or provider payloads |
-| Before edit | `active_task_context.py` | Protect `.ultra/tasks/tasks.json` (Git team checkpoint) and `.ultra/.runtime/projections/tasks.json` (local view), then restate the same DB-derived task breadcrumb |
-| Before compact | `workflow_checkpoint.py` | Validate and atomically save a minimal workflow checkpoint |
-| After compact/resume | `workflow_resume.py` | Prefer the DB breadcrumb; restore the minimal file checkpoint only when no active change owns recovery |
-| Stop | `pre_stop_check.py` | Report an incomplete workflow boundary and allow stop |
-| Subagent lifecycle | `subagent_tracker.py` | Append minimal start/stop metadata to the authoritative DB event stream |
+| `session_context.py` | Session start | Inject the one-line north star and current acceptance criteria |
+| `mid_workflow_recall.py` | Before source reads or edits | Restate current acceptance only |
+| `compact_context.py` | Before/after compaction | Save and restore a disposable snapshot derived from files and Git |
+| `post_edit_guard.py` | After edits | Record mechanical evidence observations without deciding completion |
+| `block_dangerous_commands.py` | Before shell execution | Block a narrow named external effect until the exact command is owner-authorized |
 
-The plugin deliberately does not capture prompts, tool observations, transcripts, summaries, general
-conversational memory, or code-graph payloads. It does retain project-local Ultra workflow memory in
-`.ultra/`. Generic command blocking and post-edit policy are user/repository governance. General
-memory and graph content belongs to separately installed providers.
+`_common.py` is a shared library, not a lifecycle registration. Compact snapshots and
+progress observations live under ignored `.ultra/.runtime/` or `.ultra/progress/`; the
+canonical semantic facts remain the owner-readable files and Git.
 
-`subagent_tracker.py` passes only agent id/type and the host session id to the bundled
-`hook-event.cjs` helper. The helper binds the current change/task and appends
-`subagent_started` or `subagent_stopped` to `state.db`; it never stores transcript
-paths, messages, or a parallel JSONL lifecycle log.
-
-`context_envelope.py` is an imported library, not an additional lifecycle registration.
-Registering it separately would duplicate hook execution. The checkpoint is a recovery artifact, not a second authority. A valid newer
-live workflow wins; a newer valid checkpoint may restore a missing or older
-live file; corrupt, non-object, or terminal checkpoints are ignored.
-
-Runtime wiring:
-
-- Claude Code: native `hooks/hooks.json` with `${CLAUDE_PLUGIN_ROOT}` paths.
-- Codex: native `hooks/hooks.json` through `hooks/adapters/codex.py` for wire normalization.
-- OpenCode: native JavaScript plugin events; the Python hook suite is not copied.
-- Kimi Code: native lifecycle events through its wire adapter.
-- Grok Build: camelCase lifecycle events; ignored stdout channels are used for
-  observation only, and every Skill rereads authoritative Context at entry.
+Claude Code runs the hooks directly. Codex, Kimi Code, and Grok Build use the small
+wire adapters under `hooks/adapters/`. OpenCode calls the same scripts from its native
+JavaScript plugin. A hook failure is advisory except for the explicitly classified
+external effects in `block_dangerous_commands.py`, whose denial includes a reachable
+SHA-256-scoped authorization path.