thehood 0.1.0-preview.0

package/docs/PROVIDER_ADAPTERS.md

@@ -0,0 +1,323 @@
+# Provider Adapters
+
+Provider adapters connect role contracts to concrete model or agent systems.
+
+Adapters translate TheHood's structured role requests into provider-specific calls, then normalize the result back into TheHood schemas.
+
+## Provider Access Modes
+
+TheHood tracks provider access modes so users can choose the transport that fits their workflow:
+
+| Mode | Owner of model call | Best for |
+| --- | --- | --- |
+| `agent-bridge` | TheHood | Codex-first loops, local CLI agents, ChatGPT Web/CDP bridge orchestration |
+| `api-agent` | TheHood | API models with structured tool calls and traceable runtime mediation |
+| `mcp-connector` | External MCP host | ChatGPT Developer Mode or another MCP client inspecting a local repo through TheHood |
+
+Access mode is not an authority boundary. The runtime still owns repo access, permissions, approvals, artifacts, patch integration, and verification gates.
+
+`chatgpt-web` supports both `agent-bridge` and `mcp-connector` paths. The agent bridge sends a runtime directive to the ChatGPT Web bridge. MCP connector mode lets ChatGPT call TheHood tools such as repo search, file read, run status, and artifact read through a connector or Secure MCP Tunnel.
+
+## Adapter Interface
+
+Each adapter should support:
+
+```ts
+interface ProviderAdapter {
+  id: string;
+  runAgent(request: AgentRequest): Promise<AgentResponse>;
+}
+```
+
+Current request shape:
+
+```yaml
+agent_request:
+  run: RunRecord
+  role: orchestrator | planner | researcher | implementer | qa | verifier | critic
+  assignment:
+    provider: string
+    model: string
+  context: object
+  directive:
+    objective: string
+    instructions:
+      - string
+    tool_permissions:
+      read: boolean
+      edit: boolean
+      shell: boolean
+      network: boolean
+    output_contract:
+      schema_version: 1
+      name: string
+      required_data_key: string
+    variables:
+      run: object
+      role: object
+      context: object
+```
+
+The runtime writes each directive as a `directive` artifact before provider execution. It validates each provider response against the role output contract before advancing the run state.
+
+`AgentResponse` JSON is the mechanical envelope for runtime control. Role payloads should keep small fields such as `action`, `reason`, `status`, `verdict`, refs, and `thehoodDirectiveAck` as JSON. Human-facing plans, reports, reviews, critique, rationale, acceptance criteria, and other long narrative content should be returned as GitHub-flavored Markdown in `data.<required_data_key>.markdown`. Adapters should avoid asking providers to express long plans as nested JSON arrays or objects.
+
+When the runtime supplies `context.criticTrigger` to a critic, the provider should treat it as the reason for an advisory review only. The adapter must not turn critic output into validation success, verifier approval, or edit authority.
+
+The product default is Codex-first: `codex-cli:default` for orchestration and implementation, and `codex-cli:spark` for QA, verification, and critique. Users can replace any role assignment, including orchestrator, with ChatGPT Web, Claude Code, API providers once implemented, or future CLI model aliases.
+
+Provider model policy is visible in `doctor` and `models` output:
+
+| Policy | Meaning |
+| --- | --- |
+| `listed` | The provider accepts only configured model names. |
+| `discovered` | The provider exposes a live model catalog and the runtime can mark unavailable aliases. |
+| `passthrough` | The provider accepts custom model names because the user's local CLI, bridge, connector, or API account owns model availability. |
+
+The `configured` model means "use the provider's configured or default selection" for local CLI providers. Explicit non-default names such as `sonnet`, `fable`, `mythos`, or a live Codex model slug remain role assignments and are passed to the provider when supported.
+
+## Local Command Runner
+
+The local command runner is shared by CLI-backed adapters.
+
+Rules:
+
+- It invokes commands without a shell.
+- It passes the runtime directive as stdin or prompt input.
+- It asks the provider to return the normalized `AgentResponse` JSON envelope.
+- It builds a role-specific JSON Schema for the expected `AgentResponse`.
+- It tells the provider to keep the JSON envelope mechanical and put long human-facing content in `data.<required_data_key>.markdown`.
+- It redacts obvious secrets from captured process output before parsing.
+- It fails closed with a schema-compatible blocked or failed response when output is unstructured.
+- It does not use dangerous bypass flags.
+- For read-only repo work, model-backed local command providers require an explicit provider-invocation approval before the first call.
+- It runs edit-capable local agents in an isolated git worktree by default and captures the resulting patch as a `diff` artifact.
+- It does not apply isolated patches itself; the runtime asks for approval and applies the patch deterministically during integration.
+- It requires a clean target checkout before isolated edit execution so uncommitted user work is not silently excluded.
+- It only runs edit-capable local agents in the target checkout when `THEHOOD_ALLOW_DIRECT_EDIT=1` is explicitly set.
+
+## Stub Adapter
+
+Purpose:
+
+- Exercise the runtime loop without external model calls.
+- Produce deterministic orchestrator, implementer, QA tester, critic, and verifier responses.
+- Keep smoke tests stable while the real provider adapters are still being built.
+
+Best roles:
+
+- orchestrator
+- implementer
+- qa
+- verifier
+- critic
+
+Rules:
+
+- It must not edit files.
+- It must use runtime evidence for verifier decisions.
+- It exists for testing the orchestration contract, not for real work.
+
+## ChatGPT Web Adapter
+
+Purpose:
+
+- Use the user's authenticated ChatGPT session for models only exposed in ChatGPT.
+- Support ChatGPT Pro as an orchestrator or planner.
+
+Current implementation:
+
+- Provider id: `chatgpt-web`
+- Default model: `chatgpt-pro`
+- Model policy: `passthrough`
+- Requires `THEHOOD_CHATGPT_WEB_COMMAND`
+- `thehood doctor` checks command executability, explicit model confirmation, Chrome DevTools reachability, whether a ChatGPT tab is visible, and whether the page is authenticated with a ready composer.
+- Sends the runtime directive as stdin.
+- Passes `--model <model>` and `--schema <schema-path>` to the bridge command.
+- Expects stdout to contain the normalized `AgentResponse` JSON envelope.
+- Directs ChatGPT to place plans and reports in the role payload's `markdown` string instead of deep nested JSON.
+- Returns `blocked` when no bridge command is configured.
+
+Included bridge:
+
+- Binary: `thehood-chatgpt-web-bridge`
+- Source: `src/bridges/chatgptWebBridge.ts`
+- Uses Chrome DevTools Protocol against the TheHood-managed persistent browser profile by default.
+- Requires explicit model confirmation through `THEHOOD_CHATGPT_WEB_MODEL_CONFIRMED=1` or `--allow-unverified-model`.
+- Treats ChatGPT Web GitHub connector access as unconfirmed unless `THEHOOD_CHATGPT_WEB_GITHUB_CONNECTOR_CONFIRMED=1` is set after verifying the active bridge session can use that connector.
+- Fails fast with a blocked response when the visible ChatGPT page requires login.
+- Creates a dedicated ChatGPT target for the first bridge call in a TheHood run, stores that target by run id, and reuses it for later ChatGPT Web calls in the same run so context follow-ups do not spawn new chats after every Pro answer.
+- Verifies a fresh composer before the first prompt in a run-scoped target and keeps directive acknowledgement checks on every response so reused run tabs do not accept stale provider-session output.
+- For bridge calls without a run id, closes the created target after a successfully parsed response and keeps the target open on failed or timed-out ingestion so the visible answer can be inspected or recovered.
+- Set `THEHOOD_CHATGPT_WEB_KEEP_TARGET=1` or pass `--keep-target` to keep all created targets, including successful responses.
+- Set `THEHOOD_CHATGPT_WEB_RUN_SCOPED_TARGETS=0` or pass `--no-run-scoped-target` to restore one-target-per-call behavior.
+- Set `THEHOOD_CHATGPT_WEB_KEEP_TARGET_ON_FAILURE=0` or pass `--close-target-on-failure` to restore cleanup after failed ingestion.
+- Requires ChatGPT responses to echo the current directive acknowledgement in the role payload, so schema-valid answers from stale browser/project context fail closed.
+- Fails closed with a schema-compatible `blocked` or `failed` response when browser access, selectors, model confirmation, or response parsing fails.
+
+Rules:
+
+- Use the user's existing subscription and browser session.
+- Do not bypass access controls.
+- Do not extract cookies or tokens into logs.
+- Do not rely on hidden chain-of-thought.
+- Prefer structured visible outputs.
+- Fail closed when the requested model cannot be confirmed.
+- Fail closed when the authenticated ChatGPT page or composer cannot be verified.
+- Fail closed when a fresh composer cannot be verified or when the response does not acknowledge the current directive.
+- The bridge must not log cookies, local storage, tokens, or private browser profile data.
+- When the directive includes `context.remoteRepoContext`, use ChatGPT Web's GitHub connector for the named owner, repo, branch, and commit instead of asking TheHood to send local file excerpts. The runtime only selects this route after connector access has been confirmed for the active bridge path. If the connector cannot access the repo or commit, ask TheHood for bounded local repo context.
+
+Best roles:
+
+- orchestrator
+- planner
+- critic
+
+Risk:
+
+- Browser UI changes can break automation.
+- Output extraction can be brittle.
+- Terms and product behavior may change.
+
+## ChatGPT MCP Connector Mode
+
+Purpose:
+
+- Let ChatGPT Pro inspect a local repo through TheHood without pre-sending a repo context pack.
+- Use ChatGPT Developer Mode or Secure MCP Tunnel to connect ChatGPT to TheHood's MCP server.
+
+Current implementation:
+
+- Provider access mode: `mcp-connector`
+- Transport target: `thehood mcp`
+- Repo gateway tools:
+  - `thehood_repo_tree`
+  - `thehood_repo_search`
+  - `thehood_repo_read_file`
+  - `thehood_git_status`
+  - `thehood_git_diff`
+- Run gateway tools include existing status, artifact, approval, continue, and orchestration tools.
+
+Rules:
+
+- Treat ChatGPT as an MCP host, not as runtime authority.
+- Expose read-only repo tools first.
+- Keep edit and approval actions mediated by TheHood runtime gates.
+- Do not expose `.git`, `.thehood`, dependency/build output, or secret-looking paths through repo gateway tools.
+- Prefer Secure MCP Tunnel for private local repos so the MCP server does not need a public inbound endpoint.
+
+## OpenAI API Adapter
+
+Purpose:
+
+- Use API-accessible GPT models for structured workers.
+
+Best roles:
+
+- implementer
+- planner
+- researcher
+- verifier
+- critic
+
+Notes:
+
+- Current implementation status: provider config exists, but the adapter is not wired yet.
+- Model policy: `passthrough`, but unavailable until the adapter is implemented and enabled.
+- Default API key env name: `OPENAI_API_KEY`.
+- Prefer structured output features when available.
+- Keep raw provider responses out of public logs if they contain sensitive context.
+
+## Anthropic API Adapter
+
+Purpose:
+
+- Use Claude models as guest agents or primary role owners.
+
+Best roles:
+
+- critic
+- verifier
+- architect/planner
+- implementer when tool integration is available
+
+Notes:
+
+- Current implementation status: provider config exists, but the adapter is not wired yet.
+- Model policy: `passthrough`, but unavailable until the adapter is implemented and enabled.
+- Default API key env name: `ANTHROPIC_API_KEY`.
+- Claude can be especially useful as an independent reviewer because it brings a different model family into the loop.
+- It still must obey the same runtime permissions.
+
+## Codex CLI Adapter
+
+Purpose:
+
+- Use Codex as the default orchestrator, implementation, QA, verification, critique, or investigation worker.
+
+Best roles:
+
+- orchestrator
+- implementer
+- researcher
+- qa tester
+- verifier
+- reviewer
+
+Rules:
+
+- Scope tasks tightly.
+- Capture diffs and logs.
+- Do not let Codex self-verify its own changes.
+- QA tester output is advisory and cannot satisfy runtime validation proof.
+- Run through `codex exec` with TheHood's role directive.
+- Use `read-only` sandbox for non-editing roles.
+- Require explicit provider-invocation approval before read-only repo calls.
+- Pass the generated schema through `--output-schema`.
+- Write redacted stdout/stderr `log` artifacts and a bounded `provider_invocation` artifact after the local command exits so status can show the role, provider/model, command args, workspace mode, sandbox, exit code, timeout state, output refs, parse status, and isolated patch ref when present.
+- Do not pass dangerous sandbox bypass flags.
+- Built-in friendly assignments are `default`, `spark`, and `configured`, but the active Codex model catalog comes from `codex debug models`. The runtime stores only a sanitized catalog with model slugs, display names, visibility, and reasoning/speed metadata. Friendly assignments such as `spark` resolve against the live catalog before TheHood passes `--model` to Codex CLI; unsupported custom strings are reported by `doctor` before a run.
+- Model policy: `discovered`. `configured` uses the local Codex CLI default and is not passed as a literal model name.
+
+## Claude Code Adapter
+
+Purpose:
+
+- Use Claude Code as a guest implementation or review worker.
+
+Best roles:
+
+- implementer
+- critic
+- verifier
+
+Rules:
+
+- Same separation rules as any other implementer.
+- If Claude Code edits, another agent verifies.
+- Run through `claude --print` with TheHood's role directive.
+- Use plan/read tools for non-editing roles.
+- Require explicit provider-invocation approval before read-only repo calls.
+- Pass the generated schema through `--json-schema`.
+- Do not pass permission bypass flags.
+- Model policy: `passthrough`.
+- Built-in models are `default`, `configured`, `sonnet`, `opus`, `haiku`, `mythos`, and `fable`. `configured` uses the local Claude CLI default and is not passed as a literal model name. Explicit aliases such as `sonnet`, `fable`, or `mythos` are passed through to the user's local Claude CLI.
+
+## Local Model Adapter
+
+Purpose:
+
+- Support private or cheap local workers.
+
+Best roles:
+
+- formatting
+- simple refactors
+- search summarization
+- low-risk repetitive work
+
+Rules:
+
+- Keep tasks narrow.
+- Do not use local model output as authoritative verification unless backed by deterministic logs.

