roadmap: portable AI-native SDLC

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/<slug>/`** 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/<slug>/`** 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,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 #<n>`) and keeps README/docs in sync with any change.
+- **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
@@ -70,21 +80,23 @@ 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). 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/<slug>/` 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. 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
   current upstream file, label the PR `stale` and stop — never build on a moved artifact.
 - **Stage rules (autonomous lane):** the spec stage writes only `work/<slug>/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 +106,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
 

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** · <!-- ystack-shipped-default --> 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** · <!-- ystack-shipped-default --> 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,19 +82,24 @@ 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
   *achieved*. Original done-signal: `doctor.sh` exits 0 + an accurate fresh-clone
   `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

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,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.
+  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,
@@ -128,17 +135,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 +230,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 +266,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.