Post-merge cleanup: five deferred Copilot review nits from M1 PRs #1781

Context

PRs #1775, #1776, #1777, and #1778 were all merged on 2026-08-20 after Flight verified each Copilot inline comment as non-blocking. Brady's ruling: merge now, file the nits as a single cleanup issue. These were reviewed, assessed as harmless, and deferred deliberately — they were not ignored.

All five items are cosmetic or dead-code. None affect correctness of the M1 fixes.

Items

1 — gh-aw.md L120: git add description over-broad (PR #1776, PAO)

docs/src/content/docs/guide/gh-aw.md L120 states the git add command "stages everything gh aw add wrote." gh aw add also writes .vscode/settings.json, which that command does not stage. Flight's read: true observation, but the git add path correctness that #1761 was fixing is unaffected.

Outcome options: tighten the prose to name the specific paths staged, or add a note that .vscode/settings.json is created but not staged here.

2 — gh-aw.md L128: "workflow logs directory" less specific than pre-edit (PR #1776, PAO)

L128 says "workflow logs directory" where the pre-edit text was the more specific .github/aw/logs/. Flight's read: nit, no functional impact.

Outcome options: restore the specific path, or accept the current prose as intentionally less brittle.

3 — pao/history.md references an uncommitted decision record (PR #1776, PAO)

.squad/agents/pao/history.md contains Decision record: .squad/decisions/inbox/pao-1761-gh-aw-path-verification.md. That path was never committed. The phrasing "Decision record: <path>" implies the file exists. Flight's read: consistent with the convention that .squad/ is git-excluded locally, but misleading in a persisted history entry.

Outcome options: rewrite as "Findings recorded in decisions.md (merged from pao-1761-gh-aw-path-verification.md)" or similar, making clear the record was merged rather than persisted as a standalone file.

4 — Dead runGate() helper in gh-aw-quality.test.ts (PR #1777, EECOM)

test/gh-aw-quality.test.ts defines a runGate() helper that is never called — tests use inline spawnSync instead. Flight's read: correct observation, not a defect, no runtime impact.

Outcome options: remove runGate(), or promote it to replace the inline spawnSync calls for consistency.

5 — skillBlock() off-by-one drops leading # when next skill exists (PR #1778, Procedures)

test/gh-aw-plan-lifecycle.test.ts's skillBlock() helper slices from start + 1, so when a following skill block exists the returned content drops its leading # character. Flight's read: technically real off-by-one. Harmless in current usage — every assertion targets content deeper in the block, and nextIdx correctly identifies the block boundary.

Outcome options: fix the slice index (start not start + 1) to return the complete block including its heading character, or add a comment acknowledging the deliberate drop.

Success Criteria

Each item is independently closeable. This issue is done when every item has either a merged fix or an explicit one-line decline recorded here.

SC-1: gh-aw.md L120 prose is tightened to name staged paths, or a note acknowledges the .vscode/settings.json omission. Fails if the over-broad phrasing remains with no accompanying note.

SC-2: gh-aw.md L128 either restores the specific path or carries a comment accepting the current prose. Fails if neither choice is recorded.

SC-3: pao/history.md's reference to the uncommitted inbox path is reworded to reflect the record was merged, not committed as a standalone file. Fails if the phrasing still implies the inbox path exists as a file.

SC-4: runGate() is either removed or promoted to replace inline spawnSync calls. Fails if the unused function remains with no accompanying comment explaining why.

SC-5: skillBlock()'s slice index is corrected, or a code comment explicitly documents the intentional drop of the leading #. Fails if the off-by-one remains undocumented.

Related

• PR docs: fix gh-aw guide — correct git add paths, demote compile step, add restricted-secrets callout #1776 (items 1, 2, 3 — PAO)
• PR fix(dispatch): raise max to 2 and add schema static gate (#1772) #1777 (item 4 — EECOM)
• PR Fix long-path planning lifecycle defects + guard empty dispatch probe (squad.md) #1778 (item 5 — Procedures)
• PR fix(ci): wire gh aw compile as a real CI gate (#1732) #1775 (referenced for completeness; no open nits)