diff --git a/work/target-reviewer-policy-delivery/intent.md b/work/target-reviewer-policy-delivery/intent.md new file mode 100644 index 0000000..b9ce3ff --- /dev/null +++ b/work/target-reviewer-policy-delivery/intent.md @@ -0,0 +1,112 @@ +# Intent: deliver policy to target reviewers +Author: Yihan (operator). Status: draft. + +## Problem + +PR #164 defines an exceptional-implementation and source-comment rule for ystack, +its coder routines, and its Claude-facing target template. The rule says reviewers +must block unexplained exceptions. An independent reviewer running inside another +target repository may never see it. + +Codex reviewers normally read the target's applicable `AGENTS.md`. A target may +instead have only the optional `CLAUDE.md` template, and a reviewer cannot see +ystack's control-plane `REVIEW.md`. Treating those files as equivalent would create +a silent enforcement gap. Copying the full rule into several templates would create +a different problem: the author and reviewer versions could drift. + +This is the strict-subset follow-up from issue #163 and PR #164, recorded as issue +#165. It carries only the operator-approved requirement to make the same accepted +rule reliably available to independent target reviewers. It does not reopen the +other #164 policy decisions and is unrelated to PR #154. + +## Proposed outcome + +ystack has one versioned, portable way to deliver an accepted review-policy floor +to every selected target reviewer. The author, coder, and reviewer see the same +meaning without making Claude, Codex, GitHub, or one instruction filename a core +requirement. + +The delivery path records the exact policy identity and the adapter or target +instruction identity that carried it. Generated or bridged forms are checked +against one source of truth. Missing, stale, incompatible, or candidate-controlled +review rules fail closed rather than silently weakening review. + +The result is proven on ystack and on an unrelated target fixture. A pull request +that changes its own applicable reviewer instructions cannot use those candidate +instructions to certify itself. + +## Affected users and systems + +The operator; target maintainers; Claude and other coding agents; current and future +independent reviewer adapters; target `AGENTS.md` and `CLAUDE.md` conventions; +review-policy packages or generated sections; target setup and upgrade paths; +profile resolution; contract tests; restore documentation; self-host and unrelated +target qualification evidence. + +## Constraints + +- Parent scope is issue #163. This child carries only the target-reviewer delivery + gap recorded in #165 and the scoped final review of PR #164. +- G1 may proceed now. G2 waits for #164 to merge, then pins the accepted policy + source by exact commit and blob identities. No implementation may claim the + unmerged #164 proposal is already active policy. +- A repo-native template or checked generated section may proceed after that policy + dependency. If G2 selects portable contract, profile-resolution, or reviewer- + adapter fields, it also waits for and pins the accepted G2 artifacts from + `portable-core-contracts`, `portable-profile-resolution`, and + `portable-adapter-contract-tests`; implementation pins their G3 commits. +- Live adapter/profile activation waits for the accepted control foundation, + durable orchestrator, default-adapter qualification, and environment-specific + evidence required by the roadmap. General target install/upgrade machinery stays + in the later target-packaging initiative; this child cannot implement it early. +- Core policy remains harness-, model-, and forge-neutral. Product names, + instruction filenames, comment triggers, App identities, and vendor review + formats belong only in templates, adapters, or selected profiles. +- Keep one source of truth for rule meaning. Any target-specific, harness-specific, + or generated form must be derived from or mechanically checked against it; do + not maintain independent prose copies that can drift. +- Resolve effective reviewer instructions from an accepted trust anchor outside + the candidate change. Record exact source and delivered identities. Candidate + content cannot choose, replace, weaken, or certify its own review floor. +- When a pull request adds or changes an applicable instruction or review-policy + file, route that change through a separately trusted reviewer or human gate. +- Preserve the #164 floor: root-cause first; accepted-before-code exceptions; one + private boundary; regression proof; durable provenance; temporary removal or + permanent external-invariant lifecycle; no copy or reusable API; no safety-rail + waiver; and no blanket core comment ban. +- A target may ban optional comments more strictly, but required legal/tooling/API, + safety/protocol, and exception-provenance material must remain in source or an + accepted sidecar/metadata mechanism. +- Existing target instruction files are operator-owned. Setup or upgrades cannot + overwrite them silently. Detect conflicts, show the proposed change, and require + the target's normal acceptance path. +- Reviewer delivery grants no source write, approval, merge, label, bypass, or + general task capability. It only supplies trusted review instructions and records + what was used. +- Prove clean, missing, stale, drifted, self-modifying, conflicting, and stricter- + target cases with deterministic fixtures. Later real qualification covers both + ystack and an unrelated target; one successful review is not portability proof. +- Keep restore and reconstruction possible without personal paths or secrets. + External installation/settings are referenced and diagnosed, not stored as + credentials in the repository. +- This initiative does not choose a target `AGENTS.md` template, generated section, + instruction package, or adapter-injection design at G1. G2 compares those options + and selects the smallest one that meets the constraints. +- Do not change live reviewer selection, enable automatic review, delete the local + reviewer, merge any PR, or touch PR #154 in this initiative. +- Keep each artifact and implementation PR within the normal size and one-concern + limits. Constitution-path changes follow the operator/`proposals/` boundary. + +## Open questions + +- What is the single canonical policy source, and which parts are universal floor + versus target-specific additions? +- Should target delivery use a canonical `AGENTS.md`, a generated checked section, + a versioned instruction package, reviewer-adapter input, or a combination with + one mechanically enforced source of truth? +- How are existing target `AGENTS.md`/`CLAUDE.md` files merged or upgraded without + overwriting owner content or preserving stale generated text? +- What exact base/default-branch trust anchor and provenance prove which rules a + local CLI, native GitHub reviewer, or future adapter actually used? +- Which fixtures prove rule equivalence, target stricter-policy behavior, + self-modification safety, conflict handling, restore, and unrelated-target use?