@a5c-ai/babysitter-codex 0.1.6-staging.2dca8387

package/AGENTS.md

@@ -0,0 +1,91 @@
+# Agent Instructions -- Babysitter for Codex CLI
+
+This file governs agent behavior when the `babysitter-codex` skill bundle is
+installed into Codex. Babysitter owns orchestration through the SDK runtime and
+Codex lifecycle hooks. Do not replace that model with an external orchestrator
+for the plugin path.
+
+## 1. How Babysitter Integrates With Codex
+
+Babysitter for Codex is made of:
+
+- the installed Codex skill payload under `~/.codex/skills/babysitter-codex`
+- workspace `.codex/hooks.json` registrations
+- workspace `.codex/config.toml` feature flags
+- the `.a5c/` runtime state directory
+- the Babysitter SDK CLI for run creation, iteration, status, and result posting
+
+The plugin path supports only the hooks model:
+
+- `SessionStart` seeds session state needed by the runtime
+- `UserPromptSubmit` can transform or enrich prompt-time context
+- `Stop` is the continuation point that keeps Babysitter in the orchestration loop
+
+Do not introduce an app-server loop, a polling wrapper, or a hidden supervisor
+for normal Codex plugin operation.
+
+## 2. User-Facing Activation
+
+Prefer natural language command phrases inside Codex, for example:
+
+- `babysitter call <goal>`
+- `babysitter resume`
+- `babysitter doctor`
+- `babysitter team-install`
+- `babysitter project-install`
+
+Treat these as the Codex-facing entrypoints. Raw SDK CLI commands are runtime
+plumbing and should stay behind the skill and hook flow unless the task
+explicitly requires low-level diagnosis.
+
+## 3. Runtime Contract
+
+Babysitter orchestration is driven with the SDK CLI:
+
+- `babysitter run:create`
+- `babysitter run:iterate`
+- `babysitter run:status`
+- `babysitter task:list`
+- `babysitter task:post`
+- `babysitter process-library:active`
+
+When a Codex session identifier is available, bind it honestly with
+`--harness codex --session-id <id>`.
+
+Never fabricate session IDs. Never write task `result.json` files directly.
+Write the value payload to the task output location and post it through
+`babysitter task:post`.
+
+## 4. Process Library Model
+
+The Codex package does not bundle the process library. Workspace onboarding must
+use the SDK CLI to clone or update the upstream Babysitter repository and bind
+the active process root for the current workspace.
+
+Preferred lookup order:
+
+1. project-local `.a5c/processes`
+2. the active process-library binding from
+   `babysitter process-library:active --state-dir .a5c --json`
+
+Do not instruct users to copy process files out of the package payload.
+
+## 5. Hook-Driven Loop Rules
+
+During an active run:
+
+1. create or resume the run
+2. execute the current requested work
+3. post the result back through the SDK
+4. yield control so the `Stop` hook can decide the next continuation step
+
+Do not manually spin a multi-iteration loop inside one Codex turn when the hook
+model is active. The runtime must remain aligned with the lifecycle hooks.
+
+## 6. Completion
+
+Only when the run is actually completed should the final proof be emitted as:
+
+`<promise>PROOF_VALUE</promise>`
+
+Do not emit a promise tag early.

package/CHANGELOG.md

