[shiplog/plan] Add 'Managed by shiplog' footer to envelope templates

[devallibus]

Context

When a fresh LLM session picks up work on an existing issue or PR, there is no visible signal in the artifact itself telling the reader "this item is managed by shiplog; load the skill before acting on it." The global CLAUDE.md in this repo already mandates checking shiplog before doing anything, and the skill auto-activates on phrases like "work on issue #N". That is enough in most sessions. It is not enough in two common failure modes:

1. Imported context. A subagent or external tool is handed an issue/PR excerpt with no surrounding conversation. The hidden HTML envelope (<!-- shiplog: ... -->) is often stripped by summarizers or invisible in body-only views, and the agent has no prompt-level cue that shiplog conventions apply.
2. Quiet-mode or partially-documented sessions. The operator forgets to invoke the skill explicitly, the auto-activation heuristics miss, and the agent proceeds with generic workflow defaults, producing unsigned commits or off-pattern review comments.

The proposal is a single, low-noise footer in the visible body of every shiplog envelope-template-based artifact (issue, PR, optionally timeline comments) that reads, for example:

Managed by shiplog. Load the shiplog skill before working this item.

This is a prompt for LLM consumers, yes, but it is primarily a documentation signal: it tells any human or tool reader which workflow owns this artifact and where the conventions live. That is why it goes in the body, not in prose inside each comment — one footer, one place, easy to grep, easy to keep terse.

Design Summary

• Add a short, bold "Managed by shiplog" footer to every shiplog envelope-template in skills/shiplog/references/phase-templates.md
• Keep the footer minimal (one or two sentences); this is a marker, not a prompt-injection surface
• Pair the marker with a one-line enhancement in the skill's auto-activation rules so the marker reinforces (rather than duplicates) the existing global CLAUDE.md mandate
• Keep the hidden HTML envelope as the authoritative machine signal; this footer is the visible, human-and-LLM-aware complement

Approach

Update skills/shiplog/references/phase-templates.md so that every template that produces a top-level artifact body (issue envelope, PR envelope, and any multi-comment templates the reference documents) ends with a standard footer block. Example:

---

_Managed by **shiplog**. Load the **shiplog** skill before working on this item; see `skills/shiplog/SKILL.md`._

Update skills/shiplog/SKILL.md "When This Skill Activates" section to add one bullet: "Auto-activate when an issue or PR body carries a Managed by **shiplog** footer." This keeps the auto-activation rule in one place and prevents the marker from becoming a dead decoration.

No change to the envelope schema in artifact-envelopes.md; the marker is prose, not metadata.

Alternatives Considered

• Imperative directive ("you MUST follow shiplog"): rejected. Noisy, unreliable (LLMs comply inconsistently with imperative prose), and can read as prompt-injection framing to security-conscious reviewers.
• Only a hidden HTML marker: rejected. The hidden envelope is already there (<!-- shiplog: ... -->) and it fails exactly when body-only summarization strips HTML comments, which is the failure mode this marker is meant to cover.
• Put the marker in every timeline comment: considered optional. Overkill for short discovery/implementation-issue comments. Start with issue and PR envelopes; extend later if experience justifies it.

Tasks

• T1: Define the canonical footer [tier-1]

  • What: Specify the exact footer text and placement, with the brand-formatting rule (lowercase bold shiplog) already in SKILL.md.
  • Files: skills/shiplog/references/phase-templates.md (modify)
  • Allowed to change: Template examples and the accompanying commentary.
  • Must not change: The envelope schema, existing section headings, or non-shiplog template content.
  • Forbidden judgment calls: Do not turn the footer into an imperative "you must" block or into a prompt-injection surface; keep it a short attribution + pointer.
  • Verification: Read the updated templates and confirm every issue/PR envelope template ends with the footer.

• T2: Add the footer to all issue and PR envelope templates [tier-2]

  • What: Apply the footer to each template in phase-templates.md that renders a top-level issue or PR body.
  • Files: skills/shiplog/references/phase-templates.md (modify); any mirroring template excerpts in skills/shiplog/SKILL.md if they show a full envelope
  • Allowed to change: Template bodies only.
  • Must not change: Semantic-tag conventions, envelope schema, or existing task/section formats.
  • Forbidden judgment calls: Do not retrofit the footer onto existing open issues/PRs unprompted; templates apply to newly authored artifacts.
  • Verification: Grep the reference file; every ## Issue Envelope / ## PR Envelope example ends with the footer block.

• T3: Wire the footer into auto-activation [tier-1]

  • What: Add one bullet to the "Auto-activate when ANY of these occur" list in skills/shiplog/SKILL.md that treats a visible "Managed by shiplog" footer as an activation trigger, so the marker has an enforced, documented consequence.
  • Files: skills/shiplog/SKILL.md (modify)
  • Allowed to change: The auto-activation bullet list only.
  • Must not change: The "Do NOT auto-activate for" list or any other section.
  • Forbidden judgment calls: Do not add CLAUDE.md-level or settings-level enforcement in this issue; this is skill-level scope.
  • Verification: The SKILL.md auto-activation list includes the footer-based trigger.

Provenance

Authored-by: claude/opus-4.7 (claude-code)

[devallibus]

Related: #140 (hunt query), #141 (Reviews index line). This issue covers the cross-entry-point marker; #141 covers the per-PR review index.

[devallibus]

Referenced from #143 (simplification meta-plan): the Managed-by shiplog footer fits naturally into L6 (golden-path walkthrough) if that lever is adopted.

[devallibus]

[shiplog/amendment] Referenced by simplification meta-plan

Parent: #143. Workstream E (#147) section 4 of the target SKILL.md outline wires the "Managed by shiplog" footer from this issue into the auto-activation trigger list.

Authored-by: claude/opus-4.7 (claude-code)