package/docs/PROVIDER_MATRIX.md

@@ -0,0 +1,21 @@
+# Provider Matrix
+
+TheHood is provider-neutral at the runtime boundary, but provider support is intentionally uneven in the public preview. This matrix describes what is wired today versus what is only represented in config for future adapters.
+
+| Provider | Status | Access Mode | Notes |
+| --- | --- | --- | --- |
+| `stub` | Implemented | local deterministic | Used by smoke tests and synthetic demos. Does not call external models. |
+| `codex-cli` | Implemented | local command agent | Runs the local Codex CLI through TheHood's directive and response contract. Codex model discovery depends on the local CLI. |
+| `claude-code` | Implemented | local command agent | Runs Claude Code through the same local command adapter boundary. Model aliases are pass-through to the user's installed tool. |
+| `chatgpt-web` | Experimental, user-configured | browser agent bridge | Uses a user-authenticated ChatGPT Web session through the bridge command. It must be explicitly configured and remains sensitive to ChatGPT UI/session behavior. |
+| ChatGPT MCP connector | Experimental, optional | external MCP host | ChatGPT may connect to TheHood through a trusted MCP host such as Secure MCP Tunnel when the user's workspace exposes custom connectors. This is not a launch blocker. |
+| `openai-api` | Planned, not wired | future API agent | API key names and provider config are represented, but no production OpenAI API adapter is implemented in this preview. |
+| `anthropic-api` | Planned, not wired | future API agent | API key names and provider config are represented, but no production Anthropic API adapter is implemented in this preview. |
+| local model | Planned, not wired | future local agent | Local model ownership is a product goal, not a current runtime adapter. |
+
+## Policy
+
+- Provider adapters normalize model behavior into TheHood schemas.
+- Provider adapters must not bypass runtime permissions, approval gates, transfer manifests, or verification.
+- Model aliases are user preference only. They do not bypass provider availability, local command readiness, or runtime review.
+- External browser/API provider transfers require manifest and approval policy before local repo context or memory leaves the machine.

