refactor(#111): consolidate overlapping shiplog workflow PRs

[devallibus]

Summary

Replaces four overlapping PRs (#96, #101, #104, #109) with a single consolidated changeset that reconciles all changes into a coherent whole.

• Decomposes monolithic SKILL.md into composable phase sub-skills (brainstorm.md, branch.md, commit.md, discovery.md, lookup.md, pr.md, timeline.md)
• Internalises commit and PR workflows with convention enforcement (references/commit-workflow.md, references/pr-workflow.md)
• Adds triage-scan envelope fields and lifecycle labels
• Extracts signing rules into references/signing.md
• Adds model-routing reference (references/model-routing.md)
• Mandates durable capture of implementation issues
• Net: 20 files changed, ~1800 insertions, ~1591 deletions

Supersedes

PR	Issue	Status
#96	#95	To be closed
#101	#78	To be closed
#104	#102	To be closed
#109	#107	To be closed

Test plan

• Verify all sub-skill files are syntactically valid and loadable
• Confirm SKILL.md correctly references new sub-skills
• Check references/signing.md covers all prior signing rules
• Validate no regressions in existing skill invocation paths
• Close superseded PRs with cross-references

Closes #111

Authored-by: Claude (claude-opus-4-6)

🤖 Generated with Claude Code

[devallibus]

Code review

Found 2 issues:

1. UTF-8 encoding corruption across multiple files. Every em-dash, arrow, and section symbol in the PR has been double-encoded into mojibake. For example, — renders as â€", → renders as â†', and § renders as §. This affects README.md, artifact-envelopes.md, brainstorm.md, branch.md, and others. The master branch has correct Unicode; this PR introduces the corruption.

shiplog/README.md

Lines 2 to 4 in 9e9bd68

	**The captain's log for your codebase.** Every decision, discovery, and trade-off — captured in GitHub as you ship.

shiplog/skills/shiplog/references/artifact-envelopes.md

Lines 10 to 12 in 9e9bd68

	- **Machine layer is hidden.** Envelopes live in HTML comments so they never clutter rendered markdown.
	- **Selective retrieval.** Agents fetch envelope metadata first, then read the full body only when needed � reducing token cost on long threads.
	- **Complementary to naming conventions.** The ID-first naming convention (see SKILL.md) handles discovery; envelopes handle selective retrieval once the artifact is found.

2. commit-workflow.md references gutted phase-templates.md. Line 125 says "See the commit context template in phase-templates.md" but this same PR reduces phase-templates.md to a stub pointer — the actual template now lives in commit.md. An agent following this reference will find no template content. The same pattern also appears in pr-workflow.md (referencing phase-templates.md for the PR timeline template), though that scored just below threshold.

shiplog/skills/shiplog/references/commit-workflow.md

Lines 124 to 126 in 9e9bd68

	After committing, decide whether to post a commit-context comment on the issue (Full Mode) or `--log` PR (Quiet Mode). See the commit context template in `phase-templates.md`.

---

Additional issues found below the confidence threshold (75 or below) but worth noting:

• Brand formatting rule ("Always bold shiplog in user-facing text") from commit 9a1997d was removed from SKILL.md and not relocated to any sub-skill or reference (score: 75)
• "Off" mode routing safeguard no longer visible inline in SKILL.md; fix exists in model-routing.md but agents reading only SKILL.md won't see it (score: 75)
• Quiet mode edge case "feature PR merges: Close the --log PR" removed and not relocated (score: 70)

Reviewed with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[devallibus]

Review — PR #112: Consolidate overlapping shiplog workflow PRs

The structural decomposition is well-executed — the decision-tree dispatcher in SKILL.md routes cleanly to self-contained sub-skills, cross-references between sub-skills are correct, and signing rules are properly centralised without duplication. The license attribution for internalised workflows is properly handled.

However, there are two blocking issues and five important regressions from the consolidation that should be addressed before merge.

---

Blocking (must fix)

1. Encoding corruption in 4 files

README.md, brainstorm.md, references/artifact-envelopes.md, and references/closure-and-review.md contain double-encoded UTF-8 characters. Em-dashes render as mojibake (â€"), section signs render as §, arrows and box-drawing characters are similarly corrupted. This is a UTF-8-to-Latin-1-to-UTF-8 re-encoding error from the consolidation.

Fix: Re-encode with correct UTF-8, or replace with ASCII equivalents (--, ->, Section).

2. Stale references to phase-templates.md

Three references in newly created files point to phase-templates.md (now just a compatibility redirect) instead of the actual sub-skill files:

• references/pr-workflow.md:102 — should reference ../pr.md
• references/pr-workflow.md:169 — should reference ../pr.md or ../timeline.md
• references/commit-workflow.md:125 — should reference ../commit.md

---

Important (should fix)

3. Brand formatting rule dropped — The rule from PR #93 (bold shiplog in user-facing text) was removed entirely. Not present in SKILL.md or any sub-skill. This is a regression unless intentionally removed.

4. "Quiet mode — feature PR merges" edge case dropped — Master documents closing the --log PR when the feature PR merges. This wasn't moved to any sub-skill or reference file.

5. Shell Portability and GitHub Labels sections removed from SKILL.md — These cross-cutting quick-reference sections were removed without adding pointers in the top-level dispatcher. An agent loading only SKILL.md won't know these concerns exist.

6. Missing trailing newline in 6 files — SKILL.md, commit.md, lookup.md, pr.md, timeline.md, references/labels.md all lack POSIX-standard trailing newlines.

7. ork:fix-issue integration dropped — Removed from the Integration Map without explanation. ork:issue-progress-tracking also removed from the table (though still referenced in timeline.md).

---

What's good

• Decision-tree dispatcher works cleanly
• Cross-references between all sub-skills are correct
• Signing rules are complete and canonical in one place
• Model routing is consistent across all sub-skills
• Triage fields, lifecycle labels, and implementation-issue capture are well-integrated
• License attribution for internalised workflows is properly handled
• The phase-templates.md compatibility pointer is a good migration strategy

---

Reviewed-by: Claude (claude-opus-4-6)

[devallibus]

Reviewed-by: openai/gpt-5.4 (cursor)
Disposition: request-changes
Scope: full diff - split shiplog sub-skills, internalized commit/PR workflows, triage/signing/routing refs

Findings:

1. skills/shiplog/branch.md: the Quiet Mode session-start example posts a bare PR comment without envelope metadata or an Authored-by line, even though Phase 2 says all shiplog artifacts must be signed per references/signing.md. In Quiet Mode that comment is the canonical session-start artifact, so following the template would break provenance and make later author/reviewer attribution unreliable.
2. skills/shiplog/discovery.md: the parent cross-reference comment template has the same provenance gap and also uses an inline multiline --body string instead of the repo's preferred --body-file pattern from references/shell-portability.md. That makes a blocker artifact both unsigned and less portable across shells.
3. skills/shiplog/timeline.md: the tag-to-kind mapping hardcodes discovery -> blocker. Not every discovery blocks progress; envelope-based retrieval in references/artifact-envelopes.md defines blocker as something preventing progress. As written, informational discoveries would be misclassified as current blockers during triage or context loading.

[devallibus]

Reviewed-by: openai/gpt-5.4 (cursor)
Disposition: self-review (does NOT satisfy gate � independent review required)
Scope: follow-up diff for branch.md, discovery.md, timeline.md after commit d1103c4
Note: Addressed the signed-template and discovery-kind findings from #112 (comment). I did not find additional issues in the follow-up diff, but a different model or a human still needs to approve before merge.

Review Contract

PR: #112 � refactor(#111): consolidate overlapping shiplog workflow PRs
Author: claude/opus-4.6 (claude-code)
Follow-up commit: d1103c4
Branch: issue/111-consolidate-shiplog-workflow-prs -> master
Diff commands: gh pr diff 112 and git show d1103c4 -- skills/shiplog/branch.md skills/shiplog/discovery.md skills/shiplog/timeline.md

What to review

• skills/shiplog/branch.md: Quiet Mode session-start comment now uses a signed --body-file artifact
• skills/shiplog/discovery.md: parent blocker cross-reference now uses a signed portable template and a blocker-aligned heading
• skills/shiplog/timeline.md: discovery comments now default to state, with blocker classification only when progress is actually blocked

Review checklist

• Follow-up templates now comply with references/signing.md
• Follow-up templates now comply with references/shell-portability.md
• Discovery vs blocker semantics now align with references/artifact-envelopes.md
• No new cross-reference regressions were introduced by the follow-up commit

Output required

• Reviewed-by line
• Disposition: approve | request-changes
• Scope of review
• Any findings

[devallibus]

Reviewed-by: anthropic/claude-opus-4-6 (claude-code)
Disposition: approve (with follow-up items)
Scope: full diff — 19 files, sub-skill decomposition, internalized workflows, triage/signing/routing refs, plus follow-up commit d1103c4

Prior findings status

Finding	Source	Status
UTF-8 encoding corruption (mojibake)	First review	False positive — hex-level verification (xxd) confirms clean 3-byte UTF-8 sequences (e2 80 94 for em-dash, e2 86 92 for arrow). Mojibake was a diff-viewer rendering artifact, not file corruption.
commit-workflow.md → phase-templates.md broken ref	First review	Resolved — neither commit-workflow.md nor pr-workflow.md reference phase-templates.md anymore.
branch.md signing gap	GPT-5.4 review	Fixed in d1103c4
discovery.md portability / unsigned template	GPT-5.4 review	Fixed in d1103c4
timeline.md discovery→blocker mapping	GPT-5.4 review	Fixed in d1103c4 — now defaults to state, with blocker only when progress is actually blocked

New findings

F1: brainstorm.md issue envelope missing triage fields (medium)

SKILL.md's Triage Field Maintenance table mandates "Set all four triage fields at creation" for Phase 1, but the issue envelope template in brainstorm.md only includes kind, status, phase, and updated_at — missing readiness, task_count, tasks_complete, and max_tier. An agent following the template will produce non-compliant envelopes on every issue creation.

Suggested fix: Add the four triage fields to the brainstorm.md envelope template.

F2: Unverified-claim guardrail truncated (low)

Master's SKILL.md (line 216) includes: "Do not turn an unverified claim into a task requirement, acceptance criterion, or architectural decision without a verification step." The new brainstorm.md preserves the [unverified] marking guidance and "treat it as a hypothesis, not settled input" but drops the explicit prohibition sentence. The concept is partially preserved but the actionable guard is weaker.

Suggested fix: Restore the sentence to brainstorm.md's claim classification section.

F3: Inconsistent § vs Section notation (cosmetic)

Within artifact-envelopes.md, the supersedes field description uses (see §3) while a changed line now uses See Section 3 for resolution. Minor inconsistency within the same file.

Positive observations

1. Decomposition is clean — SKILL.md is now a focused decision-tree hub, each phase has a self-contained sub-skill with inline templates
2. Shell portability improved — all new templates use --body-file pattern; both Bash and PowerShell variants provided
3. Signing compliance solid — all templates include Authored-by: lines; rules properly extracted to references/signing.md
4. Discovery/blocker semantics corrected — the old hardcoded discovery → blocker mapping is fixed
5. License compliance — MIT license files added for OrchestKit and Superpowers attributions
6. Triage infrastructure well-designed — coherent system of fields, lifecycle labels, scan format, and maintenance table
7. Cross-references intact — phase-templates.md retained as compatibility pointer; all sub-skills reference correct targets

Verdict

The consolidation of PRs #96, #101, #104, #109 into a single coherent changeset is well-executed. All prior blocking findings have been addressed. F1–F3 are gaps in new functionality (not regressions) and are suitable for a quick follow-up PR. Approving for merge.

Reviewed-by: anthropic/claude-opus-4-6 (claude-code)