Add docs/fork-discipline.md — generic contribution doctrine the cycle consults

Fork, maintenance, and validation rules were embedded only in an instance's
INTEGRATION.md (branch-from-upstream, cherry-pick-is-correctness, validate-against-
clean-upstream, the essential-line dependency, prior-art-by-path, draft-only-STOP).
The PCDA/quality-cycle/ docs are human reference and aren't read by the running
cycle; the process consults docs/INTEGRATION.md + docs/principles.md (agents are
pointed at them).

So add the doctrine as a generic, process-consulted reference following the
principles.md pattern:
- docs/fork-discipline.md.jinja — the generic rules (fork mechanics; draft-only +
  STOP; contribution targeting; validation against clean upstream; prior art), with
  "(instance: INTEGRATION.md §N)" markers so projects slot their answers. Generic →
  updates cleanly via copier; projects don't edit it.
- Cite it from the agents that act on it so the model reads it: planner (targeting +
  prior-art), builder (target-branch patch, cherry-pick correctness, placement,
  commit-ready), reviewer (cherry-pick/validation/prior-art → NEEDS-HUMAN), publisher
  (fork push discipline §1-2).

INTEGRATION.md keeps the project's answers and points here for the rules. Distinct
from principles.md (Plan-time solution design); this is Check-closing/contribution.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: eduralph

template/.claude/agents/builder.md.jinja

@@ -43,6 +43,11 @@ failing gate. Address it; do **not** re-submit the rejected approach unchanged.
 
 Cite `path:line` on the target branch for every claim and change.
 
