thehood 0.1.0-preview.0

package/docs/MEMORY_AND_RECONCILIATION.md

@@ -0,0 +1,222 @@
+# Memory And Reconciliation
+
+TheHood should make model chat context disposable. A provider window or API conversation can help with reasoning, but it must not be the durable memory for a project.
+
+## Core Principle
+
+```text
+TheHood remembers.
+Models are rehydrated from TheHood state.
+```
+
+The runtime preserves exact state first, then builds bounded context packets from that state when a model needs to reason.
+
+Summaries can be useful as previews, labels, or navigation aids. They are not canonical memory and must not replace source artifacts.
+
+## Memory Layers
+
+### Canonical Memory
+
+Canonical memory is the source of truth. It must be inspectable, durable, and grounded in exact artifacts.
+
+Examples:
+
+- run records
+- event logs
+- approval events
+- provider directives
+- provider responses
+- plans
+- diffs and commits
+- command logs
+- validation results
+- verifier verdicts
+- final reports
+- reconciliation outputs
+
+Canonical memory should be local-first and append-oriented. Existing filesystem run records and artifacts are the first implementation. A later SQLite store can index these records, but it should not replace the artifacts as the source of truth.
+
+### Index Memory
+
+Index memory exists to make canonical memory searchable and queryable.
+
+Examples:
+
+- SQLite tables
+- full-text search
+- embeddings
+- graph indexes
+- typed plan and task indexes
+
+Index memory can be rebuilt from canonical memory. If an index disagrees with a source artifact, the artifact wins.
+
+### Derived Memory
+
+Derived memory helps models retrieve relevant context efficiently.
+
+Examples:
+
+- retrieved excerpts
+- model-generated reflections
+- planner reconciliations
+- temporal graphs
+- vector memories
+- external memory engines such as Mem0, Zep, Letta, MemVid-style systems, or future adapters
+
+Derived memory must keep provenance:
+
+- source artifact refs
+- run id
+- created timestamp
+- commit or repo state when applicable
+- derivation method
+- supersedes or invalidates relationships when applicable
+
+Derived memory can accelerate reasoning, but it is not an authority boundary.
+
+## Ontology
+
+The runtime should preserve a stable project ontology so different models can share the same concepts even when provider sessions are reset.
+
+Initial entities:
+
+- `Run`
+- `Plan`
+- `Slice`
+- `Task`
+- `Agent`
+- `Role`
+- `Artifact`
+- `Evidence`
+- `Approval`
+- `Commit`
+- `Validation`
+- `VerifierVerdict`
+- `Reconciliation`
+- `Decision`
+
+Initial relationships:
+
+- `plan_created_by`
+- `task_implements_plan_item`
+- `artifact_derived_from`
+- `commit_satisfies_criteria`
+- `validation_checks_commit`
+- `verifier_reviews_evidence`
+- `reconciliation_supersedes_plan_state`
+- `decision_selects_next_slice`
+
+These names should be versioned with the runtime schema. Provider prompts should use these terms instead of inventing new labels per provider.
+
+## Rehydration Packets
+
+Before invoking an orchestrator, planner, verifier, critic, or memory-aware provider, TheHood should build a bounded context packet from canonical state.
+
+The packet should include exact refs and selected exact excerpts where possible:
+
+- current run id and parent or related run ids
+- repo path and current git HEAD
+- dirty state
+- original user goal
+- latest accepted plan state
+- selected plan items and acceptance criteria
+- relevant artifacts and refs
+- changed files and commits
+- command and validation evidence
+- verifier verdicts
+- open risks and unresolved questions
+
+The packet may include compact descriptions for navigation, but every important claim should point back to an artifact, command log, commit, or event.
+
+Provider directives should tell the model to ignore stale browser or conversation memory and reason only from TheHood-provided state.
+
+Current provider directives include a compact `canonicalMemory` object. This is not a memory engine. It is a bounded runtime-owned index with the current run snapshot, recent run summaries, and latest artifact refs for progress packets, reconciliation, local repo context, remote repo context, provider execution, final reports, review routing, and transfer manifests. It intentionally excludes large artifact bodies so browser/API providers can be rehydrated without making ChatGPT conversation history the source of truth.
+
+## Repo Context Retrieval
+
+Repo context retrieval should behave like an evidence-led repository inspection, not a one-shot dump.
+
+The default pattern is:
+
+```text
+repo map
+targeted reads
+follow-up evidence
+verification
+```
+
+The runtime should include a bounded tree, then prioritize files explicitly named by the user goal, provider decision, or source-of-truth instructions. Explicitly requested files may receive a larger per-file budget than generic files, but they still count against the total packet budget and must retain truncation metadata.
+
+Generic high-priority files such as `README.md`, `AGENTS.md`, architecture docs, runtime contracts, and key runtime modules should fill the remaining budget after requested files.
+
+Huge files should not silently consume the packet. When a source file is too large to include fully, the runtime preserves refs and excerpts, then allows a follow-up targeted context capture when the provider delegates concrete repo paths that were not already captured. For clean pushed GitHub repos used through ChatGPT Web, the runtime may preserve a refs-only remote context instead of local excerpts only when the active bridge GitHub connector surface is confirmed, then ask the provider to use its GitHub connector at the exact commit. Broad or duplicate follow-up delegations still stop rather than pretending the model has complete evidence.
+
+## Planner Reconciliation
+
+Planner reconciliation is the missing loop after implementation.
+
+```text
+planner creates plan
+runtime stores plan
+implementer builds selected slice
+runtime captures evidence
+verifier reviews evidence
+runtime sends approved progress packet back to planner
+planner reconciles plan against evidence
+runtime stores reconciliation
+```
+
+The planner should answer with small mechanical JSON fields plus markdown narrative in the role payload's `markdown` field:
+
+- which plan items are complete
+- which acceptance criteria are satisfied
+- which items remain open
+- whether implementation deviated from the plan
+- whether the next slice should change
+- whether user input is needed
+
+Reconciliation is advisory. The runtime remains responsible for approvals, tool execution, artifact storage, verification gates, and final state.
+
+The current runtime stores `progress` artifacts for completed runs and can reconcile them through the configured planner or orchestrator with `thehood reconcile` or `thehood_reconcile`. Browser and API providers require explicit approval before the progress packet is sent, and successful provider responses are stored as `reconciliation` artifacts. Future planning and reconciliation directives receive latest reconciliation refs through `canonicalMemory` when available.
+
+## Risks
+
+### Lossy Memory
+
+Risk: a summary omits critical details and a model reasons from an incomplete state.
+
+Guardrail: source artifacts remain canonical. Context packets include exact refs and excerpts instead of summary-only memory.
+
+### Stale Memory
+
+Risk: a model reconciles against an old plan, old commit, or old run state.
+
+Guardrail: packets include run ids, timestamps, git HEAD, dirty state, and supersession links.
+
+### Retrieval Poisoning
+
+Risk: a semantically related memory is contextually wrong, unsafe, or obsolete.
+
+Guardrail: retrieved memories must include provenance, source type, and validity metadata. High-impact actions still require runtime gates.
+
+### Provider Session Contamination
+
+Risk: old browser context influences a new answer.
+
+Guardrail: directives instruct browser-backed providers to ignore prior conversation and use only TheHood canonical state. ChatGPT Web bridge responses must echo the current directive acknowledgement before the runtime accepts schema-valid JSON.
+
+### Schema Drift
+
+Risk: provider outputs slowly change shape.
+
+Guardrail: all provider responses remain schema-bound and fail closed when invalid.
+
+## Build Direction
+
+The first implementation should avoid a large memory engine. Build the exact loop first:
+
+1. Add a progress packet builder from canonical run artifacts.
+2. Add planner reconciliation as a schema-bound provider call.
+3. Store reconciliation artifacts and expose them through CLI and MCP status.
+4. Add SQLite or another local index only after the artifact contract is stable.
+5. Make advanced memory engines pluggable after canonical and index layers are proven.

