fix(commit): append known plan unit ids to commit subjects (#1379)

docs/skills/ce-commit-push-pr.md

@@ -96,7 +96,7 @@ There is no fixed template. A typo can be one or two sentences. A large refactor
 
 ### Named-file commits, then a branch decision tree
 
-Same commit rules as `/ce-commit`: no `git add -A`, file-level splits only, convention from context then history then conventional commits (`fix:` when `fix:` and `feat:` both fit).
+Same commit rules as `/ce-commit`: no `git add -A`, file-level splits only, convention from context then history then conventional commits (`fix:` when `fix:` and `feat:` both fit). A known plan unit ID is appended to the subject in parentheses (`(U3)` for unit 3) when it is already in hand for that commit.
 
 Branch routing is explicit:
 

docs/skills/ce-commit.md

@@ -57,7 +57,7 @@ A rushed commit often does one of these:
 - Files are staged by name. Never `git add -A` or `git add .`
 - Distinct concerns become separate commits at file level only (2-3 max, no `git add -p`). Ambiguous grouping stays one commit
 - Detached HEAD or the default branch gets a feature branch first, with no prompt
-- The subject is imperative and names what is now possible or fixed. A body is added only when the why is not obvious
+- The subject is imperative and names what is now possible or fixed. A body is added only when the why is not obvious. When a plan unit ID is already in hand for that commit, that U-ID is appended in parentheses (`(U3)` for unit 3)
 
 ---
 

skills/ce-commit-push-pr/SKILL.md

@@ -86,7 +86,7 @@ If on the default branch, branch creation needs to handle stale local `<base>`,
 
 Scan changed files for naturally distinct concerns. If they clearly group into separate logical changes, create separate commits (2-3 max). Group at file level only — no `git add -p`. When ambiguous, one commit is fine.
 
-Stage and commit each group. **Avoid `git add -A` and `git add .`** — they sweep in `.env`, build artifacts, and generated files:
+Stage and commit each group. **Avoid `git add -A` and `git add .`** — they sweep in `.env`, build artifacts, and generated files. When a plan Implementation Unit ID is already in hand for this commit (conversation, caller, or the files belong to one unit), append that unit's U-ID in parentheses — `(U3)` means unit 3. Do not hunt for a plan. Omit when the commit spans units, the unit is unclear, or no plan is in hand.
 
 ```bash
 git add file1 file2 file3 && git commit -m "$(cat <<'EOF'

skills/ce-commit-push-pr/references/stack-submit.md

@@ -37,7 +37,7 @@ When one safe topology is clear, proceed without asking: explicit stack intent a
 
 Choose the bottom-layer path from the branch checked out when retrospective construction began. If construction starts on the resolved default branch and no parent was named, follow `references/branch-creation.md` to fetch and resolve its safe base, including the unpushed-local-commit decision and stash protection. If construction starts on an existing feature branch, do not follow `references/branch-creation.md`: fetch the resolved base `<base>` from Topology — the repo default branch unless a parent was named — from its base remote, verify the fetched remote-tracking tip, and use that exact tip as the bottom parent. When Topology already resolved the parent to a verified local branch, use that instead: a fork head materialized from `refs/pull/<n>/head` has no remote-tracking branch to fetch or verify. Record the original branch and tip, preserve the original tip with a recovery ref or branch before any operation that could move it, and do not treat the feature commits between the bottom parent and original tip as unpushed commits on the local default or carry the whole feature tip into the bottom layer. Every upstack layer starts from its immediate parent through `gh stack add`.
 
-For uncommitted whole-file groups on an existing feature branch, save all tracked and untracked working changes before switching branches, then restore them only on the planned layer whose parent contains their prerequisites; keep the saved work until the constructed top is verified complete. Initialize or adopt the bottom layer at the resolved `<base>` tip or its planned commit tip, commit only its files, then add and commit each next layer in order:
+For uncommitted whole-file groups on an existing feature branch, save all tracked and untracked working changes before switching branches, then restore them only on the planned layer whose parent contains their prerequisites; keep the saved work until the constructed top is verified complete. Initialize or adopt the bottom layer at the resolved `<base>` tip or its planned commit tip, commit only its files, then add and commit each next layer in order. Compose `<bottom-message>` and `<next-message>` with the same subject rule as Step 3: when a plan Implementation Unit ID is already in hand for that layer's commit, append that unit's U-ID in parentheses — `(U3)` means unit 3. Do not hunt for a plan. Omit when the commit spans units, the unit is unclear, or no plan is in hand.
 
 ```bash
 gh stack init --base "<base>" "<bottom-branch>"

skills/ce-commit/SKILL.md

@@ -37,10 +37,11 @@ Treat this as a snapshot. Re-read branch and staged set immediately before commi
 
 4. **Logical commits** — if changed files clearly split into distinct concerns, make separate commits (file level only, 2–3 max, no `git add -p`). If ambiguous, one commit.
 
-5. **Message** — subject is imperative and names the outcome (what is now possible or fixed), not the file list. Body only when motivation or trade-offs are not obvious from the subject.
+5. **Message** — subject is imperative and names the outcome (what is now possible or fixed), not the file list. Body only when motivation or trade-offs are not obvious from the subject. When a plan Implementation Unit ID is already in hand for this commit (conversation, caller, or the files belong to one unit), append that unit's U-ID in parentheses — `(U3)` means unit 3. Do not hunt for a plan. Omit when the commit spans units, the unit is unclear, or no plan is in hand.
 
    - Bad: `Update checkout.rb` / `Add tests and fix stuff`
    - Good: `Fix double-submit on checkout`
+   - Good: `Add per-subscription mute (U3)`
 
 6. **Stage and commit** — stage **named files only** (never `git add -A` or `git add .`). Prefer one shell call per commit group:
 

tests/ce-commit-contract.test.ts

@@ -56,6 +56,9 @@ describe("ce-commit contract", () => {
     expect(content).toMatch(/names the outcome/)
     expect(content).toContain("Fix double-submit on checkout")
     expect(content).toContain("Update checkout.rb")
+    expect(content).toContain("append that unit's U-ID in parentheses — `(U3)` means unit 3")
+    expect(content).toContain("Do not hunt for a plan")
+    expect(content).toContain("Omit when the commit spans units")
   })
 
   test("scopes to local commits and points ship flow at ce-commit-push-pr", async () => {

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

@@ -167,6 +167,14 @@ describe("ce-commit-push-pr contract", () => {
     expect(content).toMatch(/PR description.+not.+comment/i)
   })
 
+  test("appends a known plan unit id to the commit subject without hunting", async () => {
+    const content = await readRepoFile("skills/ce-commit-push-pr/SKILL.md")
+
+    expect(content).toContain("append that unit's U-ID in parentheses — `(U3)` means unit 3")
+    expect(content).toContain("Do not hunt for a plan")
+    expect(content).toContain("Omit when the commit spans units")
+  })
+
   test("adds generic Compound Engineering branding only on an explicit signal", async () => {
     const reference = await readRepoFile(
       "skills/ce-commit-push-pr/references/pr-description-writing.md",
@@ -330,6 +338,8 @@ describe("PR concept teaching contract", () => {
       readRepoFile("skills/ce-commit-push-pr/references/gh-stack-cli.md"),
     ])
 
+    expect(submit).toContain("Compose `<bottom-message>` and `<next-message>` with the same subject rule as Step 3")
+    expect(submit).toContain("append that unit's U-ID in parentheses — `(U3)` means unit 3")
     expect(submit).toMatch(/named a parent PR or branch to stack on, classify it/i)
     expect(submit).toContain("references/gh-stack-cli.md")
     expect(submit).toMatch(/Classify by \*\*PR number\*\*.{0,140}pulls a stack down from GitHub/is)