thehood 0.1.0-preview.0

package/docs/product/role-policy.md

@@ -0,0 +1,89 @@
+# Role Policy
+
+TheHood separates authority from judgment. Models can advise, plan, implement, or review according to their role. The runtime decides what is allowed.
+
+## Runtime Conductor
+
+The runtime is the mechanical conductor.
+
+It owns:
+
+- loop control
+- role assignment and role separation
+- stop conditions
+- permission checks
+- approval gates
+- evidence capture
+- artifact storage
+- schema validation
+- provider readiness checks
+- directive acknowledgement validation
+- integration and protected-path policy
+
+The runtime does not delegate these responsibilities to Pro, Codex, Claude, or any other provider.
+
+## Strategic Pro Conductor
+
+Pro is a premium strategic reviewer and planner. It can be the final strategic approver for product direction, architecture judgment, reconciliation, or high-reputation review.
+
+It owns:
+
+- ambiguous planning
+- product and architecture judgment
+- reconciliation across conflicting agent outputs
+- critique of a proposed direction
+- high-reputation narrative review
+- recommendations to continue, revise, delegate, verify, or abort
+
+It does not own:
+
+- file edits
+- shell execution
+- dependency installation
+- network permission decisions
+- approval bypasses
+- artifact authority
+- protected-path decisions
+- runtime loop termination outside the provider response contract
+
+## Claude Second Judge
+
+Claude is an independent model-family reviewer or preferred alternate worker. It is not positioned as a backup to GPT. It is the user's way to bring Claude into the Codex workflow when a second judgment, different reasoning style, or Claude-led implementation is useful.
+
+It owns, when assigned:
+
+- contrarian critique of Codex or Pro output
+- independent verifier review when Codex implemented the change
+- implementation when the user prefers Claude Code for the build lane
+- product, architecture, writing, or cautious reasoning review
+- high-assurance cross-checks before final strategic approval
+
+It does not own:
+
+- approval bypasses
+- final runtime authority
+- protected-path decisions
+- test acceptance without runtime evidence
+- verifier authority when it was also the implementer for the same task
+
+## Planner
+
+The planner creates small, reversible execution paths. It separates facts from assumptions, names risks, defines acceptance criteria, and requests bounded evidence only when needed.
+
+## Implementer
+
+The implementer executes the approved slice with minimal scope. It must not reinterpret product strategy unless the plan is impossible, unsafe, or contradicted by repository evidence.
+
+## QA Tester
+
+The QA tester is read-only advisory review. It finds missed cases and recommends deterministic validation, but it does not satisfy runtime validation gates.
+
+## Verifier
+
+The verifier checks runtime-captured evidence against acceptance criteria. It has no edit tools and cannot replace runtime command evidence.
+
+When Pro, Claude, Codex, or another provider is assigned as verifier, it is the reviewer for that slice. It still cannot bypass runtime enforcement.
+
+## Critic
+
+The critic challenges product, safety, architecture, and UX assumptions. Critic output can trigger revision, but it cannot approve integration or replace verification.

package/docs/product/runtime-invariants.md

@@ -0,0 +1,44 @@
+# Runtime Invariants
+
+Configuration changes how TheHood chooses providers and when it escalates. It does not change the trust boundary.
+
+## Configurable Policy
+
+Users and repos may configure:
+
+- default agent usage mode
+- role-to-provider assignments
+- model aliases and passthrough model names for supported providers
+- Claude second-judge, Claude builder, Pro-led, or high-assurance team presets
+- Pro and Claude escalation thresholds
+- automatic provider call budget, frequency, and context size
+- phases that can use Claude or Pro automatically
+- evidence redaction preferences
+- path sensitivity labels
+- external transfer policy within runtime limits
+- user-facing verbosity for model-use explanations
+- whether provider usage appears as a banner, timeline event, or compact audit entry
+
+## Non-Configurable Runtime Enforcement
+
+These are runtime invariants:
+
+- The runtime owns loop control.
+- The runtime owns approval enforcement.
+- The runtime validates provider responses and directive acknowledgements.
+- The runtime records artifacts, evidence refs, and provider invocation metadata.
+- The runtime enforces edit, shell, dependency, network, external-transfer, and protected-path gates.
+- The runtime rejects stale provider-session responses.
+- Models cannot grant themselves permissions.
+- Implementer and verifier authority remain separate.
+- Runtime-captured command evidence beats model summaries.
+- Provider choice cannot make a protected path unprotected.
+- Model preference cannot let an agent verify its own implementation.
+- Pro cannot bypass Codex or tenant host policy.
+- Connector mode is a safe handoff path, not a host-policy bypass.
+
+## Final Approval Boundary
+
+Pro can be configured as the final strategic approver for a product or architecture slice. Claude can be configured as the independent second judge or verifier before that final strategic approval. That means the selected model gives the last model-backed judgment for its assigned role.
+
+Final strategic approval is not final runtime authority. The runtime still decides whether required gates are satisfied and whether evidence is complete.