package/docs/PUBLIC_REPO_READINESS.md

@@ -0,0 +1,49 @@
+# Public Repo Readiness
+
+This checklist tracks repo-side scaffolding and external GitHub settings required before a public `v0.1.0-preview.0` developer-preview launch. The repo can be built and smoked locally today, but public release still requires a final safety, packaging, and repository-settings pass.
+
+## Release Position
+
+The public preview should make one claim clearly: TheHood is a local runtime for governed software goal loops. It can plan, act, capture evidence, verify independently, revise, stop safely, and preserve artifacts.
+
+It should not claim cloud routines, hosted execution, API-provider automation, a full dashboard, or polished native app rendering.
+
+## Must Finish Before Public
+
+- Keep the root MIT `LICENSE` and `package.json` license metadata in sync.
+- Keep `CONTRIBUTING.md`, `SECURITY.md`, `PRIVACY.md`, and `CODE_OF_CONDUCT.md` present in the repository and package boundary.
+- Confirm private vulnerability reporting is enabled for `lemberalla/the-hood`.
+- Keep `.thehood/`, browser profile state, provider logs, local env files, package archives, and generated build output out of git.
+- Keep examples and fixtures synthetic. Do not publish real runtime artifacts or provider transcripts.
+- Verify a fresh clone path: `npm ci`, `npm run build`, `npm run smoke:mcp`, `npm run smoke:codex-config`, and `npm run smoke:runtime`.
+- Verify release packaging with `npm run release:check`.
+- Verify package contents with `npm run pack:check`.
+- Keep the synthetic stub demo runnable from `examples/stub-demo` and `docs/DEMO.md`.
+- Keep the static site in `site/` dependency-free, analytics-free, and aligned with README claims.
+- Make README claims match current behavior. Mark API adapters, hosted UI, and automatic Codex app rendering beyond explicit agent board artifact payloads as planned unless implemented.
+- Keep ChatGPT MCP connector mode documented as experimental and optional. It depends on external ChatGPT custom connector availability and is not a public-preview blocker.
+- Configure branch protection, required CI checks, secret scanning or push protection, private vulnerability reporting, and issue/PR templates on GitHub. These settings are external to the repository tree and must be verified before public launch.
+
+## Current Public Surface
+
+- Runtime roles, same-run summons, bounded fan-out, review lanes, crew lanes, and run artifacts are implemented as local runtime concepts.
+- Codex CLI and Claude Code adapters are implemented through local command providers.
+- ChatGPT Pro works through the user-authenticated ChatGPT Web bridge when configured by the user.
+- OpenAI and Anthropic API provider config exists, but external API adapters are not implemented yet.
+- Agents are visible through CLI, MCP, TUI, status, logs, artifact surfaces, structured agent board snapshots, and renderable dashboard payloads. The optional Codex plugin provides TheHood workflow guidance and MCP wiring, but automatic native Codex app rendering on every TheHood run is still a later integration layer.
+
+## Package Boundary
+
+`package.json` uses a `files` allowlist. `npm run pack:check` should include built `dist/`, README, package metadata, docs, and the synthetic demo only. It should not include `.thehood/`, `src/`, `node_modules/`, `.env`, browser state, provider logs, local config, site drafts, GitHub workflow internals, or generated archives.
+
+## Release Gate
+
+Before the first public release, run:
+
+```bash
+npm ci
+npm run release:check
+git --no-pager diff --check
+```
+
+Publishing must happen through npm Trusted Publishing from the tag-triggered workflow. Do not publish locally and do not add npm tokens to the repo.

