# Architecture ## Objective Zimster separates durable development discipline from orchestration volume. A capable root model retains architecture and implements a coherent feature; additional contexts are spent only where isolation or independent judgment provides value. ## Layers ### 1. Harness-neutral skills The twelve skills under `skills/` define workflow selection, design/planning, persistent-owner execution, TDD, systematic debugging, bounded parallelism, risk-adaptive review, Git isolation, review handling, and completion proof. Core skills avoid hard-coded user paths and OS-specific shell assumptions. ### 2. Harness adapters - **Codex:** the repository marketplace at `.agents/plugins/marketplace.json` points to `plugins/zimster/`. That directory is a self-contained generated plugin with accepted manifest fields, skills, operational scripts, config, schemas, templates, assets, and notices. Claude hooks are not inside it. - **Claude Code:** `.claude-plugin/`, `skills/`, `agents/`, and `hooks/` expose native skills, bounded roles, and a compact `using-zimster` bootstrap. - **Cursor:** `.cursor/commands/using-zimster.md` points to Agent Skills copied into `.agents/skills/`; no unsupported repository manifest or lifecycle hook is invented. - **Kimi Code:** `.kimi-plugin/plugin.json` declares native skills and exactly one `sessionStart.skill` using documented fields. - **OpenCode:** the dependency-free project plugin registers the packaged skill path and inserts one marked bootstrap; missing package content fails actionably. - **Pi:** the `package.json` `pi` declaration loads the TypeScript extension and native skills; the extension has the same one-bootstrap and package-integrity invariants. ### 3. Operational control plane Dependency-free Node 22 tools turn important policy into inspectable state: - `init-run.mjs` creates durable execution state; - `project-commands.mjs` inventories canonical project commands; - `change-snapshot.mjs` represents committed, staged, unstaged, and untracked changes without touching the index; - `evidence.mjs` records local proof receipts and validity fingerprints; - `run-budget.mjs` enforces execution limits and proof-backed overrides; - `phase-checkpoint.mjs` separates persistent logical ownership from bounded physical contexts; - `verify.mjs` runs profile-selected gates with full Git-local logs and one compact receipt; - `installed-package-smoke.mjs` exercises exact candidate archives in isolated homes before review packaging; - `review-package.mjs` represents immutable canonical changes and mirror hashes without duplicating generated content, plus binding requirement IDs, matrix state, intended claims, evidence scope, unavailable proof, and lenses; - `semantic-assurance.mjs` validates the requirement-to-evidence matrix and deterministically gates candidate completion; - `capability-cache.mjs` decides whether one host contract needs refreshed research; - `run-postmortem.mjs` aggregates run-scoped observed/inferred/unavailable execution metrics; - `dispatch-record.mjs` records requested/effective model routing; - `delegation-record.mjs` records the delegation decision before routing; - `model-routing.mjs` creates proposals and resolves mappings and fallbacks; - `adapter-config.mjs` emits owned host overrides only for enforcing routing modes and only to an explicit output; advisory `recommend` remains inherited; - `convergence.mjs` records bounded continue/escalate decisions; - `sync-codex-plugin.mjs` generates the Codex plugin mirror; - `validate-codex.mjs` checks the pinned official contract snapshot; - `validate-claude-plugin.mjs` checks the current documented Claude manifest, hook, and plugin-agent contract when the host CLI is unavailable; - `validate-adapters.mjs` rejects obsolete Cursor surfaces and validates the Kimi, OpenCode, and Pi package contracts; - `check-version.mjs` and `bump-version.mjs` synchronize release metadata; - `package.mjs` creates deterministic archives only from a current mirror and synchronized version set. No run receipt or model record is uploaded. Normal runtime artifacts live under the worktree-safe Git administrative path returned by `git rev-parse --git-path zimster`, outside product history. ## Codex source and package flow ```text canonical root files → npm run sync:codex → plugins/zimster/ → pinned Codex contract validation → .agents/plugins/marketplace.json local reference → deterministic Codex marketplace ZIP ``` `sync:codex:check` compares every generated file digest and rejects missing, changed, or extra files. Packaging refuses a stale mirror. ## Execution state Create the Git-local `zimster/run.md` when there is more than one slice, any subagent or independent review, pending external/hardware proof, more than one commit boundary, compaction risk, or a resumed session. It stores mission, profile/rationale, Git disposition, architecture, current slice, evidence IDs, dispatch IDs, open findings, unavailable proof, budget, and next action. Detailed logs, diffs, and transcripts remain separate artifacts. Projects may opt into a project-defined audit documentation path; normal operation never turns approval or run bookkeeping into a standalone commit. The logical implementation owner persists across physical contexts. A compact checkpoint at a coherent slice boundary carries only the next dependency cone, valid receipt references, and budget position; it never embeds the full objective, passing logs, historical diffs, or transcript. ## Git state and review representation A review cannot rely on `git diff` alone. The change snapshot includes: ```text base..HEAD committed range (when supplied) git diff --cached git diff git status --short full text or hash/metadata for every untracked file ``` This supports both committed feature branches and explicit no-commit work. The snapshot does not mutate the index. ## Evidence model An evidence receipt includes: - command, cwd, kind, and scope; - Git head/tree and complete working-tree fingerprint; - environment fingerprint; - start/end time and exit code; - test-discovery classification and exact counts; - dependency cone, inputs, source, and notes; - supported requirement IDs, established/excluded claims, and environment or harness scope; - whether it was a final gate. Focused evidence may be reused only on the same fingerprint. Documentation-only changes rerun only affected provenance/packaging proof until the final gate is due. Final gates are always fresh. Duplicate evidence is surfaced instead of silently rerun. ## Semantic assurance model Binding obligations receive stable IDs in a machine-readable requirement set. The corresponding matrix names authoritative text/source, implementation locations, evidence references, candidate tree and environment scope, unavailable proof, status, and intended acceptance claims. Validation rejects missing IDs, stale/invalidated/wrong-tree proof, dirty candidate evidence, environment mismatch, and claims broader than their evidence. Semantic review records distinguish `self_review` from `independent_review`. Owner-inline work is always self-review. A review package binds the immutable base/head, complete canonical snapshot, relevant unchanged interfaces, matrix, evidence state, claims, unavailable proof, and selected lenses. Review attempts to falsify those claims. Approval binds a stable semantic-contract digest over binding text, intended claims, implementation locations, and evidence scope. Mutable receipt references, statuses, observations, and verification results remain separately validated so final proof can advance without invalidating an unchanged reviewed contract. Host evidence is independent per harness. Receipt states distinguish live, installed-package, structural, authentication-blocked, unavailable, and unsupported evidence, and separately record whether model-backed execution occurred. Public-beta completion requires one exact-package live host and claim-bounded records for all public harnesses; stable may require stronger coverage. Missing optional public-beta hosts narrow claims instead of becoming fabricated passes or a universal completion failure. Checkout integrity is orthogonal: `REVIEW_CHECKOUT_UNCHANGED`, `REVIEW_CHECKOUT_CHANGED`, and `REVIEW_CHECKOUT_UNVERIFIED` describe only the review checkout. Eligible Micro work may complete owner-only. Standard and High-risk completion requires clean-context independent approval for the exact head; High risk also requires load-bearing obligations and final integration approval. Micro and load-bearing proof references must support the exact named requirement ID and established claim. Missing review/proof yields an honest partial or blocked state, never `CANDIDATE_COMPLETE`. ## Delegation and model-routing model Delegation selection is independent and precedes model evaluation. A false decision cannot create a proposal or dispatch. Selected decisions bind role, reason, inline alternative, ownership, tools, dependency cone, stop condition, and owner acceptance proof. Plans may carry advisory proposals; dispatch regenerates authoritative, single-use proposals from current inputs. Harness-neutral classes are `economy`, `balanced`, `expert`, and `inherit`; legacy `fast` and `standard` remain read aliases. Concrete model names exist only in optional configuration. Resolution records provenance, capability evidence, fallbacks, and requested versus effective values. Local outcome summaries never mutate policy. ## Autonomous convergence Deterministic in-scope corrections continue without repeated authorization within configurable budgets. Contradiction, material expansion, sensitive authority gaps, missing review, required approval, and exhaustion are the only escalation reasons. Self-hosting freezes accepted policy until candidate rules are independently accepted. ## Agent topology and safety ```text persistent implementation owner ├── optional pure read-only scout ├── at most two isolated implementers for disjoint work ├── pure read-only seam/integration reviewer ├── tree-guarded test reviewer for one named command └── isolated diagnostician after repeated owner failure ``` Subagents do not spawn subagents. Pure reviewers have no Bash. Test-capable roles record before/after fingerprints and report any mutation rather than cleaning it. ## Review convergence ```text complete initial finding batch → owner fixes Critical/Important findings together → same reviewer performs one scoped resumed recheck → reserve final integration review until the exact candidate head is stable → require another exact-head review after any final-review correction → circuit breaker for load-bearing residuals ``` Residuals route to technical adjudication, design/requirement blocker, explicit deferral, diagnosis, or partial evidence instead of an unbounded reviewer lottery. ## Completion model Zimster separates code, integration, service, hardware, human acceptance, environment blockers, requirement blockers, and partial verification. The completion gate derives permitted claims only from valid matrix proof and emits `CANDIDATE_COMPLETE` only after profile-appropriate semantic review. The final report also states branch, commits, staged/unstaged/untracked files, and whether implementation remains uncommitted.