From 992610d407aad2979958f812e6df39fb62d444fd Mon Sep 17 00:00:00 2001 From: ci Date: Thu, 27 Aug 2026 19:59:25 -0400 Subject: [PATCH 1/2] intent: portable-control-plane-core --- work/portable-control-plane-core/intent.md | 77 ++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 work/portable-control-plane-core/intent.md diff --git a/work/portable-control-plane-core/intent.md b/work/portable-control-plane-core/intent.md new file mode 100644 index 0000000..fbd3a95 --- /dev/null +++ b/work/portable-control-plane-core/intent.md @@ -0,0 +1,77 @@ +# Intent: portable control-plane core +Author: Yihan (operator). Status: draft. + +## Problem + +ystack's current control plane mixes its durable workflow with one preferred +implementation. Core roles, prompts, model settings, review scripts, GitHub +events, labels, secrets, and publishing commands name Claude, Codex, and GitHub +directly. A different coding harness or Git forge cannot run the same governed +loop without rewriting the product. + +That coupling also hides the true safety contract. Cross-vendor review is useful, +but the requirement is separation of duties and independently verified evidence, +not a particular pair of vendors. + +## Proposed outcome + +ystack has a small, vendor-neutral core that defines artifacts, stage results, +risk gates, evidence, and adapter capabilities. A selected profile supplies the +producer, verifier, reviewer, forge, CI, execution, identity, and publisher +adapters used by a stage. An adapter is a small bridge between the core and an +external tool. The core's extension rules let later orchestration, deployment, +and incident capabilities join without changing existing artifact or audit +meaning; this initiative does not design those later contracts. + +The current GitHub + GitHub Actions + Claude Code + Codex combination remains a +working default while this core is introduced. Contract tests can swap fake +harness adapters while holding the forge fixed, then swap fake forge adapters +while holding the harness fixed. Each combination preserves the same canonical +artifacts, gates, and audit meaning. Validation fails when an adapter lacks a +required safety capability. + +## Affected users and systems + +The operator; future adopters; target repositories; the `work/` artifact chain; +canonical stage/result schemas; profile resolution; capability declarations; +fake adapters; contract tests; and the current setup that must keep working while +later initiatives extract its real adapters. + +## Constraints + +- Git is the first canonical version-control and artifact protocol. GitHub is an + adapter, not a requirement. +- Claude Code and Codex are preference adapters, not core requirements. +- Core policies and artifacts cannot call vendor CLIs, APIs, events, secrets, or + model names directly. +- Author, verifier, reviewer, and publisher capabilities remain separated. An + adapter cannot weaken no-self-approval, human merge, proof, or sandbox rules. +- Canonical formats must be extensible across + `intent → spec → accepted plan → build → verify → independent review → human + merge → deploy/rollback → production feedback/new intent` without changing + earlier audit meaning. This initiative defines only the common artifact/result/ + profile/capability foundation; later initiatives design and implement + orchestration, deployment, and monitoring. +- The current setup must keep working unchanged. Real adapter extraction happens + in later initiatives; there is no one all-at-once rewrite. +- ystack remains its own first target for dogfooding, but core contracts cannot + special-case the control-plane repo. Contract tests include an unrelated target + fixture, and a later external-target smoke is required before portability is proven. +- Start with interfaces, fake adapters, and contract tests. Do not enable new + autonomous writes in this initiative. +- Keep changes small, reversible, documented, and reconstructable from the repo. + +## Open questions + +- What is the smallest extensible result format for the complete + `intent → spec → accepted plan → build → verify → independent review → human + merge → deploy/rollback → production feedback/new intent` loop, without + implementing the later stages now? +- Which capability is required at each risk tier, and how does an adapter declare + that it cannot safely support one? +- Should canonical skills live under `.ystack/skills/`, an open Agent Skills + layout, or another neutral package with generated harness bridges? +- What compatibility period should the existing Claude/Codex scripts and config + keys receive? +- What compatibility evidence must a later real harness or forge adapter provide + before it can join a supported profile? From 077aee34eea86ab3d4f96e899308dc34d2e90b70 Mon Sep 17 00:00:00 2001 From: ci Date: Thu, 27 Aug 2026 20:08:33 -0400 Subject: [PATCH 2/2] intent: keep portable core to contracts --- work/portable-control-plane-core/intent.md | 35 ++++++++++++---------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/work/portable-control-plane-core/intent.md b/work/portable-control-plane-core/intent.md index fbd3a95..bd6f37e 100644 --- a/work/portable-control-plane-core/intent.md +++ b/work/portable-control-plane-core/intent.md @@ -15,20 +15,22 @@ not a particular pair of vendors. ## Proposed outcome -ystack has a small, vendor-neutral core that defines artifacts, stage results, -risk gates, evidence, and adapter capabilities. A selected profile supplies the -producer, verifier, reviewer, forge, CI, execution, identity, and publisher -adapters used by a stage. An adapter is a small bridge between the core and an -external tool. The core's extension rules let later orchestration, deployment, -and incident capabilities join without changing existing artifact or audit -meaning; this initiative does not design those later contracts. +ystack has a small, vendor-neutral core that defines artifact and stage-result +contracts, risk metadata, evidence references, and adapter capabilities. A +selected profile supplies the producer, verifier, reviewer, forge, CI, execution, +identity, and publisher adapters used by a stage. An adapter is a small bridge +between the core and an external tool. The core's extension rules let later +control, orchestration, deployment, and incident capabilities join without +changing existing artifact or audit meaning; this initiative does not design or +enforce those later controls. The current GitHub + GitHub Actions + Claude Code + Codex combination remains a working default while this core is introduced. Contract tests can swap fake harness adapters while holding the forge fixed, then swap fake forge adapters -while holding the harness fixed. Each combination preserves the same canonical -artifacts, gates, and audit meaning. Validation fails when an adapter lacks a -required safety capability. +while holding the harness fixed. Each combination preserves the same artifact, +policy, and audit contract. Contract validation rejects malformed or incompatible +declarations. Later initiatives decide, prove, and enforce the capabilities a +risk tier requires. ## Affected users and systems @@ -67,11 +69,12 @@ later initiatives extract its real adapters. `intent → spec → accepted plan → build → verify → independent review → human merge → deploy/rollback → production feedback/new intent` loop, without implementing the later stages now? -- Which capability is required at each risk tier, and how does an adapter declare - that it cannot safely support one? +- What risk metadata and capability declarations must the core carry so later + policies can decide whether an adapter may support a risk tier? - Should canonical skills live under `.ystack/skills/`, an open Agent Skills layout, or another neutral package with generated harness bridges? -- What compatibility period should the existing Claude/Codex scripts and config - keys receive? -- What compatibility evidence must a later real harness or forge adapter provide - before it can join a supported profile? +- What compatibility seams must the contracts expose so later adapter extraction + can preserve current behavior without putting vendor names in the core? +- What fields must an evidence reference and fake-adapter contract-test result + carry so later eval initiatives can set real-adapter qualification rules without + changing audit meaning?