Self-host: a self-adapter + fixture target so the template can iterate on itself

[robercano]

Context

The template is designed to drive a target project via the adapter (gates.json + CLAUDE.md). To improve the harness using the harness, the orchestrator repo must become its own target — the classic bootstrap / chicken-and-egg.

Two things make it tractable:

1. Worktree isolation already breaks the immediate cycle. Implementers edit candidate .claude/ files on a branch in a worktree, while the driving session keeps using the definitions it loaded at session start. The engine is never mutated mid-loop.
2. Self-hosting promotion. Harness vN drives the change that produces vN+1; you then restart the session to adopt vN+1 (like a compiler compiling its successor). Agent-definition / settings.json / hook changes only take effect on a fresh session — so they need a smoke test that launches a sub-session in the candidate worktree rather than trusting the running one.

Suggestion

Ship a self-adapter so the repo dogfoods itself:

• Its own gates.json over the harness artifacts:
  • lint: shellcheck .claude/scripts/*.sh + eslint/node --check on .claude/workflows/*.js + markdownlint on docs/;
  • build/typecheck: JSON-schema-validate gates.json, parse-check settings.json;
  • test: a smoke harness that runs feature-fanout.js against a tiny checked-in fixture target repo (under examples/) and asserts a scope→implement→review loop produces a green PR — validating the harness end-to-end without infinite regress (it operates on the fixture, not on itself).
• Optionally a pinned known-good engine copy (tag/submodule) used to launch the driving session, kept separate from the template being edited, so a broken candidate can't brick the driver mid-loop.

This both proves the template on a non-JS-product repo and gives every harness change a real gate.

Tracks the "can the orchestrator iterate on itself?" question — the bootstrap path for self-hosting.

[robercano]

🤖 Proposed implementation plan

Size: L (phased — ship the cheap static gates first, defer the live smoke harness) · The bootstrap/self-hosting change; propose doing it in two phases so we get value without solving the regress problem up front.

Goal

Let the repo dogfood itself: give the harness its own adapter so every change to .claude/**, docs/**, and the workflows is gated the same way product code would be — without infinite regress.

Why it's tractable (from the issue, confirmed against the repo)

• Worktree isolation breaks the cycle: implementers edit candidate .claude/ files on a branch in a worktree while the driving session keeps the definitions it loaded at start. Engine is never mutated mid-loop.
• Promotion model: harness vN drives the change producing vN+1; you restart the session to adopt it (agent/settings/hook changes only take effect on a fresh session).

Phase 1 — self-adapter with STATIC gates (recommended first, low risk)

A gates.json that treats the harness artifacts as the "code":

• lint: shellcheck .claude/scripts/*.sh + node --check .claude/workflows/*.js + markdownlint docs/ *.md
• build/typecheck: JSON-Schema-validate .claude/gates.json against a schema we add (.claude/gates.schema.json) + parse-check .claude/settings.json (node -e "require(...)") + jq empty
• test: (phase 1) run the above validators over the tree; no live agent run yet
• Wire it into the existing .github/workflows/gates.yml (Ship a CI workflow that runs gates.json gates on PRs (server-side gate enforcement) #8) so self-checks run server-side on PRs to this repo.

This alone gives every harness change a real gate and is cheap/deterministic.

Phase 2 — live smoke harness (the harder part; flag the open problem)

• Add a tiny checked-in fixture target repo under examples/fixture-target/ — its own gates.json, one trivial module, a seedable module:* issue.
• test (phase 2) runs feature-fanout.js against the fixture and asserts scope→implement→review produces a green PR — validating end-to-end on the fixture, not on itself (no regress).
• Open design problem to resolve before building this: a live fan-out needs real agents (API + tokens) and is non-deterministic — bad fit for CI test. Options: (a) a stub/recorded implementer that runs only the deterministic scaffolding (worktree create → gate.sh → bot-PR script) with a canned diff; (b) gate it behind a manual/workflow_dispatch job, not pull_request; (c) a --dry-run mode in feature-fanout.js. Recommend (a)+(b): deterministic stub in CI, full live run on demand.
• Depends on Per-worktree setup/teardown lifecycle hooks so isolated workers can run all gates #9 (fixture worktree must run its gates via worktree.setup).

Optional — pinned known-good engine

Keep a tagged/submodule "driver" copy separate from the template being edited, so a broken candidate can't brick the driver mid-loop. Propose as a follow-up, not blocking.

Files (phase 1)

• .claude/self/gates.json (or a documented SELF_ADAPTER=1 switch) + .claude/gates.schema.json
• .github/workflows/gates.yml — add a self-check job
• docs/USAGE.md / docs/ARCHITECTURE.md — document the self-host promotion model and the restart-to-adopt rule.

Acceptance (phase 1)

• shellcheck/node --check/markdownlint/schema-validate all run green on the current tree (fix any existing violations they surface).
• Self-check job visible on this repo's PRs.

Recommendation

Ship Phase 1 now (high value, deterministic, unblocks confident harness edits); open a follow-up issue for Phase 2 once #9 lands. Do you want me to split Phase 2 into its own issue?

[robercano-ghbot]

Closing as complete in substance — Phase 1 shipped and the bootstrap question is answered in production:

• Self-adapter: .claude/self/gates.json + .claude/self/checks.sh (real shellcheck/node/JSON gates over the harness artifacts) — PR feat(self): self-adapter to dogfood the template (issue #11, Phase 1) #23
• CI self-gates: self / build|lint|test run on every PR via gates.yml — PR feat(ci): run self-adapter gates on PRs (closes #25) #42
• Self-hosted loop: /pr-loop-self — PR feat(harness): /pr-loop-self — durable self-hosted PR loop (closes #24) #40

The repo has been dogfooding itself for weeks: harness changes are developed under its own sandbox, gated by its own self-gates, PR'd by the bot, and merged by merge-ready.sh (most recently #60–#62).

Phase 2 (fixture-target smoke harness for feature-fanout.js; pinned known-good engine) was never built — the fanout smoke test is being spun off into its own focused issue; the pinned engine has proven unnecessary in practice (the restart-to-adopt-vN+1 pattern works).