fix(ce-commit-push-pr): let a PR opening carry what motivates it

CONCEPTS.md

@@ -160,6 +160,11 @@ A concrete failing instance kept in a skill's prose underneath the condition tha
 
 It exists because a condition is an abstraction, and the most literal host a skill ships to may fail to instantiate it — the shape is insurance for that reader rather than decoration for a capable one. Removing one is a behavior change and is verifiable only by running the skill on that host, never by re-reading the block. A shape can sit after the exclusion it illustrates without weakening it, because it rules on nothing; what does weaken an exclusion is a later clause that decides something, since that gives the reader somewhere else to land.
 
+### Proxy rule
+A rule that states its condition correctly and then enforces it with an absolute about form, order, or placement — where text may sit, what a section may contain — so that the absolute, rather than the condition, is what later readers apply. It differs from a case list in looking complete: the condition is present, and the absolute agrees with it on every case the author had in mind.
+
+A proxy holds only while the condition's usual case is its only case, and it forbids the input for which the condition demands the opposite form. Replication is how the defect spreads rather than an aggravating detail — a copy placed at a site that does not own the decision gets rewritten for that site's local job, which compresses the condition into whatever that job can act on, and the compression then contradicts the owner. The characteristic failure is an audit built on the proxy: it does not merely fail to catch bad work, it instructs a reader to degrade correct work. A proxy also reads differently across hosts, since a literal reader obeys the absolute where a permissive one treats it as style, so a single-host evaluation can pass one.
+
 ### Context-absent agent
 An agent performing a Skill-shaped action without that Skill's instructions loaded in context — typically reconstructing a half-remembered command, recognizable by parameter values that drift from the Skill's documented defaults. Prose in the unloaded Skill cannot reach it; the only channels that do are the seam it entered through and the output of the tools it runs, which is why fail-closed refusals in bundled CLIs carry their own recovery path.
 

docs/solutions/skill-design/portable-agent-skill-authoring.md

@@ -178,6 +178,8 @@ If yes, it is likely **protocol**. Keep it explicit and falsifiable.
 
 If removal mainly gives a capable model more freedom to reason, it is likely **judgment**. First try deleting it. If the outcome spine already guides the work and the realistic floor does not drift, leave it out. If observed behavior shows the guidance is needed, compress it to the smallest principle or contrast pair that closes the gap.
 
+**A placement or format absolute is protocol-shaped and is usually judgment wearing protocol's clothes.** A rule that constrains where text may sit or what a section may contain — "never part of the opening", "always its own block", "must come after" — is normally a proxy for a coherence condition the author stated correctly right beside it. The proxy agrees with the condition on the cases the author had in mind and forbids the input for which the condition demands the opposite form, so it does not merely miss bad work: an audit built on it instructs a reader to degrade correct work. State the condition and let placement fall out of it, at the one layer that owns the decision; a copy at a site that does not own it makes the shared absolute the only clause every site agrees on. Two tells that the proxy, not the condition, is now the operative rule: the same decision restated at more than one site in a procedure, and a maintainer rejecting output the skill was followed exactly to produce. Absolutes also read differently across hosts — a literal host obeys one where a permissive host treats it as style — so verify a placement rule on both rather than assuming a single-host pass generalizes. Worked case: `state-the-condition-not-a-placement-absolute.md`.
+
 | Usually protocol | Usually judgment |
 |---|---|
 | Output paths and stable file shapes | Long menus of possible reasoning approaches |

skills/ce-commit-push-pr/references/pr-description-writing.md

@@ -68,10 +68,11 @@ Build a compact internal **scope map** from the **complete oneline commit list a
 
 **Program altitude (multi-PR / series).** After the PR-local map, check whether this PR sits inside a larger program (multi-PR project, stack, series, multi-unit plan). Use only signals already in hand: user prompt/conversation, a known plan path, existing PR body, commit messages, or sibling/series language in context. Do **not** invent a series, and do **not** run a repo-wide open-PR scan solely for this step.
 
-When program context is present, extend the map with: (1) **Program outcome** — end-to-end delivery in one sentence; (2) **This PR's contribution** — the local umbrella; (3) **Neighbors** — prior work (**lead-in**) and/or residual work (**lead-out**), each only when known. The map's order is **program → lead-in (if any) → this contribution → lead-out (if any)**; in the body the opening states this contribution and a short block after it supplies the rest (Step C). Early PRs need lead-out; middle need both; late need lead-in (and say the arc completes when true). Omit prior or next when unknown — never invent either. Program placement the reviewer cannot get from this PR's diff alone is decision cost. When program context is absent, keep the single-PR umbrella only.
+When program context is present, extend the map with: (1) **Program outcome** — end-to-end delivery in one sentence; (2) **This PR's contribution** — the local umbrella; (3) **Neighbors** — prior work (**lead-in**) and/or residual work (**lead-out**), each only when known. The map's order is **program → lead-in (if any) → this contribution → lead-out (if any)**; Step C decides how much of it the opening carries. Early PRs need lead-out; middle need both; late need lead-in (and say the arc completes when true). Omit prior or next when unknown — never invent either. Program placement the reviewer cannot get from this PR's diff alone is decision cost. When program context is absent, keep the single-PR umbrella only.
 
 - Bad (too local for a middle PR): the opening "Issue-close now revokes the active session on the server." with no placement anywhere in the body.
