refactor(#146): co-locate policy+query+checklist across sub-skills (closes #140)#151
refactor(#146): co-locate policy+query+checklist across sub-skills (closes #140)#151devallibus merged 8 commits intomasterfrom
Conversation
… detection (closes #140) Reshapes commands/shiplog/hunt.md to the canonical 3-section shape (Policy / Query-Template / Acceptance Checklist) and folds in #140 T1-T3: - Policy: signed review = comment with Reviewed-by: + Disposition: lines; reviewDecision/reviews fields are advisory only - Query: extended probe fetches gh pr view <N> --json comments per PR; signed-review detection scans comment bodies for both lines - Classification: PR with valid signed approve comment goes to approved bucket, not needs-review bucket - Cross-link: policy pointer to closure-and-review.md §3 in preamble and Policy - Checklist: 6 items covering comment fetch, correct bucket placement, cross-model gate check using resolved last-code-author Closes #140 Authored-by: claude/sonnet-4.6 (claude-code)
Canonical 3-section shape (Policy / Query-Template / Acceptance Checklist). - Policy: when to create a planning issue, envelope requirements, triage field derivation rule (pointer to artifact-envelopes.md §1), label-at-creation rule - Query/Template: label bootstrap snippet, gh issue create command, full planning issue body template with pre-filled Authored-by sig block - Checklist: 6 items covering envelope validity, max_tier derivation, task fields, label, sig, and unverified-claim annotation Authored-by: claude/sonnet-4.6 (claude-code)
Canonical 3-section shape (Policy / Query-Template / Acceptance Checklist). - Policy: branch naming convention (issue/<id>-<slug>), branch base must be default branch tip, label swap rule (shiplog/ready -> shiplog/in-progress), envelope readiness update, session-start comment requirement - Query/Template: fetch issue command, worktree + fallback branch commands, label swap commands, session-start comment template with Authored-by sig - Checklist: 6 items covering branch name, base, label swap, envelope update, session-start posted with unchecked task list Note: file was renamed via git mv to work around a Windows file-lock (another process had start.md open); the rename was resolved in the same commit. Authored-by: claude/sonnet-4.6 (claude-code)
Canonical 3-section shape (Policy / Query-Template / Acceptance Checklist). - Policy: commit message format (<type>(#<id>): <msg> and <type>(#<id>/<Tn>): <msg>), Authored-by: sig required in commit body, when to post commit-note comment, staging hygiene (specific files, no --no-verify) - Query/Template: temp-file + git commit -F pattern, commit message template with pre-filled Authored-by sig, commit-note comment template, git log --grep retrieval - Checklist: 6 items covering format, sig, staging, no-verify, commit-note, hash shown Authored-by: claude/sonnet-4.6 (claude-code)
Canonical 3-section shape (Policy / Query-Template / Acceptance Checklist). - Policy: PR body mandatory sections (envelope, summary, Closes, timeline, verification, reviews placeholder, sig blocks); both Authored-by: and Last-code-by: required; review gate pointer to review.md (no duplication of gate policy); partial delivery uses Addresses #<N> not Closes #<N> - Query/Template: git push + gh pr create command, full PR body template with pre-filled sig block, label transition command - Checklist: 6 items covering envelope, Closes line, timeline, sig blocks, review placeholder, label transition #141 gracefully degraded: no Reviews-index line added; reviews placeholder section references review.md for review sub-skill instead. Authored-by: claude/sonnet-4.6 (claude-code)
…-and-review.md New file: commands/shiplog/review.md with canonical 3-section shape: - Policy: 4-field sign-off requirement, cross-model gate pointer (to closure-and-review.md §3), approve-with-follow-ups precondition, default publication rule, snapshot follow-through - Query/Template: check PR code author command, gh pr diff + view, review sign-off comment template (with envelope), self-review template, PR body snapshot update commands - Checklist: 6 items covering cross-model check, diff read, follow-up issue pre-creation, publication, snapshot update, Follow-ups field validity Trim: closure-and-review.md §3 sign-off format section and §4 Review Execution Ladder shrunk to policy anchor + cross-cutting GitHub API constraint. All runbook content (templates, dispatch steps, self-review format, publication rules) relocated to review.md. Cross-model gate rule, what-constitutes-different- model definition, merge conditions (§5), and closure evidence rules all retained. Authored-by: claude/sonnet-4.6 (claude-code)
Both files reshaped to canonical 3-section shape (Policy / Query-Template / Acceptance Checklist). lookup.md: - Policy: ID-first retrieval (issue number as primary key), multi-surface search requirement (issues + PRs + git log), envelope-first reading, deep dive on request only - Query/Template: by issue number (ID-first), by keyword, by shiplog tag, envelope-only read via jq, lookup report format - Checklist: 5 items covering both gh surfaces, git log, compact-first output, envelope fields noted, ork:memory queried if available resume.md: - Policy: branch detection from issue/<id>-<slug>, session-resume comment requirement (distinct from session-start), triage field sync, open blocker surfacing - Query/Template: branch parse, gh issue view, linked PR check, session-resume comment template with Authored-by sig, git log --grep for prior commits - Checklist: 6 items covering issue detection, task status current, blockers surfaced, resume comment posted, triage sync, next task by tier Authored-by: claude/sonnet-4.6 (claude-code)
…-skills Integration Map restructured into three tables: 1. Sub-skill map — each phase pointing to its commands/shiplog/<phase>.md file 2. Cross-cutting reference anchors — what stays in references/ and why 3. External skill delegation — updated to point to sub-skill files as primary Requirements section updated: - "Internalized Workflows" table replaced with "Co-located Sub-skills" table listing all 8 phase files - New "Internalized Reference Workflows" table for references/ deep-dive files No changes to auto-activation rules, core principle, kind map, signing spec, triage maintenance table, or edge cases. Pointer updates only per T8 scope. Authored-by: claude/sonnet-4.6 (claude-code)
devallibus
added
shiplog/history
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 307e2fc6ab
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| gh label create "shiplog/plan" --color "0B7285" --description "Brainstorm captured as a planning issue" --force | ||
| gh label create "shiplog/ready" --color "2DA44E" --description "Ready to implement" --force | ||
| gh label create "shiplog/in-progress" --color "FBCA04" --description "Implementation in progress" --force | ||
| gh label create "shiplog/needs-review" --color "D93F0B" --description "Awaiting review" --force |
There was a problem hiding this comment.
shiplog/discovery to Phase 1 label bootstrap
The Phase 1 bootstrap list no longer creates shiplog/discovery, but the discovery flow still creates issues with --label "shiplog/discovery" (see skills/shiplog/discovery.md). In a repo initialized from this updated bootstrap, discovery handling will fail when it tries to apply a label that was never created, which blocks a core Phase 3 path; add shiplog/discovery back (or reuse the canonical full bootstrap from references/labels.md).
Useful? React with 👍 / 👎.
| gh pr comment <N> --body-file <temp-file> | ||
| ``` |
There was a problem hiding this comment.
This command requires temp files for required steps (gh pr comment --body-file <temp-file> and gh pr edit --body-file <updated-body-file>), but its frontmatter only allows Bash(gh:*), Bash(git:*), Read and omits Write. In environments that enforce allowed-tools, the reviewer cannot create those files, so publication and snapshot update—the two mandatory completion steps in this file—become non-executable.
Useful? React with 👍 / 👎.
| Write to a temp file and use `git commit -F`: | ||
|
|
||
| **Commit types:** `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `style`, `perf`. | ||
| ``` | ||
| <type>(#<issue-id>/<Tn>): <description> |
There was a problem hiding this comment.
The commit flow now explicitly depends on temp files (git commit -F <temp-file> and later gh issue comment ... --body-file), but this command still omits Write from allowed-tools. Under enforced tool permissions, that blocks the documented happy path for composing multiline commit messages and commit-note artifacts, so the command cannot reliably execute its own template.
Useful? React with 👍 / 👎.
[shiplog/review-handoff] #146: Review of PR #151Reviewer: claude/opus-4.7 (claude-code) — cross-model review of a sonnet-4.6 author What was reviewed
FindingsDisposition: approve — no blockers.
Notes for follow-on workstreams
One-line-edit check
Reviewed-by: claude/opus-4.7 (claude-code) |
Backfills cumulative drift since the implicit 0.1.0 baseline (PR #84, 2026-03-15). Five MINOR-worthy phases shipped without bumps; classifying them per semver lands at 0.5.0. Stays on 0.x — surface is still mobile (Quiet Mode just removed, vocabulary just rewritten). This unblocks downstream consumers: Claude Code's plugin cache and npx skills add both key on this version string. Existing 0.1.0 caches will refresh on next install and finally pick up the post-#151 hunt fix from #140 (and everything else that has merged since 2026-03-15). T1 of #156. T2 (CONTRIBUTING policy), T3 (CI bump-check), T4 (release workflow) follow as separate PRs. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 participant
[rtk] /!\ No hook installed — run
rtk init -gfor automatic token savingsSummary
commands/shiplog/<phase>.mdsub-skill file so LLMs can execute any phase from a single file without cross-file navigationhunt.mdto fetch PR comments and detect signedReviewed-by:+Disposition:lines, so PRs with comment-based reviews are correctly classified instead of appearing in the needs-review bucketclosure-and-review.mdto its cross-model gate policy anchor; runbook content moves to newcommands/shiplog/review.mdCloses #146
Closes #140
Tasks Completed
T1: hunt.md (folds in #140 T1–T3)
commands/shiplog/hunt.mdreshaped to canonical 3-section shapeReviewed-by:+Disposition:, notreviewDecision/reviewsfieldsgh pr view <N> --json commentsfetch; signed-review detection scans comment bodiesclosure-and-review.md§3T2: plan.md
commands/shiplog/plan.mdreshapedgh issue createcommand, full planning issue body template withAuthored-by:sigT3: start.md
commands/shiplog/start.mdreshapedT4: commit.md
commands/shiplog/commit.mdreshaped<type>(#<id>): <msg>format,Authored-by:in commit body, when to post commit-notegit commit -Fpattern, commit message + commit-note templatesT5: pr.md
commands/shiplog/pr.mdreshapedreview.mdreview.md, no Reviews-index lineT6: review.md (new file) + closure-and-review.md trim
commands/shiplog/review.md— policy, sign-off template, self-review template, PR snapshot updateclosure-and-review.md§3 sign-off runbook →review.md; §4 execution ladder → pointer + GitHub API constraint anchorT7: lookup.md + resume.md
commands/shiplog/lookup.md: ID-first retrieval, multi-surface search, compact report formatcommands/shiplog/resume.md: branch detection, session-resume comment template, blocker surfacingT8: SKILL.md Integration Map
Verification
hunt.mdhas exactly 3 top-level sections (Policy / Query+Template / Acceptance Checklist)hunt.mdfetchesgh pr view <N> --json commentsper PR before classifying review statusreview.mdcreated; an LLM can do a full PR review from it plus one jump toclosure-and-review.md§3closure-and-review.mdretains cross-model gate policy, merge conditions, closure evidence rulesJourney Timeline
Initial Plan
Issue #146 called for co-locating policy+query+checklist across all 8 sub-skill files, with #140 (hunt.md comment-probe fix) folded into T1.
What We Discovered
Windows file-locking (implementation issue): Several files in
commands/shiplog/were locked by another process (likely another Claude Code session or editor).start.md,commit.md,pr.md,lookup.md, andresume.mdall returnedEUNKNOWNon Write andPermission deniedoncp. Resolved by usinggit mv <file> <file>.bakto rename the locked file, then creating a fresh file at the original path, then removing the.bakin the same commit. No data was lost.Key Decisions
hunt.md; sequential edits in separate PRs create merge sequencing riskclosure-and-review.md§3, not inreview.mdreview.md; keeping them in both files recreates the desync problem this PR fixespr.mdreferencesreview.mdwithout speculating on #141's shapeChanges Made
03dd3ca— refactor([shiplog/plan] Co-locate policy + query + checklist across all shiplog sub-skills #146/T1): co-locate hunt.md with proper comment-based review detection (closes [shiplog/plan] Hunt command misses comment-based signed reviews #140)40bb85e— refactor([shiplog/plan] Co-locate policy + query + checklist across all shiplog sub-skills #146/T2): co-locate plan.md2d39182— refactor([shiplog/plan] Co-locate policy + query + checklist across all shiplog sub-skills #146/T3): co-locate start.md8a23461— refactor([shiplog/plan] Co-locate policy + query + checklist across all shiplog sub-skills #146/T4): co-locate commit.md439f4ec— refactor([shiplog/plan] Co-locate policy + query + checklist across all shiplog sub-skills #146/T5): co-locate pr.md2f82785— refactor([shiplog/plan] Co-locate policy + query + checklist across all shiplog sub-skills #146/T6): create commands/shiplog/review.md and trim closure-and-review.mdcc9cd77— refactor([shiplog/plan] Co-locate policy + query + checklist across all shiplog sub-skills #146/T7): co-locate lookup.md and resume.md307e2fc— refactor([shiplog/plan] Co-locate policy + query + checklist across all shiplog sub-skills #146/T8): update SKILL.md integration map for co-located sub-skillsReviews
Current state: approved
Last reviewed by: claude/opus-4.7 (claude-code)
Last reviewed at: 2026-04-18T14:30:00Z
Reviewed commit: 307e2fc
Source artifact: #151 (comment)
Needs re-review since: —
Authored-by: claude/sonnet-4.6 (claude-code)
Last-code-by: claude/sonnet-4.6 (claude-code)
Captain's log — PR timeline by shiplog