Share acceptance mapping and complexity control policy

AGENTS.md

@@ -30,6 +30,34 @@ Edit `AGENTS.md` and run `scripts/sync-agent-docs.sh` to regenerate `CLAUDE.md`.
   refused; the helper form uses the `gh` login. Never store a credential, never change global git
   configuration, never push with force (`jpdev push` refuses `--force` and `-f`).
 
+## Acceptance mapping and complexity control
+
+- Maintain one current requirement → implementation → verification → remaining-gate checklist
+  per issue or related batch in its existing issue, pull request or handoff. Update that record;
+  do not introduce a parallel tracking system.
+- Before adding an abstraction, ownership layer, recovery mechanism or work item, check whether
+  the existing design already satisfies the requirement. Prefer the smallest design that preserves
+  all accepted behavior and safety contracts; retain distinct authorities where required.
+- Distinguish authored, executed, reviewed, integrated and released work. Source review or a
+  passing component check does not establish end-to-end completion. Report remaining gates.
+- Reuse existing execution harnesses, fixtures and controls. A separate harness needs a concrete
+  unmet requirement, not merely a new issue or worker.
+- Plan disk and execution headroom for a useful batch, including temporary output, cache growth
+  and retained evidence. Repeated small cleanups do not replace that plan. Preserve cleanup
+  authorization, activity checks, operator reserves and other sessions' work.
+- Before diagnosing a failed check, preserve the exact candidate, command and failure. Change
+  the relevant implementation or execution condition before retrying. A recurring cause requires
+  resolving the underlying problem, not another near-identical attempt. Required fresh-worker
+  handoffs carry the diagnosis and evidence; this does not waive stop or handoff rules.
+- Group related findings into a correction round. Verify the findings and changed paths; repeat
+  broad reviews or full validation only when substantive changes, unresolved evidence or repository
+  requirements justify it. Worker handoffs and review rounds are not issues closed.
+
+These rules preserve independent review, security checks, exact-head CI, ownership, delegation
+and cleanup authorization, and merge/release gates. Simplification must preserve accepted outcomes;
+scope or gate changes remain maintainer decisions. Keep the dependency-ordered batch, focused-check
+and stable integrated-validation guidance above.
+
 ## Before you hand over
 
 Run these self-checks on the builder's own head before writing the commit message:

CLAUDE.md

@@ -30,6 +30,34 @@ Edit `AGENTS.md` and run `scripts/sync-agent-docs.sh` to regenerate `CLAUDE.md`.
   refused; the helper form uses the `gh` login. Never store a credential, never change global git
   configuration, never push with force (`jpdev push` refuses `--force` and `-f`).
 
+## Acceptance mapping and complexity control
+
+- Maintain one current requirement → implementation → verification → remaining-gate checklist
+  per issue or related batch in its existing issue, pull request or handoff. Update that record;
+  do not introduce a parallel tracking system.
+- Before adding an abstraction, ownership layer, recovery mechanism or work item, check whether
+  the existing design already satisfies the requirement. Prefer the smallest design that preserves
+  all accepted behavior and safety contracts; retain distinct authorities where required.
+- Distinguish authored, executed, reviewed, integrated and released work. Source review or a
+  passing component check does not establish end-to-end completion. Report remaining gates.
+- Reuse existing execution harnesses, fixtures and controls. A separate harness needs a concrete
+  unmet requirement, not merely a new issue or worker.
+- Plan disk and execution headroom for a useful batch, including temporary output, cache growth
+  and retained evidence. Repeated small cleanups do not replace that plan. Preserve cleanup
+  authorization, activity checks, operator reserves and other sessions' work.
+- Before diagnosing a failed check, preserve the exact candidate, command and failure. Change
+  the relevant implementation or execution condition before retrying. A recurring cause requires
+  resolving the underlying problem, not another near-identical attempt. Required fresh-worker
+  handoffs carry the diagnosis and evidence; this does not waive stop or handoff rules.
+- Group related findings into a correction round. Verify the findings and changed paths; repeat
+  broad reviews or full validation only when substantive changes, unresolved evidence or repository
+  requirements justify it. Worker handoffs and review rounds are not issues closed.
+
+These rules preserve independent review, security checks, exact-head CI, ownership, delegation
+and cleanup authorization, and merge/release gates. Simplification must preserve accepted outcomes;
+scope or gate changes remain maintainer decisions. Keep the dependency-ordered batch, focused-check
+and stable integrated-validation guidance above.
+
 ## Before you hand over
 
 Run these self-checks on the builder's own head before writing the commit message:

README.md

@@ -256,11 +256,35 @@ duplication.min_tokens: an integer from 10 to 10000 is required (got 5)`.
 
 | Toolchain | Cap |
 | --- | --- |
-| `node` | `lib/rsscap.sh`: the process group's resident memory and a timeout; never `ulimit -v`, which breaks vite and vitest |
+| `node` | `lib/rsscap.sh`: the launched session's sampled resident memory and a timeout; never `ulimit -v`, which breaks vite and vitest |
 | `go` | `flock` on the machine lock, `ulimit -v`, `GOFLAGS=-mod=readonly` (a step never rewrites `go.mod`), a per-clone `GOCACHE`, `timeout` |
 | `python` | `ulimit -v` and `timeout` |
 | `shell` | `timeout` only |
 
+The RSS guard counts all non-zombie processes in the new session, including GNU
+`timeout` and compiler/test children in other process groups. It keeps monitoring
+until the session is empty, even when the original command exits first. Memory,
+time and interruption stops kill the session's observed process groups. The
+command's exit status is preserved when no guard stops it. Limits are positive
+integers of at most nine digits; RSS is compared in KiB against the MiB limit.
+
+This is a cooperative, sampled guard, not a security boundary or a hard memory
+reservation. Between samples a process may exceed the limit. Descendants that
+call `setsid` leave the owned session and are neither measured nor cleaned up;
+use an external containment mechanism for workloads that detach this way. Shared
+pages can be counted more than once when summing resident memory.
+
+For a Go race check that cannot use the virtual-address limit, retain the existing
+wrapper's lock, per-clone cache, read-only module mode and inner timeout:
+
+```sh
+JPDEV_GO_ULIMIT_KB=unlimited lib/rsscap.sh 4096 300 -- lib/wrap.sh go -- go test -race ./...
+```
+
+This explicit invocation applies the outer RSS/time limits to the wrapper and its
+session. Normal Go steps retain their existing virtual-address cap. A limit that
+fires while the wrapper waits for the lock also stops that wait.
+
 When the manifest declares a virtual environment, its path must be a non-root relative child of
 the clone with no `..` segment, and setup and checks create it when it is missing.
 They use `python3.X` on PATH first, then the newest `~/.pyenv/versions/3.X.*/bin/python3`, and

config/env.example

@@ -11,11 +11,12 @@
 # The machine lock every Go step holds, so two sessions never run Go at once.
 #JPDEV_LOCK="$JPDEV_SCRATCH/harness.lock"
 
-# Node steps: the resident-memory cap of the step's process group (MB) and its default timeout (s).
+# Node steps: the resident-memory cap of the step's session (MiB) and its default timeout (s).
 #JPDEV_NODE_RSS_MB=6000
 #JPDEV_NODE_TIMEOUT_S=1200
 
 # Go steps: ulimit -v (KB) and the default timeout (s). The per-clone GOCACHE sits under JPDEV_SCRATCH.
+# Set unlimited only with an explicit outer RSS guard for a race check; see README.md.
 #JPDEV_GO_ULIMIT_KB=12000000
 #JPDEV_GO_TIMEOUT_S=3000
 # Go steps always run with GOFLAGS=-mod=readonly and the per-clone GOCACHE, which lib/wrap.sh sets

docs/adopting.md

@@ -353,5 +353,15 @@ refusal is a fresh run of the job's whole list. Adopt it in the repository's own
 Required status names, the matrix, the release workflow's fresh checks and its publication gates
 do not change. Measure before claiming a saving: record the executed checks and their timings on
 the repository's own runs before and after. A repository with its own evidence verifier
-(judgment-pack-agent's `scripts/dev/ci_evidence.py`) adopts this through its own reviewed
-compatibility work, not by replacing that verifier with the kit's.
+adopts this through its own reviewed compatibility work. It may retain that verifier or replace
+it with the kit's gate only when its adoption pull request maps every guarantee the old verifier
+gave to a gate check, a configuration entry or an unchanged release job. The mapping must show
+that no guarantee is lost; an unmapped guarantee blocks replacement until it is preserved.
+Passing the kit's tests alone does not establish equivalence for an adopter.
+
+For an example, [judgment-pack-agent #267](https://github.com/Judgment-Pack/judgment-pack-agent/pull/267)
+replaced `scripts/dev/ci_evidence.py` with `release_evidence.py` and mapped its mutation shards,
+advisory, approval, provenance and paired Go tag coverage. Each adopter must supply its own
+reviewed mapping, including its refusal behavior and publication gates. This permission does not
+remove independent or security review, exact-head CI, or merge and release approvals, and does
+not authorize a consumer rollout by itself.

docs/ci-evidence.md

@@ -497,7 +497,7 @@ and each of these must hold, or nothing is reused:
 
 | Input | Bound by |
 | --- | --- |
-| the trusted relationship | records that survive the merge and that the pull request's code cannot write, read through the API: one pull request of this repository (not a fork, base repository this one) merged into the trusted branch with M as its merge commit; its head branch's listing (`pulls?head=owner:branch&state=all`, every page to an empty one, ten at most) shows exactly that one pull request ever, from this repository; its timeline (every page) has no base-change event of any kind (`base_ref_changed`, `automatic_base_change_succeeded`, `automatic_base_change_failed`, and any event whose name contains `base_change` or `base_ref`); the newest `pull_request` run of the same workflow is at its final head, from this repository, on its head branch, and was created after the pull request was opened. The run's own `pull_requests`, which GitHub clears once a pull request merges, must name exactly that pull request into the trusted branch when it is not empty. Anything of this that cannot be read refuses (`reuse-pull-request`) |
+| the trusted relationship | records that survive the merge and that the pull request's code cannot write, read through the API: one pull request of this repository (not a fork, base repository this one) merged into the trusted branch with exactly one timeline `merged` event whose `commit_id` equals M (the pinned API has no `merge_commit_sha` on PR objects); its head branch's listing (`pulls?head=owner:branch&state=all`, every page to an empty one, ten at most) shows exactly that one pull request ever, from this repository; its timeline (every page) has no base-change event of any kind (`base_ref_changed`, `automatic_base_change_succeeded`, `automatic_base_change_failed`, and any event whose name contains `base_change` or `base_ref`); the newest `pull_request` run of the same workflow is at its final head, from this repository, on its head branch, and was created after the pull request was opened. The run's own `pull_requests`, which GitHub clears once a pull request merges, must name exactly that pull request into the trusted branch when it is not empty. Anything of this that cannot be read refuses (`reuse-pull-request`) |
 | exact source and tree | the merge commit the pull request job checked out (S), read through the API: its parents are M's first parent and the pull request's head, and its tree is M's tree |
 | the base relationship | S was made on M's first parent: a change set tested on another base is not M's, even with the same tree (a rebase merge of several commits therefore never qualifies) |
 | workflow, configuration and dependency digests | the pull request job's input identities (the manifest, the configuration, the gate, the workflow files, every pin file) equal M's |
@@ -698,3 +698,37 @@ the fresh route's full CI run and a re-run.
 GitHub's API contracts: [workflow runs](https://docs.github.com/en/rest/actions/workflow-runs),
 [attempt jobs](https://docs.github.com/en/rest/actions/workflow-jobs),
 [artifacts](https://docs.github.com/en/rest/actions/artifacts).
+
+
+## Pinned API response audit
+
+The gate sends API version `2026-03-10`. Read-only response projections captured on
+2026-11-01 are in `tests/fixture/github-api-2026-03-10.json`, from
+`judgment-pack-agent` PR #267 and run 41149914554, and the annotated
+`judgment-pack-devkit` v0.13.0 tag. The fixture records its source identities and the
+consumed field paths. Unrelated fields and personal identities are omitted. These
+are API contract samples, not execution evidence or generated acceptance vectors.
+Handwritten decision/refusal vectors remain in `tests/release_evidence_test.py`.
+
+| API record | Fields read by the gate |
+| --- | --- |
+| Repository | `id`, `full_name`, `default_branch` |
+| Annotated tag reference/object | reference `ref`; `object.type`, `object.sha` at each peel |
+| Workflow | `id`, `path`, `name`, `state` |
+| Run listing/single run | `id`, `run_attempt`, `event`, `head_branch`, `head_sha`, `workflow_id`, `path`, `status`, `conclusion`, `created_at`, `run_started_at`, `updated_at`, `repository.id/full_name`, `head_repository.id/full_name`, `pull_requests` |
+| Nonempty run PR association | `number`, `base.ref`, `base.repo.id` |
+| Job | `id`, `name`, `run_id`, `run_attempt`, `head_sha`, `head_branch`, `workflow_name`, `status`, `conclusion`, `labels`, `runner_group_id`, `runner_group_name`, `started_at`, `completed_at` |
+| Artifact | `id`, `name`, `expired`, `size_in_bytes`, `created_at`, `digest`, `workflow_run.id/head_sha/head_branch/repository_id/head_repository_id`; ZIP bytes |
+| Git commit | `sha`, `tree.sha`, `parents[].sha` |
+| Commit-associated PR | `number`, `state`, `created_at`, `merged_at`, `head.sha/ref/repo.id`, `base.ref/repo.id` |
+| Head-branch PR listing | `number`, `head.repo.id` |
+| PR timeline | `event`; a `merged` event's `commit_id` |
+| Paged wrappers | `total_count` and `workflow_runs`, `jobs` or `artifacts`; every row's `id` for uniqueness |
+
+All listed paths were checked against the captured records. The merged run has an
+empty PR association; a separate captured run, 41223435315, checks the nonempty
+association fields.
+`merge_commit_sha` is absent on both the commit-associated PR and single-PR
+responses. Missing, unreadable, malformed or ambiguous merge events refuse with
+`reuse-pull-request`; no PR-supplied record substitutes for the timeline. The same
+complete timeline is used for the existing base-change checks.

docs/policy.md

@@ -38,6 +38,34 @@ are the ones a brief does not repeat.
 - **Each commit is signed off, no history is rewritten.** Pushes are never forced, and go
   through the `gh` credential helper (`jpdev push`), never a stored credential.
 
+## Acceptance mapping and complexity control
+
+- Maintain one current requirement → implementation → verification → remaining-gate checklist
+  per issue or related batch in its existing issue, pull request or handoff. Update that record;
+  do not introduce a parallel tracking system.
+- Before adding an abstraction, ownership layer, recovery mechanism or work item, check whether
+  the existing design already satisfies the requirement. Prefer the smallest design that preserves
+  all accepted behavior and safety contracts; retain distinct authorities where required.
+- Distinguish authored, executed, reviewed, integrated and released work. Source review or a
+  passing component check does not establish end-to-end completion. Report remaining gates.
+- Reuse existing execution harnesses, fixtures and controls. A separate harness needs a concrete
+  unmet requirement, not merely a new issue or worker.
+- Plan disk and execution headroom for a useful batch, including temporary output, cache growth
+  and retained evidence. Repeated small cleanups do not replace that plan. Preserve cleanup
+  authorization, activity checks, operator reserves and other sessions' work.
+- Before diagnosing a failed check, preserve the exact candidate, command and failure. Change
+  the relevant implementation or execution condition before retrying. A recurring cause requires
+  resolving the underlying problem, not another near-identical attempt. Required fresh-worker
+  handoffs carry the diagnosis and evidence; this does not waive stop or handoff rules.
+- Group related findings into a correction round. Verify the findings and changed paths; repeat
+  broad reviews or full validation only when substantive changes, unresolved evidence or repository
+  requirements justify it. Worker handoffs and review rounds are not issues closed.
+
+These rules preserve independent review, security checks, exact-head CI, ownership, delegation
+and cleanup authorization, and merge/release gates. Simplification must preserve accepted outcomes;
+scope or gate changes remain maintainer decisions. Keep the dependency-ordered batch, focused-check
+and stable integrated-validation guidance above.
+
 ## Testing
 
 - **Verify the world, not the self-report.** Check claims against artifacts: the candidate head