-- Good: that same opening, then a block: "Continues the session-revocation rewrite after refresh-path rejection; multi-device revocation remains follow-on." — the block adds the program and its neighbors, not a second copy of the outcome.
+- Good: that same opening, then a block: "Continues the session-revocation rewrite after refresh-path rejection; multi-device revocation remains follow-on." — the outcome stands on its own, so the block adds the program and its neighbors, not a second copy of the outcome.
+- Good (outcome does not stand on its own): "Sessions now carry a revocation epoch — the field that makes server-side revocation possible at all. Nothing reads it yet." Here the program is what gives the change its point, so the connection is part of the opening's one idea rather than a block after it.
 - Early/late: name first-slice + residual, or complete-the-arc + what already landed — same three fields, omit the unknown neighbor.
 
 **Write the finished map down before composing** — after the program-altitude check, so it carries both halves: umbrella; clusters with their claims; program placement or "none" (three or four lines). Step E audits the opening against this written map, not against memory.
@@ -90,7 +91,7 @@ Decision cost raises the content floor, not the length ceiling (high-uncertainty
 
 A project PR-body contract sets the structural floor; this table sizes the content within it, never against it. Small + simple: the value-led sentence is the whole description.
 
-**Medium and large: a reader can stop anywhere.** The opening is one or two sentences carrying one idea — what is now different and the gap or failure it replaces — so a reviewer who stops there knows what the PR does. Program or series context, when present, is a short additive block after it (Step C), never part of the opening's sentence. Each further section exists to answer one remaining reviewer question; a bullet is one clause, with reasoning under design decisions rather than inside the bullet. Deliberately deferred scope is stated once, not woven into the opening. Which sections and devices appear is decided by what the reviewer still cannot get from the diff (Visual aids, Step C) — this is not a section list.
+**Medium and large: a reader can stop anywhere.** The opening is one or two sentences carrying one idea — what is now different and the gap or failure it replaces — so a reviewer who stops there knows what the PR does. Step C decides what that one idea must include and what goes in the block after it. Each further section exists to answer one remaining reviewer question; a bullet is one clause, with reasoning under design decisions rather than inside the bullet. Deliberately deferred scope is stated once. Which sections and devices appear is decided by what the reviewer still cannot get from the diff (Visual aids, Step C) — this is not a section list.
 
 ---
 
@@ -158,7 +159,9 @@ Preserve an existing `## New concepts` section and explainer-doc link verbatim o
 
 When a project PR-body contract supplies headings or order, preserve that structure and place the applicable elements below within the sections it permits. Otherwise: opening → body sections that earn their keep → related references when they need their own block → test plan if non-obvious → session-settled provenance when a labeled plan is in hand → New concepts section when Step B2 produced one → evidence block if one exists → branding when Step D calls for it.
 
-When the project PR-body contract supplies a heading or location for the opening, place it there without inventing or renaming a heading. Otherwise, the opening goes under `## Summary` if the body uses any `##` headings; bare paragraph otherwise. No orphaned opening above the first heading. The opening carries one idea — this PR's outcome; it is the map's "this contribution" slot. When program context is present, a short block immediately after it adds only what the opening cannot: the program outcome and the known lead-in and lead-out. It never restates the outcome, and the program is never folded into the opening's sentence.
+When the project PR-body contract supplies a heading or location for the opening, place it there without inventing or renaming a heading. Otherwise, the opening goes under `## Summary` if the body uses any `##` headings; bare paragraph otherwise. No orphaned opening above the first heading.
+
+The opening carries one idea. The test is whether a reviewer who reads only it can say what this PR changes and why it takes this shape. Usually that one idea is the local outcome by itself — the map's "this contribution" slot. Sometimes the local outcome does not stand on its own, because the program is what gives it its shape or its point. Then the connection to the program is part of the one idea and belongs in the opening, and either half may lead — whichever reads better for this change. Naming which part of the program this PR delivers is what keeps that opening honest — an opening that names the arc but leaves a reviewer unable to say what this PR changes fails the same test. Everything the one idea does not need — the rest of the arc, deferred scope, implementation detail the diff supplies — goes in a short block immediately after the opening. That block supplies the program outcome and the known lead-in and lead-out, and never restates the outcome.
 
 **Session-settled provenance:** when a plan is already in hand (caller path or conversation) with `session-settled:`-labeled KTDs, one static sentence naming settled decisions and classes (e.g. "Session-settled decisions carried from planning: X (user-directed, over Y); Z (user-approved)."). Add proceed-under-conflict clauses only when the caller flagged them. Never an outstanding-items ledger; never hunt for plans when none is in hand.
 
@@ -190,7 +193,7 @@ Before returning the title and body, check against the scope map and material cl
 
 - Does the title express the umbrella outcome rather than one cluster or mechanism?
 - Does the opening express the same umbrella — every peer outcome the map names, at parity — rather than the cluster the work started from? If the map has three peer outcomes and the opening leads with one and mentions the others as "also" or "comes with", rewrite it from the map.
-- Does the opening carry one idea in one or two sentences, and could a reviewer stop there and know what the PR does? If it also carries program context, deferrals, or implementation detail the diff already supplies, move those out; mechanism that is itself the outcome (an atomicity, protocol, or API guarantee) stays in the opening, per the prose rule above.
+- Does the opening carry one idea in one or two sentences, and could a reviewer who reads only it say what this PR changes and why it takes this shape? A reader who does not already know this project is the test. If the local outcome reads as unmotivated without the program, the opening is missing that connection. If the opening names the arc but a reviewer cannot say which part of it this PR delivers, it is missing the outcome. Move out whatever that one idea does not need — the rest of the arc, deferrals, or implementation detail the diff already supplies. Mechanism that is itself the outcome (an atomicity, protocol, or API guarantee) stays in the opening, per the prose rule above.
 - Does any section, table, or hint restate what the Files-changed tab or diff already shows? Cut it. Does any section answer no remaining reviewer question? Cut it.
 - Is every material outcome represented by the umbrella framing or body, or intentionally omitted because it is supporting-only?
 - Is every claim the diff can't establish present — and any claim the diff *does* show restated needlessly?

tests/commit-push-pr-contract.test.ts

@@ -55,6 +55,34 @@ describe("ce-commit-push-pr contract", () => {
     // Bidirectional contrast: middle PR needs prior + residual, not local-only
     expect(sizingSection).toContain("too local for a middle PR")
     expect(sizingSection).toContain("Continues the session-revocation rewrite")
+    // #1422 enforced "one idea" with a placement absolute (program never in the
+    // opening's sentence). #1572 falsified it: a first-in-series change whose
+    // local outcome is unmotivated without the program was rejected twice for
+    // reading as if it had no point. Both directions stay pinned — the opening
+    // must stand alone, and the program joins it only when it is what gives the
+    // change its point.
+    expect(sizingSection).toContain("outcome does not stand on its own")
+    expect(content).not.toMatch(/never part of the opening's sentence/i)
+    expect(content).not.toMatch(/never folded into the opening/i)
+
+    const assemblySection = content.match(
+      /## Step C: Assemble the body([\s\S]+?)## Step D:/,
+    )?.[1]
+    expect(assemblySection).toBeDefined()
+    expect(assemblySection).toMatch(
+      /reviewer who reads only it can say what this PR changes and why it takes this shape/i,
+    )
+    expect(assemblySection).toMatch(/does not stand on its own/i)
+    // Both halves are required; the order is not. An earlier revision mandated
+    // "the bigger picture first", which contradicted the local-first worked
+    // example at the Step A bullet above and reinstated an ordering absolute of
+    // the same class this block removes (#1576 review). Keep it gone.
+    expect(assemblySection).toMatch(/either half may lead/i)
+    expect(content).not.toMatch(/the bigger picture first/i)
+    // The counter-failure: leading with the arc and losing the local outcome.
+    expect(assemblySection).toMatch(
+      /names the arc but leaves a reviewer unable to say what this PR changes/i,
+    )
 
     const auditSection = content.match(
       /## Step E: Pre-apply coverage audit([\s\S]+)\s*$/,
@@ -66,6 +94,11 @@ describe("ce-commit-push-pr contract", () => {
     expect(auditSection).toMatch(
       /program context was absent.+invent a multi-PR series/is,
     )
+    // The audit used to check placement ("move program context out"), which
+    // would have broken the accepted #1572 opening. It now checks legibility.
+    expect(auditSection).toMatch(/reader who does not already know this project/i)
+    expect(auditSection).toMatch(/reads as unmotivated without the program/i)
+    expect(auditSection).toMatch(/which part of it this PR delivers/i)
 
     // Tracker refs stay separate from series narrative
     const relatedSection = content.match(