From ead38c265c5b393a5f1aad3727fdb3706d6b0e2c Mon Sep 17 00:00:00 2001
From: Aaron Stainback <aaron_bond@yahoo.com>
Date: Tue, 28 Apr 2026 02:15:14 -0400
Subject: [PATCH 1/2] backlog(B-0069): encode HEREDOC patterns into
 commit-message-shape skill (Aaron 2026-04-28)

---
 ...it-message-shape-skill-aaron-2026-04-28.md | 101 ++++++++++++++++++
 1 file changed, 101 insertions(+)
 create mode 100644 docs/backlog/P2/B-0069-heredoc-patterns-encode-into-commit-message-shape-skill-aaron-2026-04-28.md

diff --git a/docs/backlog/P2/B-0069-heredoc-patterns-encode-into-commit-message-shape-skill-aaron-2026-04-28.md b/docs/backlog/P2/B-0069-heredoc-patterns-encode-into-commit-message-shape-skill-aaron-2026-04-28.md
new file mode 100644
index 000000000..a1ab8a3ca
--- /dev/null
+++ b/docs/backlog/P2/B-0069-heredoc-patterns-encode-into-commit-message-shape-skill-aaron-2026-04-28.md
@@ -0,0 +1,101 @@
+---
+id: B-0069
+priority: P2
+slug: heredoc-patterns-encode-into-commit-message-shape-skill
+status: backlog
+created: 2026-04-28
+maintainer: aaron
+ownership: otto
+title: Encode HEREDOC patterns into commit-message-shape skill (Aaron 2026-04-28)
+---
+
+# B-0069 — Encode HEREDOC scripts into substrate
+
+## Why
+
+The human maintainer 2026-04-28 (verbatim, /btw aside during PR drain):
+
+> "does HEREDOC have scripts we should encode into substraight?"
+
+The factory uses a recurring `git commit -m "$(cat <<'EOF' ... EOF
+)"` HEREDOC pattern for commit messages and `gh pr create --body
+"$(cat <<'EOF' ... EOF
+)"` for PR bodies. These patterns have nuance that is currently
+tribal knowledge — should be encoded into
+`.claude/skills/commit-message-shape/SKILL.md` so future
+agents/contributors get the discipline at session-bootstrap, not
+discover it through trial-and-error.
+
+## Patterns worth encoding
+
+1. **Single-quoted EOF (`<<'EOF'`)** — prevents shell expansion of
+   backticks (`` ` ``), `$variables`, `$(command)` substitution, and
+   `\` escapes inside the body. Critical for commit messages /
+   PR bodies that contain literal backticks (markdown code spans),
+   dollar-prefixed identifiers (file paths, env vars), or shell
+   metacharacters. Unquoted `<<EOF` would break those.
+
+2. **Closing `EOF\n)"` form** — the trailing newline before the
+   closing `)` is what makes the HEREDOC parse correctly inside the
+   `$(...)` command substitution. Missing the newline produces a
+   shell parse error.
+
+3. **Trailer-block placement at end** — when the HEREDOC body ends
+   with an AgencySignature trailer block, the trailer block must be
+   the last lines of the body (per `git interpret-trailers` parser
+   rules: trailers are the last paragraph, separated from prose by
+   one blank line). Embedding trailer-shape lines mid-body breaks
+   the parser.
+
+4. **Co-authored-by line as final trailer** — the `Co-authored-by:`
+   line attributes the agent contribution; lives at end of trailer
+   block. Composes with the AgencySignature 7-trailer schema (per
+   task #298 + task #299 + Amara ferry-7 absorb at
+   `docs/research/2026-04-26-amara-fail-open-with-receipts-attribution-rule-7-trailer-schema.md`).
+
+5. **PR body HEREDOC vs commit message HEREDOC** — same shape,
+   different consumers. PR body has GitHub-flavor markdown (tables,
+   task lists `[ ]`, `🤖 Generated with [Claude Code]` footer);
+   commit message is plain text + trailer block. Both use
+   `<<'EOF'` / `EOF\n)"`.
+
+6. **Variable interpolation cases** — when HEREDOC body MUST include
+   a shell variable (commit SHA, run ID), use unquoted `<<EOF`
+   instead of `<<'EOF'`. This is rare; most cases stay
+   single-quoted. Per Aaron's framing, this is the "scripts
+   encoded into substrate" piece — knowing when to flip the
+   quoting discipline.
+
+7. **Backtick-in-trailer pitfalls** — backticks in trailer-block
+   text (e.g., `` Authority-Source: `docs/AGENT-BEST-PRACTICES.md` ``)
+   need single-quoted `<<'EOF'` to preserve literally; otherwise
+   the shell parses the backticks as command substitution.
+
+8. **Truncated heredoc end-marker rule** — closing `EOF` MUST be at
+   the start of its line (no leading whitespace). YAML files / nested
+   shell often add accidental indentation; that breaks the heredoc
+   close detection and makes the next 1000+ lines of script body part
+   of the heredoc.
+
+## Composition with existing substrate
+
+- `.claude/skills/commit-message-shape/SKILL.md` — the natural home
+- task #296 — "Integrate ferry-3 canonical commit-attribution
+  schema into commit-message-shape SKILL.md via skill-improver
+  workflow" — same skill update target; bundle B-0069 with task
+  #296 if the skill-improver workflow is already triggering
+- `memory/feedback_otto_354_*` — AgencySignature trailer-discipline
+  memory (operational status; refinement to v2 7-schema pending)
+- task #298 + task #299 — pre-merge validator + post-merge
+  auditor (already landed)
+
+## Cadence
+
+When skill-improver workflow next fires for the
+commit-message-shape SKILL — bundle this with task #296 to keep
+the changes coherent.
+
+## Provenance
+
+- Aaron 2026-04-28 verbatim (above)
+- Composition partner: task #296 (skill-improver workflow trigger)

