Resolves #10794
Authored by GPT-5 (Codex Desktop). Session dbb1a88c-987f-4519-9645-8f13e9d71000.
Refines the substrate-mutation gate without adding another rule surface: the author-side pull-request workflow now scopes slot-rationale to turn-loaded or skill-loaded memory substrate, and the reviewer-side PR template now exposes the existing /turn-memory-pre-flight loading-runtime-effect audit as a conditional trigger. This keeps ordinary learn/agentos/** operator/reference docs out of the PR-body duplication path when their slot rationale already lives in-doc.
Evidence: L1 (static substrate diff + skill-manifest lint + focused lint unit coverage) -> L1 required (#10794 ACs are workflow/template substrate text). No residuals.
Deltas from Ticket
The ticket text was partially stale at intake. Current substrate already had the detailed reviewer Required Action wording in pr-review-guide.md and the learn/agentos/*.md carve-out in /turn-memory-pre-flight. This PR implements the residual only:
- author-side
pull-request-workflow.md now points the gate at true memory substrate, including directly turn-/skill-loaded learn/agentos/** files only;
- reviewer-side
pr-review-template.md now has a visible Turn-Memory / Substrate-Load conditional audit trigger, pointing to the existing guide audit instead of duplicating its body.
Decision Record impact: aligned with ADR 0007 and ADR 0008; no ADR amendment needed.
Related: #10757
Substrate Mutation Rationale
.agents/skills/pull-request/references/pull-request-workflow.md §1.1: disposition rewrite. The existing author gate remains in the pull-request workflow Map because it fires during PR opening, but the wording now matches /turn-memory-pre-flight instead of treating all learn/agentos/** docs as future-session memory substrate. Trigger-frequency: PR-open only; failure-severity: medium/high for false-positive author friction and missed slot-rationale gates; enforceability: lint-assisted plus reviewer discipline.
.agents/skills/pr-review/assets/pr-review-template.md: disposition compress-to-trigger. The template gets one conditional trigger line; the substantive Required Action body stays in pr-review-guide.md loading-runtime-effect audit. Trigger-frequency: only PRs touching memory substrate; failure-severity: high when missed because reviewers can approve on file-completeness while missing runtime-load effect; enforceability: template + lint-skill-manifest reference integrity.
Load-effect audit: no SKILL.md, AGENTS.md, harness-local turn injection, or new always-loaded router content changed. Both edits are lifecycle-loaded skill payload/template surfaces, and the substantive rule body remains behind existing skill loads. Net substrate delta is small and validated under the workflow-map positive-delta budget.
Test Evidence
git diff --check
npm run ai:lint-skill-manifest -- --base origin/dev
npm run ai:lint-agents -- --base origin/dev
npm run test-unit -- test/playwright/unit/ai/scripts/lint/lintSkillManifest.spec.mjs --workers=1
git diff --check passed.
lint-skill-manifest passed, including workflow-map delta budget and reference integrity.
lint-agents passed.
lintSkillManifest.spec.mjs passed: 35/35.
Post-Merge Validation
Commit
ffcd8297f - feat(agent): refine substrate mutation gate (#10794)
Resolves #10794
Authored by GPT-5 (Codex Desktop). Session dbb1a88c-987f-4519-9645-8f13e9d71000.
Refines the substrate-mutation gate without adding another rule surface: the author-side
pull-requestworkflow now scopes slot-rationale to turn-loaded or skill-loaded memory substrate, and the reviewer-side PR template now exposes the existing/turn-memory-pre-flightloading-runtime-effect audit as a conditional trigger. This keeps ordinarylearn/agentos/**operator/reference docs out of the PR-body duplication path when their slot rationale already lives in-doc.Evidence: L1 (static substrate diff + skill-manifest lint + focused lint unit coverage) -> L1 required (#10794 ACs are workflow/template substrate text). No residuals.
Deltas from Ticket
The ticket text was partially stale at intake. Current substrate already had the detailed reviewer Required Action wording in
pr-review-guide.mdand thelearn/agentos/*.mdcarve-out in/turn-memory-pre-flight. This PR implements the residual only:pull-request-workflow.mdnow points the gate at true memory substrate, including directly turn-/skill-loadedlearn/agentos/**files only;pr-review-template.mdnow has a visible Turn-Memory / Substrate-Load conditional audit trigger, pointing to the existing guide audit instead of duplicating its body.Decision Record impact: aligned with ADR 0007 and ADR 0008; no ADR amendment needed.
Related: #10757
Substrate Mutation Rationale
.agents/skills/pull-request/references/pull-request-workflow.md §1.1: dispositionrewrite. The existing author gate remains in the pull-request workflow Map because it fires during PR opening, but the wording now matches/turn-memory-pre-flightinstead of treating alllearn/agentos/**docs as future-session memory substrate. Trigger-frequency: PR-open only; failure-severity: medium/high for false-positive author friction and missed slot-rationale gates; enforceability: lint-assisted plus reviewer discipline..agents/skills/pr-review/assets/pr-review-template.md: dispositioncompress-to-trigger. The template gets one conditional trigger line; the substantive Required Action body stays inpr-review-guide.mdloading-runtime-effect audit. Trigger-frequency: only PRs touching memory substrate; failure-severity: high when missed because reviewers can approve on file-completeness while missing runtime-load effect; enforceability: template +lint-skill-manifestreference integrity.Load-effect audit: no
SKILL.md,AGENTS.md, harness-local turn injection, or new always-loaded router content changed. Both edits are lifecycle-loaded skill payload/template surfaces, and the substantive rule body remains behind existing skill loads. Net substrate delta is small and validated under the workflow-map positive-delta budget.Test Evidence
git diff --checkpassed.lint-skill-manifestpassed, including workflow-map delta budget and reference integrity.lint-agentspassed.lintSkillManifest.spec.mjspassed: 35/35.Post-Merge Validation
Commit
ffcd8297f-feat(agent): refine substrate mutation gate (#10794)