package/docs/NPM_PUBLISHING.md

@@ -0,0 +1,51 @@
+# NPM Publishing
+
+TheHood `v0.1.0-preview.0` should be published as a preview package only after the public repo, CI, and package boundary are reviewed.
+
+Do not publish from a local machine for the public preview. Do not add npm tokens to the repository or GitHub Actions secrets. Use npm Trusted Publishing / OIDC for the tag-based workflow.
+
+## Before Publishing
+
+1. Verify the npm package name is available or owned by the project maintainer.
+2. Configure npm Trusted Publisher for the GitHub repository `lemberalla/the-hood`.
+3. Confirm `.github/workflows/publish.yml` is the trusted workflow.
+4. Confirm the workflow has `id-token: write` and does not use an npm token.
+5. Run the release gate from a clean checkout:
+
+```bash
+npm ci
+npm run release:check
+```
+
+`npm run pack:check` uses a temporary npm cache by default so local cache ownership problems do not block package-boundary verification. If a specific cache path is required, set `THEHOOD_NPM_PACK_CACHE`:
+
+```bash
+THEHOOD_NPM_PACK_CACHE=/private/tmp/thehood-npm-cache npm run pack:check
+```
+
+## First Preview Publish
+
+Publish only from a version tag:
+
+```bash
+git tag v0.1.0-preview.0
+git push origin main --tags
+```
+
+The workflow publishes with:
+
+```bash
+npm publish --tag next
+```
+
+## Install Test
+
+After the workflow publishes, test from a clean shell or temp directory:
+
+```bash
+npm install -g thehood@next
+thehood --help
+thehood doctor --repo .
+```
+
+Promote to `latest` only after external installs and public docs are verified.