package/docs/RESEARCH_NOTES.md

@@ -0,0 +1,92 @@
+# Research Notes
+
+These notes capture the agent-loop patterns TheHood is built from.
+
+## Primary Sources
+
+- [Anthropic: Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents)
+- [Anthropic: How We Built Our Multi-Agent Research System](https://www.anthropic.com/engineering/multi-agent-research-system)
+- [Claude Code: Subagents](https://code.claude.com/docs/en/sub-agents)
+- [Claude Code: Agent Teams](https://code.claude.com/docs/en/agent-teams)
+- [Claude Code: Dynamic Workflows](https://code.claude.com/docs/en/workflows)
+- [OpenAI: A Practical Guide To Building Agents](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)
+- [Google ADK: Agents](https://adk.dev/agents/)
+- [Google ADK: Evaluate](https://adk.dev/evaluate/)
+- [Microsoft AutoGen: Teams](https://microsoft.github.io/autogen/stable/user-guide/agentchat-user-guide/tutorial/teams.html)
+- [LangChain: Plan-And-Execute Agents](https://www.langchain.com/blog/planning-agents)
+
+## Extracted Patterns
+
+### Prompt Chaining
+
+Break work into sequential stages. Each stage produces structured output for the next stage.
+
+TheHood use:
+
+- inspect
+- plan
+- implement
+- verify
+- critique
+- integrate
+
+### Routing
+
+Route tasks to the right role, model, and permission set.
+
+TheHood use:
+
+- user-configurable role mapping
+- provider-neutral adapter layer
+- risk-based role selection
+
+### Parallelization
+
+Run independent subtasks in parallel where safe.
+
+TheHood use:
+
+- parallel researchers
+- parallel critics
+- parallel exploration workers
+
+Implementation changes should be serialized or isolated in separate worktrees.
+
+### Orchestrator-Workers
+
+A high-capability manager delegates scoped tasks to workers.
+
+TheHood use:
+
+- ChatGPT Pro, Claude Opus, or another selected model can orchestrate
+- workers receive narrow objectives and permissions
+- runtime stores and validates their outputs
+
+### Evaluator-Optimizer
+
+One agent proposes or changes output, another evaluates it, then the loop revises.
+
+TheHood use:
+
+- implementer changes code
+- runtime captures diff and logs
+- verifier reviews independently
+- orchestrator decides next step
+
+### Deterministic Runtime
+
+The runtime is responsible for state, tool execution, and evidence capture.
+
+TheHood use:
+
+- runtime executes commands
+- runtime captures logs
+- runtime enforces permissions
+- models do not self-authorize
+
+## Key Design Conclusion
+
+A model can be intelligent without being trusted as an authority over its own work.
+
+TheHood should use models for reasoning, critique, and generation. It should use local runtime code for permissions, state, evidence, and integration.
+

package/docs/ROADMAP.md

@@ -0,0 +1,94 @@
+# Roadmap
+
+The roadmap is documentation-first, runtime-second, UI-last.
+
+## Phase 0: Documentation And Contracts
+
+- Architecture docs
+- Role contracts
+- Prompt schemas
+- CLI spec
+- MCP spec
+- Provider adapter boundaries
+- Security rules
+- Verification rules
+- ADRs
+
+## Phase 1: Local Runtime Skeleton
+
+- Run store
+- State machine
+- Event log
+- Permission model
+- Command runner
+- Diff capture
+- Config loader
+- Typed schemas
+
+## Phase 2: CLI
+
+- `thehood init`
+- `thehood config`
+- `thehood roles`
+- `thehood run`
+- `thehood status`
+- `thehood logs`
+- `thehood approve`
+- `thehood continue`
+- `thehood abort`
+
+## Phase 3: MCP Server
+
+- `thehood mcp`
+- `thehood_plan`
+- `thehood_orchestrate`
+- `thehood_continue`
+- `thehood_status`
+- `thehood_abort`
+
+## Phase 4: Provider Adapters
+
+- Codex CLI adapter with live model discovery
+- Claude Code adapter with configured/custom model passthrough
+- ChatGPT Web adapter as experimental
+- OpenAI API adapter
+- Anthropic API adapter
+- Local model adapter
+
+## Phase 5: Worktree And Verification Gates
+
+- Worktree isolation
+- Protected path detection
+- Runtime validation commands
+- Separate verifier flow
+- Patch integration
+
+## Phase 6: Memory And Reconciliation
+
+- Canonical progress packet builder
+- Planner reconciliation provider call
+- Reconciliation artifacts
+- CLI and MCP reconciliation status
+- Local index for run memory queries
+- Pluggable derived memory engines
+
+## Phase 7: macOS Menubar Companion
+
+- Active run list
+- Approval prompts
+- Pause/resume
+- Open logs
+- Open diffs
+- Role switch trigger
+
+The menubar app should talk to the local runtime. It should not own orchestration logic.
+
+## Phase 8: Public Hardening
+
+- Example configs
+- Synthetic fixtures
+- Integration smoke tests
+- Security review
+- Contributor docs
+- License
+- Release workflow