@@ -0,0 +1,162 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [Unreleased]
+
+### Fixed
+- Dropped the bundled `upstream/babysitter` snapshot from the plugin payload.
+- `team-install` and postinstall onboarding now rely on the SDK CLI to
+  clone/update/use the original process library for the active workspace.
+- Packaged docs and tests no longer claim deleted runtime artifacts such as the
+  old process-mining helper or maintainer runbook.
+
+### Changed
+- Added manifest scripts and `prepack` regeneration so packaged integrity data
+  matches the actual shipped payload.
+- Updated packaged metadata to point at the `a5c-ai/babysitter` repository.
+
+## [0.1.5] - 2026-03-11
+
+### Added
+- Team setup/install flow and lock architecture:
+  - `babysitter.lock.json`
+  - `babysitter:team-install`
+  - `scripts/team-install.js`
+- Runtime/content package split scaffolding (`packages/runtime`, `packages/content`).
+- Layered rules resolution and defaults (`.codex/rules-resolver.js`, `config/rules/*`).
+- Lazy process index cache (`.codex/process-index.js`) integrated into discovery.
+- Content integrity pipeline:
+  - `scripts/generate-content-manifest.js`
+  - `scripts/verify-content-manifest.js`
+  - `config/content-manifest.json`
+- Mapping contract checks and CI gates (`scripts/check-mapping-contract.js`, workflow updates).
+- Architecture docs:
+  - `docs/ARCHITECTURE_UPGRADES_1_8.md`
+  - `docs/CODEX_MAPPING.md` updates
+
+### Changed
+- Plugin manifest version bumped to `4.0.149`.
+- npm package version bumped to `0.1.5`.
+- README updated for version/mode changes and refreshed Blame Beni section.
+- Fixed command metadata regression in `.codex/plugin.json` (restored per-command descriptions).
+
+### Added
+- Runtime/content package split scaffolding:
+  - `packages/runtime`
+  - `packages/content`
+- Lock and install architecture:
+  - `babysitter.lock.json`
+  - `scripts/team-install.js`
+  - new command: `babysitter:team-install`
+- Layered rules architecture:
+  - `.codex/rules-resolver.js`
+  - `config/rules/upstream-base.json`
+  - `config/rules/team/default.json`
+- Lazy process library indexing:
+  - `.codex/process-index.js`
+  - discovery integration for indexed lookup metadata
+- Secure content channel primitives:
+  - `scripts/generate-content-manifest.js`
+  - `scripts/verify-content-manifest.js`
+  - optional HMAC signature validation
+- Mapping contract gate:
+  - `scripts/check-mapping-contract.js`
+  - CI enforcement (`check:mapping`, `manifest:verify`, `team:install` smoke)
+- Bundled full upstream Babysitter skill/process/reference library snapshot under `upstream/babysitter/`.
+- Added Codex command mapping manifest: `config/codex-command-map.json`.
+- Added new Codex command mode: `babysitter:retrospect`.
+- Added mapping/runtime helpers:
+  - `.codex/process-library.js`
+  - `.codex/codex-mapping.js`
+  - discovery now reports mapped `processLibraryRoot`/`referenceRoot`.
+- Foundation modules for prioritized roadmap delivery:
+  - feature flags (`.codex/feature-flags.js`)
+  - session index (`.codex/state-index.js`)
+  - event stream + notifications (`.codex/event-stream.js`)
+  - policy engine (`.codex/policy-engine.js`)
+  - model routing (`.codex/model-router.js`)
+  - telemetry + budget checks (`.codex/telemetry.js`)
+  - workspace manager (`.codex/workspace-manager.js`)
+  - MCP doctor scaffold (`.codex/mcp-doctor.js`)
+  - eval harness scaffold (`.codex/eval-harness.js`)
+  - GitHub issue workflow helper (`.codex/github-workflow.js`)
+- New hook lifecycle types: `on-tool-error`, `on-policy-block`, `on-retry`.
+- Roadmap doc and feature-request issue template.
+- Feature-complete implementation pass for requested items 1-10:
+  - selector-based session UX (`list`, `search`, alias/tag management)
+  - event stream IDs/sequence and configurable notification sinks (including file sink)
+  - policy config with staged approvals + strict allowlists
+  - persisted model routing policy (`.a5c/config/model-policy.json`)
+  - richer MCP doctor checks + recommendations
+  - GitHub issue flow with comments, apply mode, and optional PR update/create paths
+  - telemetry history and explicit budget phase states (`normal`/`soft-limit`/`hard-stop`)
+  - docs: `docs/FEATURES_1_10.md`
+
+### Changed
+- Fixed plugin command metadata regression: per-command descriptions restored in `.codex/plugin.json`.
+- Command surface increased to 15 modes with `team-install`.
+- Updated plugin manifest command set to 15 commands (including `retrospect` and `team-install`) and version `4.0.148`.
+- Updated docs/tests for 15-mode parity and upstream-library mapping.
+- `orchestrate.js` now emits structured events, supports policy/model/telemetry integration, and records session metadata for resume UX.
+- `on-turn-complete` now emits event-stream notifications.
+- Dispatcher now executes concrete mode handlers for `model`, `issue`, `resume` selectors, and `doctor mcp`.
+- Orchestrator now supports multi-repo alias workdirs and adaptive prompt shrinking under budget pressure.
+- Added upstream sync/parity tooling and documentation (`sync:upstream`, `check:upstream`).
+- Added explicit compatibility policy checks (`check:compat`) and CI enforcement.
+- Added maintainer runbook and real-world validation docs.
+
+## [0.1.4] - 2026-03-07
+
+### Added
+- First-class macOS support documentation and install verification steps.
+- Cross-platform long-session scenario runner: `test/full-session-long-run.js`.
+- GitHub Actions CI matrix for `macos-13`, `ubuntu-latest`, and `windows-2022` on Node `20` and `22`.
+- Shared SDK package resolver (`.codex/sdk-package.js`) used by runtime/test entrypoints.
+
+### Changed
+- Runtime hooks now resolve SDK package via `BABYSITTER_SDK_PACKAGE`/`BABYSITTER_SDK_VERSION` with consistent wrapper invocation.
+- `postinstall` now enforces executable bits (`+x`) for hook shell scripts on non-Windows systems.
+- `npm run test:long-scenario` now uses the cross-platform Node runner.
+
+## [0.1.3] - 2026-03-06
+
+### Added
+- SDK capability detection with explicit compatibility reporting (`full`, `compat-core`, `unsupported`).
+- Deterministic per-run trace logging at `<runDir>/run-trace.jsonl`.
+- Trace events across run lifecycle (run/iteration/task requested, executed, posted, failed, completed).
+- Windows and Linux installation guides with platform-specific commands.
+- Full long-session scenario runner (`test/full-session-long-run.ps1`) that enforces:
+  - at least 3 interview breakpoints
+  - at least 1 breakpoint with 4 questions
+  - user-choice application checks in generated artifact
+  - simulated 60-minute workload
+  - strict `score == 100` pass gate
+- Full scenario runbook and helper scripts:
+  - `test/FULL_SESSION_SCENARIO.md`
+  - npm scripts: `test:scenario`, `test:long-scenario`
+
+### Changed
+- Orchestrator startup now fails fast when required core SDK commands are missing.
+- Health diagnostics now include compatibility-aware missing core/advanced command reporting.
+- README now clarifies Babysitter is external to Codex and explains real activation prompts per mode.
+- Requirements documentation now clarifies SDK dependency is installed by `babysitter-codex` (non-circular install guidance).
+
+## [0.1.2] - 2026-03-05
+
+### Added
+- Codex CLI skill package with one-step global install flow.
+- 11 orchestration modes and hook-based integration.
+
+### Notes
+- Baseline for subsequent Codex compatibility and documentation improvements listed under `Unreleased`.
+
+## [0.1.1] - 2026-03-04
+
+### Added
+- Packaging and installation stability fixes for Codex skill discovery.
+
+## [0.1.0] - 2026-03-03
+
+### Added
+- Initial `babysitter-codex` release with Codex skill integration baseline.