package/docs/OPEN_DECISIONS.md

@@ -0,0 +1,81 @@
+# Open Decisions
+
+These decisions should be resolved before or during the runtime skeleton phase.
+
+## License
+
+Recommended default: Apache-2.0.
+
+Alternatives:
+
+- MIT for simplicity
+- dual license only if there is a clear commercial strategy
+
+## Implementation Language
+
+Current direction:
+
+- TypeScript for runtime, CLI, schemas, provider adapters, and MCP
+- Swift only for the eventual macOS menubar companion
+
+## State Store
+
+Initial implementation:
+
+- local filesystem JSON run records under `.thehood/runs`
+
+Later option:
+
+- SQLite for querying run history and UI state
+
+## Memory Store
+
+Current direction:
+
+- exact run records and artifacts are canonical
+- summaries, embeddings, graphs, and provider reflections are derived memory
+- derived memory must preserve source refs and be rebuildable
+
+Open options:
+
+- SQLite plus full-text search for the first local index
+- vector index for semantic retrieval
+- graph index for ontology relationships
+- external or embedded memory engines after canonical artifacts and reconciliation are stable
+
+## Planner Reconciliation
+
+Current direction:
+
+- after implementation and verification, TheHood can send an approved progress packet back to the original planner or orchestrator
+- the provider returns a schema-bound reconciliation result
+- runtime stores the result as an artifact and uses it to inform the next slice
+
+Open question:
+
+- should reconciliation attach to the original plan run, create a child run, or both?
+
+## Remaining Provider Adapters
+
+Current status:
+
+1. Codex CLI adapter is implemented through the local command runner.
+2. Claude Code adapter is implemented through the local command runner.
+3. ChatGPT Web adapter is implemented as an experimental user-authenticated bridge.
+4. OpenAI API adapter remains future work.
+5. Anthropic API adapter remains future work.
+6. Local model adapter remains future work.
+
+## First Runtime Validation Strategy
+
+Start with project-discovered commands:
+
+- package scripts
+- language build files
+- CI files
+
+Avoid inventing validation commands when a repo already defines them.
+
+## macOS Menubar Timing
+
+Build after the CLI and local runtime can run a complete plan/implement/verify loop.