package/docs/release/v0.1.0-preview.0.md

@@ -0,0 +1,48 @@
+# v0.1.0-preview.0 Release Notes
+
+Status: planned developer preview. Do not publish this release until the final release audit passes.
+
+## Position
+
+TheHood `v0.1.0-preview.0` is a local runtime for governed software goal loops.
+
+It should be evaluated as a developer tool for local orchestration, approvals, evidence, role separation, provider routing, and verification. It is not a hosted agent service, cloud scheduler, or polished native app.
+
+## Included
+
+- CLI and stdio MCP surfaces over the same local runtime.
+- Codex-first role defaults with provider-neutral role mapping.
+- Local Codex CLI and Claude Code command adapters.
+- ChatGPT Web bridge support when a user configures their own authenticated bridge.
+- Experimental ChatGPT MCP connector guidance when the user's workspace exposes the required connector and tunnel flow.
+- Deterministic `stub` provider for local smoke tests and synthetic demos.
+- Bounded `goal`, `run`, `continue`, and `loop` workflows.
+- Runtime-owned approvals, evidence artifacts, transfer manifests, review routing, QA/verifier/critic lanes, revision packets, and final reports.
+- npm preview packaging metadata and tag-triggered Trusted Publishing workflow.
+- Public contributor rails: issue templates, PR template, CODEOWNERS, and contributor guide.
+
+## Not Included
+
+- Hosted execution.
+- Timer schedules or overnight automation.
+- Production OpenAI API or Anthropic API provider adapters.
+- A polished web dashboard or macOS app.
+- Automatic native Codex visual rendering beyond explicit artifact/dashboard payloads.
+- Public release of private run logs, browser state, local `.thehood/` directories, provider transcripts, or real customer artifacts.
+
+## Validation Gate
+
+The release audit should pass:
+
+```bash
+npm ci
+npm run release:check
+npm_config_cache=/private/tmp/thehood-npm-cache npm pack --dry-run --json
+git --no-pager diff --check
+```
+
+The release audit should also inspect package contents and GitHub repository settings before publishing.
+
+## Publish Boundary
+
+Publishing must happen through npm Trusted Publishing from the tag-triggered workflow. Do not publish locally, do not add npm tokens to the repo, and do not tag the release until README, docs, package contents, and CI evidence agree.

package/examples/stub-demo/README.md

@@ -0,0 +1,25 @@
+# Stub Demo
+
+This example is the public-preview demo path for TheHood.
+
+It runs a bounded goal loop against a temporary synthetic repository using only the deterministic `stub` provider. It does not call external models, browser providers, API providers, or connector tools.
+
+From the repository root:
+
+```bash
+npm run build
+DEMO_REPO="$(mktemp -d)"
+node dist/cli/main.js init --repo "$DEMO_REPO"
+node dist/cli/main.js approvals policy set mode autopilot --repo "$DEMO_REPO"
+cat > "$DEMO_REPO/package.json" <<'JSON'
+{
+  "scripts": {
+    "typecheck": "node -e \"process.stdout.write('demo validation ok\\n')\""
+  }
+}
+JSON
+node dist/cli/main.js goal "Synthetic demo: prove a governed local loop can complete" --repo "$DEMO_REPO" --orchestrator stub:orchestrator --implementer stub:implementer --qa stub:qa --verifier stub:verifier --critic stub:critic --max-iterations 5 --json
+node dist/cli/main.js status --repo "$DEMO_REPO"
+```
+
+See [docs/DEMO.md](../../docs/DEMO.md) for the demo boundary and expected evidence.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "thehood",
+  "version": "0.1.0-preview.0",
+  "description": "A local, provider-neutral runtime for governed software agent loops.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lemberalla/the-hood.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lemberalla/the-hood/issues"
+  },
+  "homepage": "https://github.com/lemberalla/the-hood#readme",
+  "bin": {
+    "thehood": "dist/cli/main.js",
+    "thehood-chatgpt-web-bridge": "dist/bridges/chatgptWebBridge.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "PRIVACY.md",
+    "docs",
+    "examples",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/prepare-bin.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run typecheck && npm run build && npm run smoke:mcp && npm run smoke:codex-config && npm run smoke:runtime",
+    "release:check": "npm test && npm run pack:check && git --no-pager diff --check",
+    "pack:check": "node scripts/verify-pack-manifest.mjs",
+    "smoke:codex-config": "node scripts/smoke-codex-config.mjs",
+    "smoke:mcp": "node scripts/smoke-mcp.mjs",
+    "smoke:runtime": "node scripts/smoke-runtime.mjs",
+    "clean": "rm -rf dist"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "agents",
+    "mcp",
+    "codex",
+    "orchestration",
+    "runtime"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.8.3"
+  }
+}