package/README.md

@@ -0,0 +1,146 @@
+# @a5c-ai/babysitter-codex
+
+Babysitter integration package for OpenAI Codex CLI. It packages Codex-facing
+skills, install helpers, mapping docs, and the hook assets used to keep
+Babysitter in the Codex lifecycle loop.
+
+This is a Codex skill bundle plus workspace hook templates. It is not a
+Claude-style manifest plugin, but it does rely on Codex's real lifecycle hook
+engine through `.codex/hooks.json`, and the package postinstall now wires the
+active workspace when the global install is launched from that workspace.
+
+## What This Package Owns
+
+- Codex skill payload under `~/.codex/skills/babysitter-codex`
+- Codex-facing command docs
+- Codex runtime hook helpers under `.codex/`
+- Codex mapping and compatibility policy for SDK-driven orchestration
+
+## Active Process-Library Model
+
+`babysitter-codex` does not ship the process library. Workspace onboarding
+fetches the original Babysitter repo through the SDK CLI and binds the active
+process root in `.a5c/active/process-library.json`.
+
+Active-use process discovery should prefer:
+
+1. Project-local `.a5c/processes`
+2. The SDK-managed active process-library binding returned by
+   `babysitter process-library:active --state-dir .a5c --json`
+
+`project-install` and `team-install` layer config, rules, profiles, and pinned
+content metadata. They should not be documented as creating an exclusive
+project/team process-library scope.
+
+## Codex User Experience
+
+Codex should be integrated through its real hook engine:
+
+- `SessionStart` initializes Babysitter session state
+- `UserPromptSubmit` handles prompt-time transformations safely
+- `Stop` keeps Babysitter in the orchestration loop after each yielded turn
+
+Current contract:
+
+- start, resume, and inspect work through Codex command phrases such as
+  `babysitter call`, `babysitter resume`, and `babysitter doctor`
+- let the installed Codex hook assets handle runtime state, result posting,
+  and continuation
+- stop after each completed phase so the `Stop` hook can decide whether Codex
+  exits or receives the next Babysitter iteration message
+- finish only when `completionProof` is emitted and echoed as
+  `<promise>...</promise>`
+
+Do not document external supervisors, hidden wrapper loops, or `notify` as the
+continuation mechanism for the plugin path.
+
+## Installation
+
+Install from npm:
+
+```bash
+npm install -g @a5c-ai/babysitter-codex
+```
+
+If you run that command from inside the target repository, postinstall will:
+
+- install the skill payload into `CODEX_HOME`
+- merge `~/.codex/config.toml` so `codex_hooks` is enabled
+- materialize workspace `.codex/hooks.json` and `.codex/config.toml` for the
+  active workspace
+- clone or update the original Babysitter repo into `.a5c/process-library/...`
+- bind `.a5c/process-library/.../library` for active use through the SDK CLI
+
+If you installed from somewhere else, run:
+
+```bash
+npm install -g @a5c-ai/babysitter-sdk
+babysitter harness:install-plugin codex --workspace /path/to/repo
+```
+
+`babysitter harness:install-plugin ...` is provided by the SDK CLI, so make
+sure `@a5c-ai/babysitter-sdk` is installed first.
+
+Or from a local checkout:
+
+```bash
+cd /path/to/babysitter-codex
+npm install -g .
+```
+
+Verify the installed skill payload:
+
+```bash
+npm ls -g @a5c-ai/babysitter-codex --depth=0
+ls -1 ~/.codex/skills/babysitter-codex
+test -f ~/.codex/skills/babysitter-codex/scripts/team-install.js
+test -f ~/.codex/skills/babysitter-codex/.codex/hooks.json
+test -f ~/.codex/skills/babysitter-codex/.codex/hooks/babysitter-stop-hook.sh
+```
+
+Verify the active process-library binding:
+
+```bash
+babysitter process-library:active --state-dir /path/to/repo/.a5c --json
+```
+
+Manual bootstrap uses the same SDK CLI flow:
+
+```bash
+babysitter process-library:clone --repo https://github.com/a5c-ai/babysitter.git --dir .a5c/process-library/babysitter-repo
+babysitter process-library:use --dir .a5c/process-library/babysitter-repo/library --state-dir .a5c
+babysitter process-library:active --state-dir .a5c --json
+```
+
+## Quick Start
+
+Use command phrases in Codex chat:
+
+```text
+babysitter help
+babysitter call implement authentication with tests
+babysitter yolo fix lint and failing tests
+babysitter resume latest incomplete run
+babysitter doctor current run
+```
+
+For Codex users, the expected interface is the Codex command phrases plus the
+workspace hook install created by onboarding. Raw Babysitter CLI primitives are
+internal harness details and live in the Codex skill, not in this user-facing
+README.
+
+## Project And Team Install
+
+Use `babysitter team-install` and `babysitter project-install` from Codex chat
+when you want workspace onboarding. They layer pinned config and setup around
+the active process roots already used at runtime; they are not the source of
+truth for process discovery.
+
+## Documentation
+
+- [commands/README.md](./commands/README.md)
+- Internal orchestration details: [.codex/skills/babysitter/call/SKILL.md](./.codex/skills/babysitter/call/SKILL.md)
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: babysitter-codex
+description: >-
+  Run babysitter workflows from Codex using real Codex surfaces: skills,
+  AGENTS.md guidance, project config, lifecycle hooks, and the Babysitter SDK
+  runtime loop.
+  Use when the user wants to babysit a task, resume a run, diagnose run health,
+  install the Codex skill, or assimilate a methodology for Codex.
+---
+
+# Babysitter for Codex CLI
+
+Babysitter on Codex is implemented as:
+
+- Codex-facing instructions and skills
+- A workspace `.codex/hooks.json` with `SessionStart`, `UserPromptSubmit`, and
+  `Stop` registrations
+- A `.a5c` state directory in the target workspace
+- The Babysitter SDK run/task loop that owns `run:create`, `run:iterate`,
+  `task:post`, breakpoint handling, and resume behavior
+- Optional `notify` monitoring only as secondary telemetry
+
+Codex does expose real lifecycle hooks for this package on supported
+installations. Do not replace them with an external orchestrator or claim that
+`notify` owns continuation.
+Codex also does not expose a native installable plugin manifest for this
+package. Treat `.codex/command-catalog.json` as Babysitter compatibility
+metadata for the skill bundle, not as a Codex platform feature.
+
+## Choosing a Mode
+
+Read the matching sub-skill from `.codex/skills/babysitter/<mode>/SKILL.md`.
+If the user intent is unclear, default to `call/SKILL.md`.
+
+| User intent | Mode |
+|-------------|------|
+| Start an orchestration run | `call` |
+| Run autonomously | `yolo` |
+| Resume an existing run | `resume` |
+| Plan without executing | `plan` |
+| Diagnose run health | `doctor` |
+| Help and documentation | `help` |
+| Install into a project | `project-install` |
+| Install user profile/setup | `user-install` |
+| Install team-pinned setup | `team-install` |
+| Assimilate external methodology | `assimilate` |
+
+## Internal Runtime Contract
+
+Use the babysitter SDK CLI for orchestration:
+
+```bash
+babysitter run:create   --process-id <id> --entry <path>#<export> ...
+babysitter run:iterate  <runDir> --json --iteration <n>
+babysitter run:status   <runDir> --json
+babysitter task:list    <runDir> --pending --json
+babysitter task:post    <runDir> <effectId> --status ok --value <file> --json
+```
+
+When a Codex session ID is available, bind it honestly:
+
+```bash
+babysitter run:create ... --harness codex --session-id <id> --state-dir .a5c --json
+```
+
+## Result Posting Protocol
+
+1. Write the result value to `tasks/<effectId>/output.json`
+2. Post it with `babysitter task:post`
+3. Never write `result.json` directly
+
+## Codex Hook Loop
+
+The workspace onboarding flow should install `.codex/config.toml` and
+`.codex/hooks.json` so:
+
+1. `SessionStart` seeds `.a5c` session state
+2. `UserPromptSubmit` performs prompt-time transformations when needed
+3. `Stop` decides whether the run is complete or Codex should receive the next
+   Babysitter iteration context
+
+## Codex-Specific Rules
+
+- Prefer natural-language activation such as `babysitter call ...`
+- Legacy `/babysitter:*` aliases may exist only as optional user-installed
+  prompt sugar; they are not a native Codex plugin feature
+- Never fabricate a session ID when none is available from Codex or the caller
+- Use `notify` only for monitoring and telemetry, never as the orchestration
+  control loop

package/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Babysitter"
+  short_description: "Orchestrate multi-step AI workflows with quality convergence"
+  default_prompt: "Use $babysitter-codex to orchestrate this task"

package/babysitter.lock.json

@@ -0,0 +1,18 @@
+{
+  "version": 1,
+  "generatedAt": "2026-03-11T00:00:00.000Z",
+  "runtime": {
+    "name": "@a5c/babysitter-codex-runtime",
+    "version": "0.1.4"
+  },
+  "content": {
+    "name": "@a5c/babysitter-codex-content",
+    "version": "0.1.4",
+    "processLibrary": {
+      "repo": "https://github.com/a5c-ai/babysitter.git",
+      "processSubpath": "library",
+      "referenceSubpath": "library/reference",
+      "snapshotCommit": "unknown"
+    }
+  }
+}