From f70aeac5a93b26d0ffb1ca6fee0525addcff44b4 Mon Sep 17 00:00:00 2001 From: ci Date: Thu, 27 Aug 2026 19:39:30 -0400 Subject: [PATCH 1/2] roadmap: make ystack portable across harnesses and forges --- AGENTS.md | 29 +++- NORTH_STAR.md | 81 +++++++----- README.md | 53 ++++---- REVIEW.md | 2 +- ROADMAP.md | 298 ++++++++++++++++++++++++++++++++++++++++++ ci/required-files.txt | 1 + work/README.md | 15 ++- 7 files changed, 410 insertions(+), 69 deletions(-) create mode 100644 ROADMAP.md diff --git a/AGENTS.md b/AGENTS.md index 149477d..aa2f282 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,14 +7,16 @@ target repo: agents here are improving the team itself. whatever vendor — Codex and most tools look for `AGENTS.md`, Claude Code reads `CLAUDE.md`, which imports this file. One file, no drift. -Companions: **`REVIEW.md`** is how work is reviewed here (passes, Important -vs nit, how disagreements end). **`work//`** holds the artifact chain — +Companions: **`ROADMAP.md`** records the portable architecture and rollout order. +**`REVIEW.md`** is how work is reviewed here (passes, Important vs nit, how +disagreements end). **`work//`** holds the artifact chain — `intent.md` → `spec.md` → `plan.md`. If you are implementing, your brief is that slug's plan; it is written so someone who never saw the conversation can build from it. Two goals drive the backlog: -1. **Reusable by anyone** — a clean, parameterized, well-documented product others can adopt. +1. **Reusable anywhere** — a clean, parameterized, well-documented product whose + core is not tied to an agent harness, model vendor, Git forge, or CI provider. 2. **Full backup** — everything needed to reconstruct the team if the live setup is lost. ## What lives here @@ -49,6 +51,11 @@ Two goals drive the backlog: ## PR rules (enforced by coder + reviewer) - **One concern per PR.** Soft size budget ~300–400 net lines; split if bigger. - Every PR links its issue (`Closes #`) and keeps README/docs in sync with any change. +- **Risk sets the plan gate.** High-risk work — constitution paths, workflows, + identity/auth, security controls, migrations, deployment/production infrastructure, + or broad architecture — requires the operator to accept `plan.md` before code. + Routine work may keep plan + code in one PR only after an independent plan check + records acceptance before the write phase. The author cannot accept its own plan. - **Plain language, always** (operator rule, 2026-08-26): every artifact (intent/spec/plan), PR title/description, and review comment is written for a tired human. Short sentences. Everyday words. No jargon where a plain word @@ -70,13 +77,16 @@ Two goals drive the backlog: user-directed issue is gated by the user's approval of the drafted spec (the one-liner is the request, not the go), a proactive issue by the passed yshifu⇄Codex manager-debate consensus (for *proactive* work the user's gate is at the north-star altitude; user-directed issues - still need the user's spec approval). + still need the user's spec approval). This intake rule does not waive the later high-risk + plan gate: proactive and user-directed high-risk work both return to the operator before code. ## v2 artifact chain (work/) - One initiative = one dir: `work//` holding `intent.md` → `spec.md` → `plan.md`. Each artifact lands via its own PR and the operator's merge IS the gate: G1 accepts - the intent, G2 approves the spec, G3 approves the implementation PR (which carries - `plan.md` + code + tests). Details: `work/README.md`; review policy: `REVIEW.md`. + the intent, G2 approves the spec, and G3 approves the implementation. High-risk work + records a separate operator acceptance of `plan.md` before code; routine work may carry + an independently accepted plan with code + tests in the implementation PR. Details: + `work/README.md`; review policy: `REVIEW.md`. - Skills: `/intent-draft`, `/spec-draft`, `/plan-draft` hold the templates and stage rules. - **Hash discipline:** `spec.md` frontmatter records `intent-blob` (`git hash-object` of the intent it was drafted from); `plan.md` records `spec-blob`. On mismatch with main's @@ -84,7 +94,7 @@ Two goals drive the backlog: - **Stage rules (autonomous lane):** the spec stage writes only `work//spec.md`; the implement stage never touches `intent.md`/`spec.md`; unattended agents never write the **constitution paths** — `.github/**`, `.claude/**`, `AGENTS.md` (this file), - `CLAUDE.md`, `REVIEW.md` — such changes land as patches under `proposals/` that the + `CLAUDE.md`, `REVIEW.md`, `ROADMAP.md` — such changes land as patches under `proposals/` that the operator applies. That is the same list `REVIEW.md` uses; the two must always match, so a change to one is a change to both. Operator-driven sessions are exempt; Phase 3 hooks enforce this mechanically via `YSTACK_STAGE`. @@ -94,6 +104,11 @@ Two goals drive the backlog: ## Reusability goal - No hardcoded personal values (usernames, repo names) in shipped templates — keep the reusable path parameterized. Personal config stays out of it. +- Core artifacts, policies, gates, state, and evals are harness-, model-, forge-, and + CI-neutral. Claude, Codex, GitHub, and other products belong in adapters or selected + profiles, never in core requirements. +- Safety is expressed as capabilities and separation of duties: author, verifier, + reviewer, and publisher boundaries must survive an adapter change. ## The rules that bite diff --git a/NORTH_STAR.md b/NORTH_STAR.md index 9f67aec..29306b1 100644 --- a/NORTH_STAR.md +++ b/NORTH_STAR.md @@ -37,33 +37,43 @@ user's approval of the spec yshifu drafts from their one-liner is its own gate.) ## Current north star -### B — "Pick up any project at any stage" · status: **active** · history: set + approved by the **operator** (2026-06-28). **Adopters:** this is ystack's goal, not yours — replace it with your own north star and explicitly approve *that* before proactive mode applies to your repo (and remove the `ystack-shipped-default` marker on this line when you do). This history line is **not** a token that auto-approves a clone. - -ystack can adopt a project wherever it is and drive it toward the operator's goal — whether -that project is an empty folder or an existing codebase with history. - -- **Two modes:** - - **Empty (0→1):** the operator's first command *becomes* the first north star; ystack - scaffolds the skeleton + a **real PR-CI gate (the operator confirms that initial gate)** - + a first commit + a **committed `.ystack/north-star.md`** (yshifu drafts the exact - north-star text + done-signal from the operator's command as part of the approved bootstrap - plan; the bootstrap coder commits THAT text into the target), then runs the loop. - - **Existing (1→N):** ystack **understands the whole project first** (structure, stack, - conventions, current state), then pursues the operator's north star. -- **Done-signal:** from BOTH starting points — (a) an empty folder/repo, and (b) an existing - repo with no prior ystack setup — a first `/yshifu` session drives one real change to a - **merged, CI-gated PR** toward the operator's stated goal, with the CI gate present - (**operator-approved when ystack bootstrapped it**) before any autonomous merge. On the - empty (0→1) path the bootstrap PR also lands a **committed `.ystack/north-star.md`** (active - non-placeholder entry, no `ystack-shipped-default` marker) so the 0→1 target ends with the - committed north star the shipped gate (`manager-review.sh`) requires — a `doctor.sh` - north-star WARN *before* that bootstrap PR lands is advisory in greenfield (like missing - PR CI), not a blocker. -- **Why it's the north star:** the team is only *"pick up my work"* useful if it meets a - project where it is, instead of requiring a pre-wired repo. -- **Safety note:** ystack's autonomy rests on CI + cross-vendor review; on an empty project - neither exists yet, so the gate is bootstrapped **early and operator-approved**, and the - human stays in the loop until a real gate exists. +### D — "Any harness, any Git forge, one governed loop" · status: **active** · history: set + approved by the **operator** (2026-08-27). **Adopters:** this is ystack's goal, not yours — replace it with your own north star and explicitly approve *that* before proactive mode applies to your repo (and remove the `ystack-shipped-default` marker on this line when you do). This history line is **not** a token that auto-approves a clone. + +ystack is a harness-neutral and forge-neutral control plane for an AI-native +software-delivery loop. It can meet a Git project at any stage, then run the same +versioned artifacts, risk gates, verification, review, and human authorization through +replaceable adapters. + +- **Portable core:** intent, spec, accepted plan, evidence, review, incident records, + state, policies, evals, and gates do not require Claude, Codex, GitHub, or another + named vendor. Git is the first canonical artifact protocol; GitHub, GitLab, and + Bitbucket are forge adapters. +- **Preference profiles:** the first profile may prefer Claude Code as producer, Codex + as reviewer, and GitHub Actions as CI. A profile selects these implementations; it + cannot weaken separation of duties, deterministic proof, human merge, or production + gates. +- **Any-stage adoption remains required:** greenfield bootstrap establishes a real, + operator-approved CI/merge gate before autonomous 1→N work. An existing project is + understood before change. Both paths commit the target's own approved north star. + ystack is its own first dogfood target, but an unrelated external target is required + to prove the core did not special-case itself. +- **Complete loop:** work moves through + `intent → spec → accepted plan → build → verify → independent review → human merge → + deploy/rollback → production feedback/new intent`. Events only wake the loop; durable + reconciliation reads canonical state and repairs missed work. +- **Done-signal:** the same canonical contracts and gates complete a real target change + under the default profile, while at least one alternative harness and one alternative + forge pass the adapter contract and smoke path. No core rule or artifact requires a + Claude, Codex, or GitHub-specific command, event, secret, model, or file layout. A real + target then completes the full loop through a rehearsed rollback or production signal + that creates a new intent and permanent eval. +- **Why it's the north star:** faster code generation is useful only when the whole system + stays portable, recoverable, measurable, and governed. The durable product is the + control plane and its contracts, not one vendor harness. +- **Safety note:** the operator remains the merge and production authority. High-risk work + receives plan approval before code. Model-controlled commands and candidate code cannot + read model, forge, or deployment credentials; inference and external writes cross a + brokered boundary. No adapter may downgrade the core gates. --- @@ -72,11 +82,16 @@ that project is an empty folder or an existing codebase with history. A short history of north stars and consensus-filtered proposals, so the human can see the trajectory and override anything consensus dropped. -- **B — "Pick up any project at any stage"** — *active; set + approved by the operator - (2026-06-28) (history, not an inheritable token).* Done-signal: from both an empty - folder/repo and an existing un-set-up repo, a first manager session reaches a merged, - CI-gated PR toward the operator's goal — gate present + operator-approved-if-bootstrapped - before any autonomous merge. +- **D — "Any harness, any Git forge, one governed loop"** — *active; set + approved by + the operator (2026-08-27) (history, not an inheritable token).* Done-signal: a portable + core runs the governed artifact-to-production-feedback loop under the default profile, + with alternative harness and forge adapters proving the same contracts and gates. +- **B — "Pick up any project at any stage"** — *superseded — folded into D.* Any-stage + greenfield and existing-project adoption remains a requirement of the portable loop. + B was substantially built but not independently proven on a real fresh clone, so it is + folded forward rather than marked achieved. Original done-signal: from both starting + points, a first manager session reaches a merged, CI-gated PR toward the operator's + goal, with an operator-approved gate established before autonomous work. - **A — "Frictionless first-run"** — *superseded — folded into B.* Frictionless adoption of an existing repo is a subset of any-stage adoption. Substantially built out via #54–#82, but **not** independently proven on a real fresh clone, so folded into B rather than marked @@ -84,7 +99,7 @@ trajectory and override anything consensus dropped. `QUICKSTART.md` walkthrough. - **C — "Numbers I can trust" (MapleFolio)** — *the team's **first real external run**; set + approved by the operator (2026-07-01, in an in-session manager chat); **achieved 2026-07-02**. Logged - here as a completed external run — this repo's own active star stays B.* Goal: MapleFolio's + here as a completed external run — this repo's own active star stays D.* Goal: MapleFolio's Canadian room/cash/FX calculation engine verified by an automated test suite run as the hard CI gate, so real-money contribution decisions rest on correct math. This run motivated the **per-target north-star architecture** (#97 resolver, #98/98a atomic flip, 98b adoption) — a diff --git a/README.md b/README.md index d17f81a..6d7ae2f 100644 --- a/README.md +++ b/README.md @@ -4,15 +4,19 @@ A small autonomous coding team. **yshifu** (the manager) runs the shop in a Clau session: you approve specs, and yshifu spawns a Claude coder subagent to build and runs a Codex reviewer to review. -This repo is the **control plane** — it defines *how the team works*. It is **not** -where the team writes code. The team works in separate **target repos**; this repo -holds the prompts, roles, and templates you edit to set up and evolve the team. +Claude Code + Codex + GitHub are the **current default profile**, not product +requirements. The portable target architecture and rollout live in +[`ROADMAP.md`](ROADMAP.md). + +This repo is the **control plane** — it defines *how the team works*. Target product +code normally lives in separate repos; ystack is intentionally its own target when +the team is improving the control plane itself. **ystack** — Yihan's stack for the AI-native SDLC: an autonomous coding team, gated by human judgment. -**Get started →** [QUICKSTART.md](QUICKSTART.md) +**Get started →** [QUICKSTART.md](QUICKSTART.md) · **Direction →** [ROADMAP.md](ROADMAP.md) -## The team +## The current default team You talk **only** to yshifu, in a Claude Code session. yshifu orchestrates the other roles within that session — spawning the coder and running the reviewer — so there is no @@ -66,12 +70,12 @@ exactly one coder launch per cleared issue, one review path, and one revision pa ## Design decisions (the "why") -- **4 roles, fixed** (2 vendors). Manager = the PM (no separate PM). Add an agent only for a - distinct *job + trigger + tool surface* — not per discipline (no FE/BE split; - specialize via each target repo's `CLAUDE.md`). -- **Cross-vendor by design.** Claude codes, Codex reviews — different training/ - architecture = decorrelated blind spots. A reviewer's value is being *different*, - not a second copy. +- **Responsibilities are stable; adapters are replaceable.** Add a role only for a + distinct *job + trigger + tool surface* — not per discipline. The current profile + maps those responsibilities to Claude and Codex. +- **Cross-vendor review is a preference, not a requirement.** The requirement is an + independent reviewer identity, context, and permission boundary. A different vendor + is the preferred default because it can reduce common blind spots. - **Reviewer is read-only, comments only, never the author.** Non-negotiable. - **Judgment lives at the direction (front gate at the north-star altitude), not the diff.** You approve the **north star** — each target repo's own committed @@ -92,7 +96,8 @@ exactly one coder launch per cleared issue, one review path, and one revision pa [`reviewer/manager-review.md`](reviewer/manager-review.md)). For *proactive* work you are pulled back in only at the north-star altitude: **north-star achieved**, **goal drift / transition**, and `needs-human` escalations — user-directed issues still come to you for the - drafted-spec approval. + drafted-spec approval. This intake autonomy does not waive the risk-tiered plan gate: + high-risk proactive or user-directed work returns to you for plan approval before code. - **CI is the hard gate** — ground truth. Autonomy rests on tests first, diverse reviewer second. - **yshifu never merges — it labels, then hands you the PR.** Merging is the operator's, @@ -128,17 +133,18 @@ exactly one coder launch per cleared issue, one review path, and one revision pa scoped-down core is contested, it's a genuine coder↔reviewer standoff, or it's a safety-rail / north-star decision — only then does the cap reach you. The cap **count** is unchanged; only how it resolves. -- **State lives in labels, not memory.** Each coder is a fresh subagent with no memory of - the last round, so rounds + escalation live in **labels** (`round-0..3`, `needs-human`) - that yshifu reads and bumps each round. +- **The current profile projects state into labels, not memory.** Each coder is a fresh + subagent, so `round-0..3`, `needs-human`, and `merge-ready` currently survive in forge + labels. The portable core moves canonical stage, retry, stale, and decision state into + durable records; labels remain a UI projection rather than a second state machine. - **Runs on the plan** in an ordinary Claude Code session (Claude coder subagents) plus Codex's built-in review via `scripts/codex-review.sh` — compliant ordinary use, metered. Prototype on personal repos; apply terms diligence before any work/shared repo. -> **Autonomous lane: being built.** The autonomous lane is being built through the v2 -> chain — committed intent → spec → plan artifacts, each gated by the operator's merge. -> Stack A (the artifact chain) is merged; the GitHub Actions workflows land next. Until -> they do, the in-session loop above is the one path that runs. +> **Autonomous write is paused for re-planning.** The artifact spine is useful, but draft +> PR #146 bound the lane to one harness/forge and exposed missing credential, eval, and +> reconciliation controls. It must not merge. The portable core and control foundation in +> [`ROADMAP.md`](ROADMAP.md) come before any autonomous write is enabled. ## Model policy @@ -222,6 +228,7 @@ merging the doc change — `doctor.sh`'s static validation is unaffected. ``` QUICKSTART.md The ~10-min golden path: stand the team up from scratch +ROADMAP.md Portable architecture, control objectives, and rollout order CLAUDE.md Repo conventions + self-modification safety rails (vs manager/CLAUDE.md = yshifu's persona) manager/CLAUDE.md yshifu's persistent role (paste into Claude Code) routines/coder.md Coder baseline instructions yshifu passes to a spawned coder subagent @@ -257,7 +264,7 @@ RESTORE.md Disaster-recovery runbook: rebuild the team from this drift. Both the **brief** and a **status / Tracking pass** are **read-only — they surface `merge-ready` PRs, they never merge**. No agent merges: `main` needs a pull request plus an approving review the comments-only reviewer cannot give, and no agent has a bypass. -- **Phase 3** — widen what the loop takes on as it proves out (the autonomous lane in the v2 - chain); always back-look high-risk work (auth, migrations, shared repos). **The merge gate - does not widen** — the operator merges, in every phase. There is no agent merge path, now - or planned. +- **Next** — migrate the current profile behind portable adapters, establish the + control/eval/reconciliation foundation, then enable bounded writes one stage at a + time. [`ROADMAP.md`](ROADMAP.md) is authoritative. **The merge gate does not widen** — + the operator merges in every phase. diff --git a/REVIEW.md b/REVIEW.md index 20e183f..4c912e7 100644 --- a/REVIEW.md +++ b/REVIEW.md @@ -15,7 +15,7 @@ Run three passes and tag each finding with its pass: - **Compliance**: the diff matches `work//plan.md` and `spec.md` (when the PR belongs to a chain); safety rails intact — reviewer stays comments-only, round cap and `needs-human` escalation intact, no-merge guards untouched, constitution - paths (`.github/**`, `.claude/**`, `AGENTS.md`, `CLAUDE.md`, `REVIEW.md`) changed only by the + paths (`.github/**`, `.claude/**`, `AGENTS.md`, `CLAUDE.md`, `REVIEW.md`, `ROADMAP.md`) changed only by the operator or via `proposals/`. ## What Important means here diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..190402c --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,298 @@ +# ystack roadmap — a portable AI-native SDLC + +This document records the direction between the north star and individual +`work//` initiatives. It preserves the architecture decisions that future +specs and plans must follow. It is not an implementation plan by itself. + +The reference model is Anthropic's +[AI-Native SDLC Playbook](https://claude.com/blog/the-ai-native-sdlc-playbook), +supplemented by its +[AI-native SDLC security guidance](https://claude.com/blog/how-anthropic-secures-its-ai-native-software-development-lifecycle), +[NIST SSDF](https://csrc.nist.gov/pubs/sp/800/218/final), and +[DORA](https://dora.dev/guides/dora-metrics/). The playbook supplies useful +control objectives, not vendor requirements or a recipe to copy unchanged. + +## Product boundary + +ystack is a control plane for a governed software-delivery loop. Its core is: + +- **harness-neutral** — Claude Code, Codex CLI, Gemini CLI, an Agent SDK, or a + custom runner may fill an agent role; +- **model-neutral** — model names and vendors belong to a selected profile; +- **forge-neutral** — GitHub, GitLab, Bitbucket, or another Git forge may host + the same change-request and approval contract; +- **CI-neutral** — GitHub Actions, GitLab CI, Bitbucket Pipelines, or another CI + system may provide checks and execution; +- **Git-backed first** — committed Git artifacts are the initial durable source + of truth. Supporting a non-Git version-control system is not a current goal. + +The first shipped profile may prefer GitHub + GitHub Actions, Claude Code as a +producer, and Codex as a reviewer. Those are defaults, not requirements. + +## Self-hosting and target separation + +ystack is the product; a target repo is where that product runs. Target repos own +their north star, artifacts, project policy, selected profile, code, tests, and +delivery evidence. They do not inherit ystack's personal paths, credentials, or +operator approval. + +The ystack control-plane repo is intentionally its own first target. Using ystack +to develop ystack is the bootstrap and dogfood path: it exposes missing gates and +keeps the backup complete. It is not sufficient proof of portability, because a +control plane can accidentally special-case itself. + +The rollout therefore needs both: + +- **self-host proof** — ystack improves its own control plane through the same + artifacts and gates; and +- **external-target proof** — a fresh unrelated Git repo selects a profile and + completes the same contracts without copying ystack-specific state. + +Control-plane self-modification is always high risk. A self-hosted run cannot +rewrite or activate its own architecture, workflow, identity, eval, or safety +policy without the operator accepting the exact plan first. Source changes do +not silently change a running installation: release/sync and target upgrades are +explicit, versioned operator actions. + +## Control objectives + +Every implementation must preserve these rules regardless of adapter: + +1. Work flows through versioned artifacts: + `intent → spec → accepted plan → diff + tests → review → human merge → + deploy/rollback → production feedback/incident → new intent`. +2. One source of truth is named for every artifact. Forge issues, labels, and + comments are links, projections, and audit records; they are not a second + hidden state machine. +3. Human judgment stays at explicit gates. An author cannot approve its own + work, and no agent merges or passes a production gate by itself. +4. Risk changes the gate. High-risk work receives plan approval before code; + lower-risk work may combine plan and code review when eval evidence supports + that shortcut. +5. Skills and prompts are advisory. Rules that must always hold are enforced by + deterministic hooks, CI, sandbox policy, branch rules, and publishers. +6. Model output is untrusted. Candidate code never shares a sandbox with a + credential worth stealing. +7. Events are wake-up signals. A durable reconciler reads canonical state and + repairs missed, repeated, canceled, or partially completed runs. +8. Autonomy is earned in stages: manual → shadow/read-only → bounded write → + risk-tiered automation. Every stage has a kill switch. +9. Configuration changes are tested like code. Prompts, skills, hooks, models, + adapters, and permissions run against versioned evals. +10. The loop is measured by user value, quality, flow, recovery, and human + attention — never by code volume or token use alone. + +## Stable interfaces + +The core should use capabilities rather than vendor commands. + +### Artifact and Git + +- read an artifact at an exact commit; +- calculate and compare immutable identities; +- materialize an isolated snapshot or package; +- describe an allowed diff; +- record input and output commits. + +### Harness + +- plan from trusted artifacts in read-only mode; +- produce a bounded patch or structured artifact; +- review an exact change with no write authority; +- return a structured result and trace, with model and cost metadata when they + apply to that harness. + +### Forge + +- identify the repository and default branch; +- open or find one change request for a deterministic branch; +- read approvals and current head/base identities; +- post comments, labels, or status projections; +- expose branch and code-owner controls. + +### CI + +- start and observe deterministic checks; +- publish machine-verifiable evidence; +- retain check state and artifacts; +- enforce environment-specific gates. + +### Execution + +- provision a disposable, policy-bound environment; +- isolate candidate code from credentials and the host; +- deny network by default and expose only approved tools/resources; +- destroy the environment without losing the durable session record. + +### Orchestration and reconciliation + +- wake from an event, schedule, or operator request; +- scan canonical state for pending or stranded work; +- retry at least once delivery without duplicating effects; +- apply backpressure, cancellation, and a kill switch; +- return an actionable recovery reason to the operator. + +### Deployment and rollback + +- expose deploy, status, and rollback as environment-scoped capabilities; +- require the risk tier's named authorization; +- bind a release to verified source and evidence; +- rehearse and record rollback before autonomous maintenance can invoke it. + +### Observability and incident intake + +- record stage, tool, adapter, gate, identity, latency, and cost events; +- receive deterministic control-band or security-scan findings; +- create a canonical incident/intent artifact without granting deploy authority; +- feed shipped failures back into evals. + +### Publisher and identity + +- use a short-lived, single-purpose identity; +- validate base, allowed paths, proof, approval state, and output identity; +- never execute candidate code or invoke a model; +- perform only the fixed external write for its stage. + +Adapters implement these interfaces. Core artifacts and policies must not call +`gh`, `glab`, `claude`, or `codex` directly. + +## Canonical state and audit + +Git artifacts and their immutable identities are canonical. A forge adapter may +project state into PR/MR labels such as `stale` or `needs-human`, but deleting a +label must not erase the underlying state. + +Each stage record must make these facts recoverable: + +- initiative and stage; +- input and output commit identities; +- risk tier and required gate; +- harness and adapter identity/config, plus model, effort, prompt/skill version, + and cost when they apply; +- run, retry, skip, stale, and failure reason; +- proof identity and check result; +- human decision and timestamp. + +Delivery is **at least once**. Idempotency and reconciliation make repeated +delivery safe; the system does not pretend webhook delivery is exactly once. + +## Risk-tiered gates + +The initial policy is: + +- **High risk** — constitution paths, workflows, identity/auth, security + controls, database/schema migrations, deployment, production infrastructure, + or broad architectural change. A human accepts `plan.md` before code. +- **Routine** — small, reversible, well-tested work within an accepted spec and + established architecture. Plan and code may share the final change request, + provided an independent plan check passes before the write phase. +- **Bootstrap** — work that creates its own CI or gate. It stays human-gated and + cannot certify itself. + +Every tier still requires deterministic checks and a human merge. Changing the +tier policy requires eval evidence and an operator decision. + +An **accepted plan** always has a recorded decision before code. For high-risk +work that decision is the operator's approval. For routine work it may be an +independent plan check backed by eval evidence; the producing agent cannot accept +its own plan. + +## Security architecture + +Agent execution is split into independent boundaries: + +1. **Planner/producer (brain)** — model access, trusted inputs, no repository + write credential. It produces an artifact or patch. +2. **Verifier** — no model credential, no forge write credential, no network by + default. It runs candidate code and produces commit-bound evidence. +3. **Reviewer** — read-only access to the exact change. It cannot edit, approve, + or merge. +4. **Publisher (hands)** — no model and no candidate-code execution. It validates + the artifact and uses a short-lived adapter credential for one fixed write. +5. **Session/telemetry** — a durable append-only record outside every disposable + execution sandbox. + +Agent-to-agent routes count as capabilities and must be included in the same +permission and threat model as direct tools. + +## Evals and measurements + +Before bounded autonomous writes, ystack needs a small regression suite built +from real work. It must cover, at minimum: + +- stale and moved artifacts; +- repeated, canceled, and missed events; +- approval invalidation and no-push-after-approval; +- actor and rerun identity; +- malicious issue, PR/MR, diff, and comment instructions; +- protected-path, credential, network, and publisher boundaries; +- empty, fake, timed-out, and degraded reviews; +- reviewer severity and false-positive/false-negative behavior; +- adapter contract compliance. + +Agent evals run multiple trials where behavior is stochastic. Deterministic, +model-based, and human graders are combined and calibrated. Production failures +become permanent regression cases. + +The operating dashboard should pair flow and quality: + +- intent-to-spec and accepted-plan-to-merge time; +- queue and human-gate wait; +- first-pass success and rework cycles; +- review latency, precision, recall samples, and stale rate; +- escaped defects and vulnerabilities; +- retry/reconciliation recovery; +- token, latency, and cost per accepted change; +- DORA throughput and instability metrics; +- user or service outcome for the target change. + +## Rollout sequence + +The roadmap is intentionally ordered by dependency, not by playbook stage name. +Each numbered item becomes its own intent/spec/plan chain and small PRs. + +1. **Portable control-plane core** — canonical contracts, capability manifests, + profile resolution, fake adapters, and adapter contract tests. +2. **Control foundation** — brain/verifier/publisher separation, sandbox and + credential policy, risk gates, kill switch, and immutable evidence. +3. **Durable orchestrator** — canonical state scanner, at-least-once retry, + reconciliation, backpressure, and operator recovery messages. +4. **Default adapters** — GitHub forge, GitHub Actions CI, Claude Code producer, + and Codex reviewer as the first preference profile. +5. **Agent evals and telemetry** — eval/trace framework, then real default-adapter + regression and qualification evidence, cost/latency, and flow/quality dashboard. +6. **Alternative adapters** — prove at least one alternative harness and one + alternative forge against the same contract and safety evals. GitLab is the + recommended first alternative forge. +7. **Shadow vertical slice** — run the artifact lane read-only/manual on real + self-host and external-target changes, including adversarial and recovery + smoke tests. +8. **Bounded autonomous writes** — enable one low-risk stage at a time in an + independent PR after shadow evidence passes. +9. **Safe review-fix loop** — add autonomous fixes only after the credential and + reconciliation boundaries are proven. +10. **Target packaging** — install profiles and adapters into a fresh target + without copying personal configuration. +11. **Deploy and rollback** — environment tiers, named production gate, rehearsed + rollback, and delivery evidence. +12. **Maintenance loop** — deterministic control bands and scans create new + intents; service owners triage; shipped incidents become evals. + +## Current disposition + +- PR #146 is a draft experiment and must not merge. It records useful failure + modes from a GitHub/Claude-specific implementation. +- The old Phase 2 event names are not product requirements. A supported event is + acceptable only when it is trusted, durable, idempotent, and recoverable. +- The previous Phase 3 controls and the reconciler portion of Phase 4 move ahead + of autonomous write enablement. +- Existing in-session and autonomous paths must converge on the same artifact + source of truth before either is called the product loop. + +## Non-goals for the first initiative + +- implementing every harness or forge; +- opening autonomous write access; +- deployment or production monitoring; +- replacing Git as the first artifact store; +- preserving Claude, Codex, or GitHub as mandatory dependencies. diff --git a/ci/required-files.txt b/ci/required-files.txt index f1d6f6f..8a0deee 100644 --- a/ci/required-files.txt +++ b/ci/required-files.txt @@ -15,6 +15,7 @@ AGENTS.md QUICKSTART.md RESTORE.md NORTH_STAR.md +ROADMAP.md # Manager persona manager/CLAUDE.md diff --git a/work/README.md b/work/README.md index e3b315a..e510f52 100644 --- a/work/README.md +++ b/work/README.md @@ -1,13 +1,17 @@ # work/ — the v2 artifact chain One initiative per directory: `work//`. Every stage commits an artifact the -next stage reads; the operator's PR merges are the only human gates. +next stage reads. G1/G2/G3 are operator merge gates. High-risk work adds a +pre-code plan gate: the operator's decision is recorded against the exact +`plan.md` blob before implementation. Until the portable stage record exists, +use a separately merged plan PR. Any plan change invalidates that acceptance and +must return to the plan gate. | Artifact | Written by | Gate that accepts it | |---|---|---| | `intent.md` | operator + `/intent-draft` | **G1** — operator merges the `intent: ` PR | | `spec.md` | `/spec-draft` (spec stage) | **G2** — operator merges the `spec: ` PR | -| `plan.md` | `/plan-draft`, first commit of the impl branch | **G3** — operator approves + merges the implementation PR (plan + code + tests) | +| `plan.md` | `/plan-draft`, before implementation | **Plan gate** — operator accepts the exact blob before high-risk code; routine work records an independent plan check before code, then the operator accepts plan + code + tests at G3 | **Chain state is the artifacts themselves, hash-linked.** `spec.md` frontmatter records `intent-blob` — the `git hash-object` of the intent it was drafted from; @@ -19,6 +23,7 @@ stop — never build on a moved artifact. `ystack/impl/`. A re-run updates the existing branch/PR; it never opens a second PR for the same slug. -Today the stages run by hand (`/intent-draft`, `/spec-draft`, `/plan-draft` in a -Claude Code session); Phase 2 wires them to GitHub events. The gates never change -either way. +Today the artifact stages run by hand. Autonomous wiring is paused: draft PR #146 +proved that portable adapters, credential separation, evals, and durable +reconciliation must land first. [`ROADMAP.md`](../ROADMAP.md) is the authoritative +rollout order; no forge event name or agent harness is a core gate. From 4cd48b44aa2dec63988799e80509402a64084bea Mon Sep 17 00:00:00 2001 From: ci Date: Thu, 27 Aug 2026 19:48:58 -0400 Subject: [PATCH 2/2] roadmap: clarify plan gate rollout --- AGENTS.md | 24 +++++++++++++----------- README.md | 6 ++++-- ROADMAP.md | 2 +- proposals/README.md | 2 +- work/README.md | 15 +++++++++------ 5 files changed, 28 insertions(+), 21 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index aa2f282..b1b84d6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,11 +51,14 @@ Two goals drive the backlog: ## PR rules (enforced by coder + reviewer) - **One concern per PR.** Soft size budget ~300–400 net lines; split if bigger. - Every PR links its issue (`Closes #`) and keeps README/docs in sync with any change. -- **Risk sets the plan gate.** High-risk work — constitution paths, workflows, - identity/auth, security controls, migrations, deployment/production infrastructure, - or broad architecture — requires the operator to accept `plan.md` before code. - Routine work may keep plan + code in one PR only after an independent plan check - records acceptance before the write phase. The author cannot accept its own plan. +- **Accepted roadmap policy — not yet a live gate:** risk will set the plan gate. + High-risk work — constitution paths, workflows, identity/auth, security controls, + migrations, deployment/production infrastructure, or broad architecture — will require + the operator to accept `plan.md` before code. Routine work may keep plan + code in one + PR only after an independent plan check records acceptance before the write phase. The + author cannot accept its own plan. The current manager does not enforce this yet; until + the portable control foundation wires and evaluates it, the existing gate rules for + each lane remain authoritative and nobody may claim a pre-code plan gate passed. - **Plain language, always** (operator rule, 2026-08-26): every artifact (intent/spec/plan), PR title/description, and review comment is written for a tired human. Short sentences. Everyday words. No jargon where a plain word @@ -77,16 +80,15 @@ Two goals drive the backlog: user-directed issue is gated by the user's approval of the drafted spec (the one-liner is the request, not the go), a proactive issue by the passed yshifu⇄Codex manager-debate consensus (for *proactive* work the user's gate is at the north-star altitude; user-directed issues - still need the user's spec approval). This intake rule does not waive the later high-risk - plan gate: proactive and user-directed high-risk work both return to the operator before code. + still need the user's spec approval). The accepted roadmap adds a later high-risk plan + gate for both paths. It is planned policy, not a gate the current manager enforces. ## v2 artifact chain (work/) - One initiative = one dir: `work//` holding `intent.md` → `spec.md` → `plan.md`. Each artifact lands via its own PR and the operator's merge IS the gate: G1 accepts - the intent, G2 approves the spec, and G3 approves the implementation. High-risk work - records a separate operator acceptance of `plan.md` before code; routine work may carry - an independently accepted plan with code + tests in the implementation PR. Details: - `work/README.md`; review policy: `REVIEW.md`. + the intent, G2 approves the spec, and G3 approves the implementation. The accepted + roadmap adds a separate pre-code plan gate based on risk; it does not become live until + both lanes enforce it. Details: `work/README.md`; review policy: `REVIEW.md`. - Skills: `/intent-draft`, `/spec-draft`, `/plan-draft` hold the templates and stage rules. - **Hash discipline:** `spec.md` frontmatter records `intent-blob` (`git hash-object` of the intent it was drafted from); `plan.md` records `spec-blob`. On mismatch with main's diff --git a/README.md b/README.md index 6d7ae2f..f2e6b43 100644 --- a/README.md +++ b/README.md @@ -96,8 +96,10 @@ exactly one coder launch per cleared issue, one review path, and one revision pa [`reviewer/manager-review.md`](reviewer/manager-review.md)). For *proactive* work you are pulled back in only at the north-star altitude: **north-star achieved**, **goal drift / transition**, and `needs-human` escalations — user-directed issues still come to you for the - drafted-spec approval. This intake autonomy does not waive the risk-tiered plan gate: - high-risk proactive or user-directed work returns to you for plan approval before code. + drafted-spec approval. The accepted roadmap adds a risk-tiered plan gate after intake: + high-risk proactive or user-directed work will return to you for plan approval before + code. That gate is not wired into the current manager yet; `ready` must not be described + as plan approval. - **CI is the hard gate** — ground truth. Autonomy rests on tests first, diverse reviewer second. - **yshifu never merges — it labels, then hands you the PR.** Merging is the operator's, diff --git a/ROADMAP.md b/ROADMAP.md index 190402c..a3bb538 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -178,7 +178,7 @@ delivery safe; the system does not pretend webhook delivery is exactly once. ## Risk-tiered gates -The initial policy is: +The target policy is: - **High risk** — constitution paths, workflows, identity/auth, security controls, database/schema migrations, deployment, production infrastructure, diff --git a/proposals/README.md b/proposals/README.md index ac4324c..5549b5f 100644 --- a/proposals/README.md +++ b/proposals/README.md @@ -1,7 +1,7 @@ # proposals/ Patches to the constitution paths — `.github/**`, `.claude/**`, `AGENTS.md`, `CLAUDE.md`, -`REVIEW.md` — which unattended agents may not write directly. +`REVIEW.md`, `ROADMAP.md` — which unattended agents may not write directly. An autonomous-lane agent that wants to change how the machinery itself works saves a unified diff here (`proposals/-.patch`) with a one-paragraph diff --git a/work/README.md b/work/README.md index e510f52..42b3c19 100644 --- a/work/README.md +++ b/work/README.md @@ -1,17 +1,20 @@ # work/ — the v2 artifact chain One initiative per directory: `work//`. Every stage commits an artifact the -next stage reads. G1/G2/G3 are operator merge gates. High-risk work adds a -pre-code plan gate: the operator's decision is recorded against the exact -`plan.md` blob before implementation. Until the portable stage record exists, -use a separately merged plan PR. Any plan change invalidates that acceptance and -must return to the plan gate. +next stage reads. Within this artifact chain, G1/G2/G3 are the live operator merge +gates. The in-session manager still uses its existing intake, CI, review, and human +merge gates. The accepted roadmap adds a risk-based pre-code plan gate, but neither +lane enforces it yet. Once both lanes wire that gate, the operator's decision must be +recorded against the exact `plan.md` blob before high-risk implementation. Until the +portable stage record exists, that means a separately merged plan PR. Any plan change +invalidates that acceptance and must return to the plan gate. Do not claim this planned +gate passed before the enforcement change lands. | Artifact | Written by | Gate that accepts it | |---|---|---| | `intent.md` | operator + `/intent-draft` | **G1** — operator merges the `intent: ` PR | | `spec.md` | `/spec-draft` (spec stage) | **G2** — operator merges the `spec: ` PR | -| `plan.md` | `/plan-draft`, before implementation | **Plan gate** — operator accepts the exact blob before high-risk code; routine work records an independent plan check before code, then the operator accepts plan + code + tests at G3 | +| `plan.md` | `/plan-draft` | **G3 today; target plan gate after enforcement lands** — operator accepts the exact blob before high-risk code; routine work records an independent plan check before code, then the operator accepts plan + code + tests at G3 | **Chain state is the artifacts themselves, hash-linked.** `spec.md` frontmatter records `intent-blob` — the `git hash-object` of the intent it was drafted from;