From 650717483228033c81de51bda390e2b4e2e821e7 Mon Sep 17 00:00:00 2001
From: Aaron Stainback <aaron_bond@yahoo.com>
Date: Tue, 28 Apr 2026 03:14:29 -0400
Subject: [PATCH 2/2] fix(pr-85): align B-0069 frontmatter to backlog schema +
 replace dead xref with in-tree authoritative pointer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR #85 review threads addressed (3 of 3):

1. P1 copilot (line 8) — frontmatter diverged from the schema in
   tools/backlog/README.md:
   - status: backlog → status: open (the documented enum is
     open|closed|superseded-by-B-NNNN|deferred)
   - dropped non-schema fields slug, maintainer, ownership
   - added required last_updated: 2026-04-28
   - added optional ask: (maintainer Aaron 2026-04-28 /btw aside),
     effort: S, tags: per the schema
   Result: frontmatter now passes the schema spec in
   tools/backlog/README.md verbatim.

2. P2 codex (line 54) + 3. P1 copilot (line 54) — same finding:
   xref to docs/research/2026-04-26-amara-fail-open-with-receipts-
   attribution-rule-7-trailer-schema.md is a dead pointer because
   that file ships in PR #17 which hasn't landed yet. Replaced
   with a pointer at tools/hygiene/validate-agencysignature-pr-
   body.sh — the in-tree authoritative source for the
   AgencySignature schema (already landed via task #298). The
   substantive content (composition with the 7-trailer schema) is
   preserved; the broken path dependency is removed.

Sister-row note: B-0068, B-0070, B-0071 (all 2026-04-28 backlog
rows authored in parallel) likely have the same schema-divergence
shape. Same-shape fix tracked for follow-up sweep on the next pass
through the queue.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 ...mmit-message-shape-skill-aaron-2026-04-28.md | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/docs/backlog/P2/B-0069-heredoc-patterns-encode-into-commit-message-shape-skill-aaron-2026-04-28.md b/docs/backlog/P2/B-0069-heredoc-patterns-encode-into-commit-message-shape-skill-aaron-2026-04-28.md
index a1ab8a3ca..6fbee1f68 100644
--- a/docs/backlog/P2/B-0069-heredoc-patterns-encode-into-commit-message-shape-skill-aaron-2026-04-28.md
+++ b/docs/backlog/P2/B-0069-heredoc-patterns-encode-into-commit-message-shape-skill-aaron-2026-04-28.md
@@ -1,12 +1,13 @@
 ---
 id: B-0069
 priority: P2
-slug: heredoc-patterns-encode-into-commit-message-shape-skill
-status: backlog
-created: 2026-04-28
-maintainer: aaron
-ownership: otto
+status: open
 title: Encode HEREDOC patterns into commit-message-shape skill (Aaron 2026-04-28)
+effort: S
+ask: maintainer Aaron 2026-04-28 /btw aside
+created: 2026-04-28
+last_updated: 2026-04-28
+tags: [skill-substrate, commit-discipline, heredoc, agency-signature]
 ---
 
 # B-0069 — Encode HEREDOC scripts into substrate
@@ -50,8 +51,10 @@ discover it through trial-and-error.
 4. **Co-authored-by line as final trailer** — the `Co-authored-by:`
    line attributes the agent contribution; lives at end of trailer
    block. Composes with the AgencySignature 7-trailer schema (per
-   task #298 + task #299 + Amara ferry-7 absorb at
-   `docs/research/2026-04-26-amara-fail-open-with-receipts-attribution-rule-7-trailer-schema.md`).
+   task #298 (pre-merge validator landed) + task #299 (post-merge
+   auditor landed); the canonical schema is documented in
+   `tools/hygiene/validate-agencysignature-pr-body.sh` which is
+   already in-tree and authoritative).
 
 5. **PR body HEREDOC vs commit message HEREDOC** — same shape,
    different consumers. PR body has GitHub-flavor markdown (tables,