@b00dea/cockpit 0.0.0-bootstrap.0 → 0.1.0

package/docs/architecture.md

@@ -0,0 +1,136 @@
+# Architecture and design
+
+This page is for integrators and contributors who want the reasoning behind cockpit: the problem it
+solves, the design decisions that follow, and where in the source to extend it. The fields and
+commands themselves are in the generated [configuration reference](configuration-reference.md) and
+[CLI reference](cli-reference.md).
+
+## The problem cockpit solves
+
+Agent work across several repositories of one product fails in predictable, mechanical ways:
+
+1. **No shared environment.** Each agent sees one checkout. Nothing boots the product it is
+   changing, so "it works" means "it compiles".
+2. **File access is not instruction.** Granting an agent a sibling directory does not tell it
+   what that repository is, how it is tested, or which commands are safe there.
+3. **Guards do not carry across tools.** A hook written for one harness does nothing in another,
+   and each harness spells permissions differently.
+4. **Environments collide.** Two agents on one machine fight over ports, volumes and the right to
+   stop the stack.
+5. **Completion is self-reported.** The session that did the work also declares it done.
+
+There are three ways to respond. A planning tool describes the work and leaves the environment
+to you. A sandbox isolates the agent from your machine, and from the product. cockpit boots the
+product the agent is editing, from the checkouts it is editing, and gives every harness the same
+rules about it.
+
+## Design decisions
+
+### Two axes: mount and acquire
+
+A sibling declares how the stack uses it (`mount`) separately from how it reaches disk
+(`acquire`). Neither is derived from the other. Collapsing them produces a preflight that reports
+healthy while the stack mounts the wrong checkout, or none.
+
+### Configuration that parses does something
+
+Every schema field is consumed by code. A field that is accepted and then ignored reads as a
+control the next person relies on, so it is a defect. Where a harness offers no
+mechanism for a restriction, cockpit emits nothing and records the feature as `unavailable`
+rather than writing a setting that binds nothing.
+
+### Generated files are committed and drift-checked
+
+Generated surfaces and Compose files are written into your repository, committed, and compared
+byte for byte by `cockpit check`. This sits between vendoring (copies that silently go stale) and
+a hidden runtime dependency (nothing to review). You can read every line an agent will load, and
+CI fails when a line changes without the configuration changing.
+
+### TypeScript decides, shell runs the hooks
+
+Configuration, validation, codegen, drift and state live in the TypeScript CLI, and every child
+process goes through one executor. Guards and hooks stay in shell, because every harness invokes
+them directly on each tool call and they must behave identically under all of them with no
+interpreter start-up cost.
+
+### Leases, locks and destruction
+
+These rules came from failures on shared machines:
+
+- **Ports are leased, not derived.** Two checkouts of one product would compute the same port from
+  the same configuration. A lease records who holds each port family.
+- **Locks are directory creations.** Creating a directory either succeeds or fails atomically, and
+  a process that dies leaves the directory behind for inspection instead of a half-written file.
+- **Unknown is not dead.** A lock or holder whose liveness cannot be established is reported, not
+  stolen. Age alone never justifies removing it.
+- **Classification overrides intent.** Destructive commands act only on resources whose cockpit
+  labels and records match, so "just delete it" cannot be expressed. The question cockpit asks
+  is "can I account for everything I am about to destroy?", not "does this look dangerous?".
+
+### Why the evaluator is independent
+
+Self-assessment is overconfident: an agent that wrote the code also wrote the account of it. The
+evaluator is a separate subagent that reruns the declared verification commands, grades each
+acceptance criterion from that output, and may abstain when the output is not enough to decide. Abstention
+is a valid result; it is what turns a likely false pass into a visible gap.
+
+### Prior art
+
+Spec and workflow tools also generate files into repositories. cockpit adds three things they
+typically lack: a drift check against installed generated files, a `--dry-run` preview of every
+write, and CLI and configuration references generated from the source so they cannot go stale.
+
+## Non-goals
+
+- **Not a planner.** cockpit does not decide what work to do. Pair it with a spec or workflow tool.
+- **Not a sandbox.** It does not isolate an agent from your machine; see
+  [Safety and autonomy](safety-and-autonomy.md).
+- **No telemetry.** The only network request cockpit makes itself is `doctor` reading the latest
+  published version from the npm registry, skipped when `CI` or `NO_UPDATE_NOTIFIER` is set.
+- **Not a monorepo or build-system replacement.** It can manage one repository or several, but
+  delegates each repository's build and dependency graph to that repository's own tools.
+- **No per-test containers.** One stack per checkout, shared across the agent's work.
+
+## Processing path
+
+Configuration is declared and loaded, the environment is observed, policy code decides, the
+environment application orders the work, and the shared executor runs child processes.
+Postchecks verify results before command handlers print them. The
+[Cockpit evidence boundary](concepts.md#cockpit-evidence-boundary) applies at every step: a
+parsed declaration is not an observation, a dispatched command is not a successful postcheck,
+and a generated file does not show that its harness loaded it.
+
+## Surface overlays
+
+Use a [Cockpit surface overlay](concepts.md#cockpit-surface-overlay) for product-specific rules,
+subagents, skills and hooks. Overlay merging belongs to `packages/cockpit/src/surfaces/merge.ts`;
+rendering continues through the existing surface code, and publication stays within
+[Cockpit generated ownership](concepts.md#cockpit-generated-ownership).
+[Ownership and extension](harness-surfaces.md#ownership-and-extension) covers the `replaces` rule
+and the review procedure.
+
+## Guards
+
+Extend policy in `packages/cockpit/src/guards/evaluator.ts`, then adapt its decision through the
+per-harness adapters. Do not interpret guard policy in shell or rebuild it in a CLI
+handler. A harness mechanism that has not been probed beside a deliberately broken control stays
+`instructed` or `unavailable`; see [Capability states](harness-surfaces.md#capability-states).
+
+## Runtime behavior
+
+Add a public command to `packages/cockpit/src/command-table.ts`, bind it in
+`packages/cockpit/src/cli.ts`, and order environment work through the environment application
+(`packages/cockpit/src/environment/application/`). Every child process crosses
+`packages/cockpit/src/environment-exec/execute.ts`; health and lifecycle verdicts stay in their
+existing modules. Add a schema field only together with the code that consumes it.
+
+The runtime sequence and recovery rules are in [Environment](environment.md). A new diagnostic
+needs one actionable remedy in [Troubleshooting](troubleshooting.md).
+
+## Harnesses
+
+A custom harness declares one row for every feature, with the evidence described in
+[Custom harnesses](harness-surfaces.md#custom-harnesses). Probe the exact harness version beside
+a deliberately broken control before changing a capability claim. Repository tests verify
+cockpit's side of the contract; native loading and enforcement need their own check through
+`cockpit selftest`.

package/docs/capability-matrix.md

@@ -0,0 +1,50 @@
+# Capability matrix
+
+<!-- Generated by `npm run references`; edit its sources, not this file. -->
+
+<!-- Source manifest: 94a3b5d0068e28fa3dc3ce7751dd8e3dc2d35d7a5e067980a8b09ff479f3ea7a -->
+
+This generated page is for users checking what cockpit actually enforces in each agent tool. Each cell holds one of four states:
+
+- `enforced`: a dated run of the real tool, beside a deliberately broken control, showed it refusing the forbidden operation.
+- `instructed`: cockpit writes the guidance or setting, but nothing makes the agent follow it.
+- `generated`: cockpit writes the files, but nobody has checked that the tool even loads them.
+- `unavailable`: cockpit writes nothing for this cell.
+
+Only a dated run of the real tool changes a state; writing a file or passing cockpit's own tests never does.
+
+Written says whether `sync` writes the tool's files for a cockpit.toml that lists no tools: the tools whose guard firing is measured are the default `[surfaces] tools`, and any other tool is written only once listed (`npx --no cockpit tool add <tool> --config <your cockpit.toml>`).
+
+Guard firing is the generated hook refusing a protected operation. Instruction loading is the tool reading the guidance cockpit writes for it, including the guides of sibling repositories. Skills are the tool loading the skills cockpit renders: `cockpit-setup`, `cockpit-explain`, `cockpit-fix` and `cockpit-work`. The session-start check is the tool running `cockpit check` as a session starts and showing its drift report to the agent.
+
+| Tool | Written | Guard firing | Instruction loading | Skills | Session-start check |
+| --- | --- | --- | --- | --- | --- |
+| Claude Code (`claudecode`) | by default | enforced | instructed | instructed | instructed |
+| Codex (`codexcli`) | by default | enforced (needs a person) | instructed | instructed | instructed (needs a person) |
+| OpenCode (`opencode`) | by default | enforced | instructed | instructed | unavailable |
+| Cursor (`cursor`) | when listed | unavailable | generated | generated | unavailable |
+| Grok Build (`grokcli`) | when listed | unavailable | generated | generated | unavailable |
+
+## Measurements
+
+Each line gives the date and tool version of the run and what it showed.
+
+- Claude Code, guard firing (2026-11-01, version 2.1.316): with the exact push pre-allowed by permissions, the hook refused git push to a protected branch and the remote stayed empty while git status ran; the same checkout without the hook pushed.
+- Codex, guard firing (2026-11-01, version 0.165.0): only after a person trusts the hook: untrusted, Codex skipped it and git push ran; trusted (forced with --dangerously-bypass-hook-trust), it refused the push. Trust is per machine and cockpit doctor warns until it is given.
+- OpenCode, guard firing (2026-11-01, version 1.19.4): the plugin refused git push and a native read of a secrets file while an unprotected read stayed allowed; before read was routed through the guard, the same read returned the file.
+- Claude Code, instruction loading (2026-11-03, version 2.1.317): in a workspace Claude Code had not trusted, a sibling guide copied into the root AGENTS.md that CLAUDE.md imports loaded, with or without Claude Code's user option for reading AGENTS.md, while the undeclared sibling's guide and the decoy did not; nothing loaded through a committed CLAUDE.md @-import of a link to the guide or of its relative path, through permissions.additionalDirectories with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD in the settings env (ignored until a person trusts the workspace), or through --add-dir with that variable set.
+- Codex, instruction loading (2026-11-03, version 0.166.0): a sibling guide copied into the root AGENTS.md loaded while the undeclared sibling's guide and the decoy did not; nothing loaded through a line in AGENTS.md telling the agent to read a link to the guide, through --add-dir naming the sibling, or through project_doc_fallback_filenames naming the link, and Codex dropped the end of a project AGENTS.md past 32 KiB.
+- OpenCode, instruction loading (2026-11-03, version 1.19.5): a sibling guide copied into the root AGENTS.md loaded, as did a guide named through a link in the opencode.jsonc instructions list, while the undeclared sibling's guide and the decoy did not.
+- Claude Code, session-start check (2026-11-03, version 2.1.317): a SessionStart hook in .claude/settings.json ran under claude -p and the agent quoted its stdout back, while a hook under a misspelled event name never ran and Claude Code named it as ignored.
+- Codex, session-start check (2026-11-03, version 0.166.0): only after a person trusts the hook, as for the guard: a trusted SessionStart hook in .codex/hooks.json ran under codex exec and the agent quoted its stdout back, while a hook under a misspelled event name never ran.
+
+## Without a measurement
+
+- Guard firing in Cursor and Grok Build: no guard adapter is checked in, so cockpit generates no guard hook.
+- Instruction loading in Cursor: cockpit's instructions and the sibling guides it copies reach Cursor only through the root AGENTS.md, and .cursor/rules holds only rules overlays; no run of the tool beside a broken control has shown that it loads either.
+- Instruction loading in Grok Build: cockpit writes the files, but no run of the tool beside a broken control has shown that it loads them.
+- Skills in Claude Code (`.claude/skills`), Codex (`.agents/skills`) and OpenCode (`.opencode/skills`): a person has not yet reviewed whether the tool loads and triggers them as written.
+- Skills in Cursor (`.cursor/skills`) and Grok Build (`.grok/skills`): cockpit writes the files, but no run of the tool beside a broken control has shown that it loads them.
+- Session-start check in OpenCode: OpenCode 1.19.5 delivers session.created to a plugin, but no run has shown a plugin putting text in the agent's context, so cockpit generates no session-start check.
+- Session-start check in Cursor and Grok Build: cockpit generates no hook for this tool.
+- Browser native transports (the playwright MCP tools and the pinned Playwright CLI) in Claude Code, Codex and OpenCode: cockpit declares them and the browser skill says each still needs a person's paired call beside a broken control; no cockpit command runs or records that call, so the browser commands drive the browser through cockpit's own project client instead.