+Write the patch against the brief's **target branch** and follow
+`docs/fork-discipline.md`: a cross-version cherry-pick must *remain correct* on the
+target, not just apply cleanly (§3); ship the test in the location the target branch
+uses (§3); make the patch commit-ready for the target's own hooks (§4).
+
 **When you reject an alternative on cost, show the cost** — a diff sketch or a concrete
 line count someone can check, never an adjective ("heavier", "larger", "touches every
 reader"). This matters most when your chosen fix *guards a symptom* (adds a probe/guard)

template/.claude/agents/planner.md.jinja

@@ -33,7 +33,9 @@ Either way the output file is `brief.md`, and you must keep the parsed
 `- **Label:** value` lines (the driver reads the spec from them). The load-bearing
 field is the **success criterion** — the sentence Check later tests "did this work"
 against. Resolve the **repo + branch target** here, and state **scope / out of
-scope** so Do can't sprawl.
+scope** so Do can't sprawl. Follow `docs/fork-discipline.md` for the targeting and
+prior-art rules — fixes ride the current maintenance line (§3); run the prior-art
+check by **affected file path**, across merged history *and* closed/rejected PRs (§5).
 
 **One issue or several (batch).** You run from the project root; your prompt names
 where to write. For a single issue it gives one bundle directory — write the one

template/.claude/agents/publisher.md.jinja

@@ -54,6 +54,10 @@ not push, branch, or open a PR yourself.**
   `cd <checkout> && …` (`git -C` is the safe idiom).
 - Resolve the branch target per INTEGRATION §2. One logical fix per PR; do not invent
   scope the brief didn't accept.
+- Follow `docs/fork-discipline.md` §1–§2: the contribution branches from
+  `upstream/<base>` (not the fork's drifted branch), the PR is **draft-only** and the
+  human marks it ready, and the deterministic `pdca publish` performs the push. Write
+  the commit-msg/PR prose to match the target; do not push or open the PR yourself.
 
 ## Boundaries
 

template/.claude/agents/reviewer.md.jinja

@@ -69,6 +69,12 @@ upstream-isn't-ahead; scope-creep / Plan re-entry; visual / manual-repro
 outcomes; and the project's enumerated human-only items (INTEGRATION.md §4).
 Each becomes a `- [ ]` row in `SUMMARY.md` §6 the human must clear.
 
+Judge the contribution against `docs/fork-discipline.md`: a cross-version
+cherry-pick that *applies cleanly* is not necessarily *correct* on the target (§3);
+validation must be against the **clean upstream** target, not the fork's branches
+(§4); and confirm the prior-art check ran by file path (§5). Where these can't be
+mechanically settled, raise them NEEDS-HUMAN.
+
 ### C5 symptom-guard smell-test
 
 The "contested symptom-vs-root-cause" trigger above has a concrete detection rule —

template/docs/fork-discipline.md.jinja

@@ -0,0 +1,108 @@
+# Fork & contribution discipline
+
+> The generic rules for contributing a fix upstream through a fork — the **Check
+> closing / contribution** discipline (the counterpart to [`principles.md`](principles.md),
+> which governs Plan-time solution design). These rules are project-agnostic; **your
+> project's concrete answers** — which branches, which remotes, which validation
+> runners — live in [`INTEGRATION.md`](INTEGRATION.md) (§2 branch targets, §5
+> upstream-isn't-ahead, §8 committing/PR, §10 maintainer). The cycle consults this
+> file: the planner, builder, reviewer, and publisher are each pointed here for the
+> rules they act on. Maintained as a generic reference — record a project specific in
+> `INTEGRATION.md`, not here.
+
+The split this file assumes: **the rules are generic and live here; the answers are
+per-project and live in `INTEGRATION.md`.** Where a rule needs a concrete value
+(a branch name, a remote, a runner), it says *"(instance: INTEGRATION.md §N)"* — fill
+it there, not by editing this file (so `copier update` keeps the rules current).
+
+## 1. Fork mechanics
+
+- **Remote layout.** `upstream` = the canonical project (read-only, the contribution
+  target); `origin` = **your fork** (where branches are pushed). The fork owner is
+  distinct from the upstream owner. *(instance: the actual repos/owner — INTEGRATION.md §5.)*
+- **Branch from `upstream/<base>`, never the fork's tracking branch.** A fork's
+  `maintenance/*` / default branches **drift** — they carry local CI/tooling commits
+  that must not ride into the contribution. Always `fetch upstream` and branch off
+  `upstream/<base>` so the diff is exactly the fix. *(A stray tooling file riding in on
+  a fork-based branch is the classic symptom.)*
+- **A fork-based PR's `--head` is `OWNER:BRANCH`.** The branch lives on the fork
+  (origin); `gh pr create --head <bare-branch>` resolves it against the *base* repo,
+  where it doesn't exist, and fails. The publish mechanics handle this deterministically.
+- **Keep the fork checkout clean.** Publish refuses on a dirty checkout. A
+  patch-apply-then-commit op must stage **added** files (a new test), not only modified
+  ones — `git apply` + `git add --all` + `git commit`, never `commit -a` (which silently
+  drops the new file). The same applies to a patch-and-revert validation gate: revert
+  *modified* files and **remove** *added* ones, or run in a throwaway worktree.
+
+## 2. Draft-only, and STOP
+
+- The automation **commits, pushes a branch, and opens a *draft* PR — then stops.** It
+  never marks a PR ready and never merges. Marking ready is the human's disposition
+  after a fresh-eyes re-read.
+- No push / PR-open / ready-mark happens without explicit instruction. This is
+  **mechanically enforced** by the builder/publisher PreToolUse hook (`builder_guard.py`),
+  not left to prompt discipline.
+- If a brief seems to require marking a PR ready, that is a brief defect — surface it
+  and stop; do not work around the block.
+
+## 3. Contribution targeting
+
+For a project with a single line of development this is one rule (target the default
+branch). For a project with **parallel maintenance lines**, the targeting matters:
+
+- **Fixes ride the current maintenance line and forward-merge** to the development
+  line; only genuinely new features target the development/`main` line. A fix sent to
+  the dev line alone doesn't reach released users. *(instance: the per-area branch map
+  — INTEGRATION.md §2.)*
+- **A maintainer's explicit base-branch request on the PR overrides the default.**
+- **Cross-version cherry-pick is a *correctness* check, not a conflict check.**
+  "Applies cleanly" is **not** "remains correct": verify a cherry-picked fix against the
+  *target branch's* related code — **including files the patch doesn't touch** — not just
+  that `git cherry-pick`/`git apply` succeeds.
+- **Where the test/artifact ships can differ by target.** Different branches or target
+  kinds (e.g. a core vs a plugin/addon contribution) may use different test locations or
+  naming conventions; the brief's **Test file** field must name the right one *for the
+  target branch*. Getting it wrong is a recurring Do error. *(instance: the per-target
+  conventions — INTEGRATION.md §3.)*
+
+## 4. Validation against upstream
+
+- **Validate against the *clean upstream* contribution target**, not the fork's
+  tooling-polluted branches and not a developer's working clone. Use a pinned checkout
+  of `upstream/<base>` (a per-version `git worktree` when the project has several target
+  versions) so "verified" means "verified against what reviewers will see." *(instance:
+  the runners + how the pinned targets are built — INTEGRATION.md §3.)*
+  - *Docker note:* a `git worktree`'s `.git` is a **file** pointing at the primary
+    gitdir; if you bind-mount a worktree into a container, also mount that gitdir at its
+    own absolute path or in-container git breaks.
+- **A fix may legitimately depend on an unmerged upstream fix.** When the contribution
+  target lacks a not-yet-merged prerequisite, **record the dependency** (e.g. retry
+  against an "essential" line = upstream + a minimal, evidence-based set of enabling
+  fixes, and write a dependency note into the bundle) rather than silently failing the
+  gate. Keep that enabling set minimal — add a fix only once a bundle demonstrably needs
+  it ([`principles.md`](principles.md) §8). *(instance: the essential set + manifest —
+  INTEGRATION.md §2.)*
+- **The patch must be commit-ready for the *target* repo.** The publish commit runs the
+  *target's own* pre-commit hooks (formatter/linters), which no PDCA gate models — so
+  "all gates green" ≠ committable. Run the project's configured formatter / commit hooks
+  before declaring done.
+
+## 5. Upstream-isn't-ahead (prior art)
+
+Before contributing, confirm the fix isn't already upstream or already rejected:
+
+- **Search by affected file *path*, not bug-id or keyword.** Anchoring on the path
+  catches side-effect fixes that an id/keyword search misses. (Mind host tokenization
+  quirks — a substring search may not match a compound word.)
+- **Check merged history *and* closed/rejected PRs** on the upstream repo(s) for that
+  path before opening a contribution. *(instance: the exact branches + search commands —
+  INTEGRATION.md §5.)*
+
+---
+
+**Who consults this.** Plan resolves the branch target and runs the prior-art check
+(§3, §5); Do writes the patch against the target branch, honoring cherry-pick
+correctness and test placement (§1, §3, §4); Check (reviewer) judges cherry-pick
+correctness, validation-against-upstream, and prior-art (§3–§5) and routes the
+unmechanizable ones to NEEDS-HUMAN; Publish performs the fork push under §1–§2. The
+deterministic git/PR mechanics are in `pdca_harness.publish`; this file is the *why*.