Claude Custom

Verdict: APPROVED

Re-review of board item #1617 after refinement. Previous review: review-1617-2026-06-26 (NEEDS_REFINEMENT). All three issues from the prior review have been resolved.

Previous Issues — Resolution

• [x] MEMORY.md missing from File Targets — FIXED. MEMORY.md now listed in File Targets with correct description ("correct sprint status terminology").
• [x] story:sprint-planning label mismatch — FIXED. Label changed to story:sprint-orchestration, which matches the existing user story on project-claude-custom.
• [x] arch:memory label missing note — FIXED. Label changed to arch:docs, backed by the existing arch-docs-claude-custom architecture note.

Template Completeness

• [x] Type — Feature
• [x] Lineage — present (project: claude-custom, Sprint 5 origin)
• [x] Repo — ldraney/claude-custom
• [x] User Story — present
• [x] Context — present, well-written with concrete Sprint 5 failure evidence
• [x] File Targets — present (2 files)
• [x] Feature Flag — None (appropriate for memory file update)
• [x] Acceptance Criteria — present (5 items)
• [x] Test Expectations — present (manual verification)
• [x] Constraints — present (2 constraints)
• [x] Checklist — present
• [x] Related — present

Traceability

• [x] story:sprint-orchestration label — matches user story on project-claude-custom
• [x] story note verified — found in project-claude-custom user-stories section (heading "sprint-orchestration", paragraph describes orchestrating sprints as cross-project waves)
• [x] arch:docs label — docs architecture component
• [x] arch note verified — arch-docs-claude-custom note exists in pal-e-docs (note_type: architecture, status: active)
• [x] Forgejo issue — #290, open, valid URL

File Targets

• [x] ~/.claude/projects/-home-ldraney-claude-custom/memory/feedback_sprint-philosophy.md — verified: file exists (28 lines). Currently defines what a sprint IS (parallel, scope-based, no internal deps) but has no Definition of Done section. Correct target for the change.
• [x] ~/.claude/projects/-home-ldraney-claude-custom/memory/MEMORY.md — verified: file exists (90 lines). Contains sprint entries. Sprint 5 already uses "IN VALIDATION" (line 13), but Sprints 2-4 still use "DONE" in their headers (lines 33, 46, 56). Correct target for terminology updates.

Repo Placement

OK. Issue filed on ldraney/claude-custom, targets memory files in ~/.claude/projects/-home-ldraney-claude-custom/memory/. Correct repo. Single-repo change.

Dependencies

No blocking dependencies. Board item #1617 is independent. Related items on the board:

• #280 (Sprint SOP — codify cross-project wave concept) is in_progress — complementary but independent. Sprint SOP defines sprint mechanics; this ticket defines sprint done criteria.
• #275 (Dictionary definitions) is in_progress — could define "done" but this ticket is specifically about sprint done criteria in memory, not dictionary.

No undocumented dependencies.

Acceptance Criteria

5 ACs — all agent-verifiable for a 1-point memory file update:

• AC 1-3: Verified by reading updated feedback_sprint-philosophy.md for new Definition of Done section and corollaries.
• AC 4: Verified by checking for cross-reference to sop-board-workflow validation/done column definitions.
• AC 5: Verified by reading MEMORY.md sprint status entries for correct terminology.

No missing criteria detected.

Blast Radius

Low. Changes are confined to memory files which are session-context only. No hooks, scripts, or code reference these files programmatically. Other memory files in sibling projects (project_paldocs-consolidation.md, project_sprint-1-tickets.md) also reference sprint status with "done" but those are in different project contexts and not in scope for this ticket. No downstream consumers affected.

Decomposition Assessment

2 file targets, 1 repo, 5 ACs. Estimated agent work well under 5 minutes — this is a documentation/memory update. No decomposition needed.

Recommendation

No action needed. All three issues from the prior review have been resolved. Ticket is ready for development.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Feature
• [x] Lineage — present
• [x] Repo — ldraney/claude-custom
• [x] User Story — present
• [x] Context — present, well-written with concrete Sprint 5 failure evidence
• [x] File Targets — present (1 file)
• [x] Feature Flag — None (appropriate for memory file update)
• [x] Acceptance Criteria — present (5 items)
• [x] Test Expectations — present (manual verification)
• [x] Constraints — present (2 constraints)
• [x] Checklist — present
• [x] Related — present

Traceability

• [ ] story:sprint-planning label — MISMATCH: The project page (project-claude-custom) has a sprint-orchestration user story but no sprint-planning story. The board item uses story:sprint-planning which has no backing entry. [SCOPE] Either create a sprint-planning user story entry on project-claude-custom, or change the label to story:sprint-orchestration (sprint done criteria is arguably part of sprint orchestration).
• [ ] arch:memory label — MISSING NOTE: No arch-memory architecture note found in pal-e-docs. [SCOPE] Create architecture note arch-memory for the memory component, or change to an existing arch label that fits.
• [x] Forgejo issue — #290, open, valid URL

File Targets

• [x] ~/.claude/projects/-home-ldraney-claude-custom/memory/feedback_sprint-philosophy.md — verified: file exists (28 lines). Currently defines what a sprint IS (parallel, scope-based, no internal deps) but has no Definition of Done section. Correct target for the change.
• [ ] MEMORY.md — ISSUE: AC #5 says "Update MEMORY.md sprint status entries to use 'IN VALIDATION' instead of 'DONE'" but MEMORY.md is not listed in File Targets. Verified that MEMORY.md exists and contains sprint entries marked "DONE" on lines 46, 56. [BODY] Add MEMORY.md to File Targets section.

Repo Placement

OK. Issue filed on ldraney/claude-custom, targets memory files in ~/.claude/projects/-home-ldraney-claude-custom/memory/. Correct repo.

Dependencies

No blocking dependencies found. Board item #1617 is independent. Related items on the board:

• #280 (Sprint SOP — codify cross-project wave concept) is in_progress — related but not blocking. The sprint SOP defines sprint mechanics; this ticket defines sprint done criteria. They are complementary but independent.
• #275 (Dictionary definitions) is in_progress — could define "done" but this ticket is specifically about sprint done criteria in memory, not dictionary.

No undocumented dependencies.

Acceptance Criteria

5 ACs — right at the decomposition threshold but appropriate for a 1-point memory file update. All are verifiable:

• AC 1-3: Can be verified by reading the updated feedback_sprint-philosophy.md for the new section and corollaries.
• AC 4: Can be verified by checking for cross-reference to sop-board-workflow.
• AC 5: Can be verified by reading MEMORY.md sprint status entries for correct terminology.

All ACs are agent-verifiable. No missing criteria detected.

Blast Radius

Low. Changes are confined to memory files which are session-context only. No hooks, scripts, or code reference these files programmatically. The sprint done definition may influence future sprint status tracking in MEMORY.md, but that is the stated intent. No sibling services affected.

Decomposition Assessment

1 file target (+1 missing from File Targets), 5 ACs, 1 repo. Estimated agent work well under 5 minutes — this is a documentation/memory update. No decomposition needed.

Recommendation

• [BODY] Add MEMORY.md to File Targets: ~/.claude/projects/-home-ldraney-claude-custom/memory/MEMORY.md — update sprint status entries from "DONE" to "IN VALIDATION" where applicable.
• [LABEL] Change story:sprint-planning to story:sprint-orchestration on board item #1617 (sprint-orchestration story already exists on project-claude-custom; sprint-planning does not).
• [SCOPE] Create architecture note arch-memory for the memory component in pal-e-docs, OR change the arch:memory label to an existing arch component that fits.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- story: sprint-orchestration | arch: docs
• [x] Repo -- claude-custom, pal-e-docs, paldocs
• [x] User Story -- present, well-written
• [x] Context -- clear motivation and background
• [x] File Targets -- 9 targets across 3 repos, tabular format
• [x] Feature Flag -- "None" with rationale (schema change)
• [x] Acceptance Criteria -- 6 criteria
• [x] Test Expectations -- present for both repos
• [x] Constraints -- 3 constraints documented
• [x] Checklist -- 7 items
• [x] Related -- 4 related issues + note-conventions reference

All required feature template sections are present.

Traceability

• [x] story:sprint-orchestration label -- present on board item
• [ ] story note MISSING -- project-claude-custom user-stories section only contains "operational-reference". No "sprint-orchestration" entry exists. [SCOPE] Create user story entry "sprint-orchestration" on project-claude-custom user-stories section.
• [x] arch:docs label -- present on board item
• [ ] arch note MISSING -- searched pal-e-docs for "arch-docs" and "arch-docs-claude-custom" -- no matching note found. [SCOPE] Create architecture note arch-docs for the docs component of claude-custom.
• [x] Forgejo issue -- https://forgejo.tail5b443a.ts.net/ldraney/claude-custom/issues/283, open

File Targets

• [x] ~/pal-e-docs/src/pal_e_docs/models.py -- verified: Project class at line 56, confirmed NO status column exists. Change is valid.
• [x] ~/pal-e-docs/alembic/versions/ -- verified: directory exists with 4 existing migrations. New migration is valid.
• [x] ~/pal-e-docs/src/pal_e_docs/schemas.py -- verified: ProjectOut (line 49), ProjectCreate, ProjectUpdate all lack status field. Change is valid.
• [x] ~/pal-e-docs/src/pal_e_docs/routes/projects.py -- verified: list_projects (line 35) has no status filtering. Change is valid.
• [x] ~/paldocs/app/models/project.rb -- verified: exists, no status scope. Change is valid.
• [x] ~/paldocs/app/controllers/ -- verified: directory exists with projects_controller.rb. Sprint controller would be new.
• [x] ~/paldocs/db/ci_schema.sql -- verified: projects table (line 5) has no status column. Change is valid.
• [x] docs/operations.md -- verified: Sprint Orchestration section exists at line 59. Already mentions paldocs as target interface. Update is valid.
• [x] docs/mcp-servers.md -- verified: exists. Adding project status field documentation is valid.

All 9 file targets verified. All paths exist and the described changes are accurate.

Repo Placement

Issue filed on claude-custom (tracking repo) -- correct, since changes span 3 repos: pal-e-docs (schema/API), paldocs (Rails UI), claude-custom (docs). However, changes to pal-e-docs and paldocs will need separate PRs in those repos. The issue does not explicitly document this multi-repo PR strategy. This is acceptable for a tracking issue but will need decomposition into per-repo sub-tickets.

Dependencies

• claude-custom#277 (stale board cleanup) -- documented as related. Blocked on knowing which projects are relevant, which this ticket enables. Correct dependency.
• claude-custom#280 (Sprint SOP) -- documented as related. Sprint planning interface is part of the SOP. Correct dependency.
• claude-custom#281 (Dispatch wave 1) -- documented as related. Needs the interface to stage waves. Correct dependency.
• #274 (Ollama restore, in_progress) -- no direct dependency.
• #275 (dictionary, in_progress) -- no direct dependency.
• Execution order: pal-e-docs schema change MUST land before paldocs can consume the status column. This sequencing is implied by the constraints but not explicitly stated as a dependency chain.

Acceptance Criteria

• AC1: "projects table has status column" -- testable via migration + model inspection
• AC2: "list_projects API defaults to active" -- testable via API call
• AC3: "Dead projects marked as archived" -- requires human review (constraint #2 says "needs Lucas's review"). Not automatable by agent alone.
• AC4: "Paldocs shows only active projects in sprint planning views" -- testable via controller spec + UI
• AC5: "Paldocs can display boards from multiple selected projects" -- significant new UI feature, multiple views/controllers
• AC6: "claude-custom docs updated" -- testable via file content check

6 acceptance criteria. AC3 requires human decision (which projects to archive). AC5 is a substantial UI feature that alone could be a separate ticket.

Blast Radius

• pal-e-docs MCP tools (list_projects) will inherit the status filter -- all MCP consumers will only see active projects by default. This is the desired behavior but is not called out in the AC.
• The Repo model already has a status column (line 94 of models.py) with active/archived -- the Project status column follows the same pattern, good consistency.
• paldocs ci_schema.sql must stay in sync with the real schema -- adding status there is correct for CI.
• No other repos appear to directly query the projects table.

Decomposition Assessment

NEEDS DECOMPOSITION

• 9 file targets across 3 repos -- exceeds threshold of >3 files across >2 repos
• 6 acceptance criteria -- exceeds threshold of >5 AC
• Estimated agent work: well over 5 minutes. The pal-e-docs schema change alone is a focused task (migration + model + schema + route). The paldocs sprint planning UI is a separate, substantial feature (new controller, views, board integration). The docs update is a third independent unit.
• Natural decomposition boundary: (1) pal-e-docs schema + API, (2) paldocs status scope + CI schema, (3) paldocs sprint planning UI, (4) claude-custom docs update, (5) bulk archive dead projects (human-gated).

[DECOMPOSE] 9 file targets across 3 repos, 6 AC. Route to skill-decompose-ticket.

Recommendation

• [SCOPE] Create user story entry "sprint-orchestration" on project-claude-custom user-stories section.
• [SCOPE] Create architecture note arch-docs for the docs component of claude-custom. (Memory references "arch-docs-claude-custom" but the note does not exist in pal-e-docs.)
• [BODY] Add explicit dependency chain: "pal-e-docs PR must merge before paldocs PR can be created (paldocs reads the schema)."
• [DECOMPOSE] 9 file targets across 3 repos, 6 AC, well over 5 minutes. Route to skill-decompose-ticket for sub-ticket creation.

Verdict: APPROVED

Re-review of board item #1529 after scope refinement. Previous review review-1529-2026-06-20 returned NEEDS_REFINEMENT because the issue described building hooks that already exist. The rewritten issue correctly scopes this as a deletion/cleanup task.

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone, discovered during PR #265
• [x] Repo — ldraney/claude-custom
• [x] User Story — present (As the Overseer...)
• [x] Context — thorough explanation of migration to Forgejo, MCP replacements
• [x] File Targets — detailed with DELETE/MODIFY/NOT-TOUCH categories
• [x] Feature Flag — None (correct for cleanup task)
• [x] Acceptance Criteria — 8 criteria
• [x] Test Expectations — 4 items with concrete commands
• [x] Constraints — clear guardrails (no new hooks, don't touch MCP hooks)
• [x] Checklist — present
• [x] Related — present

Traceability

• [x] story:operational-reference label — verified on board item
• [x] story note verified — found in project-claude-custom user-stories section ("As the Overseer or any agent working in this repo, I can find which files to modify...")
• [x] arch:hooks label — present on board item
• [ ] arch note MISSING — no arch-hooks note found in pal-e-docs. However, this is a deletion/cleanup task that removes dead code. The arch note gap is pre-existing and not introduced by this ticket. Acceptable to proceed without it.
• [x] Forgejo issue — ldraney/claude-custom#268, open

File Targets

Files to DELETE (all verified to exist):

• [x] hooks/post-merge-rebase.sh — exists, confirmed dead (replaced by post-mcp-merge-rebase.sh)
• [x] hooks/block-pr-merge.sh — exists, confirmed dead (replaced by block-mcp-merge.sh)
• [x] hooks/remind-review-loop.sh — exists, confirmed dead (replaced by remind-mcp-review-loop.sh)
• [x] hooks/block-upstream.sh — exists, blocks gh commands never used post-migration

Files to MODIFY (all verified):

• [x] hooks/check-issue.sh — confirmed: lines 105-111 (github) case) and lines 118-124 (*) fallback) contain gh issue view calls. Issue says "~lines 82-123" which is approximate but scope is correct.
• [x] settings.json — confirmed: 4 hook wiring entries at lines 56, 68, 223, 227. Also has Bash(gh api:*) permission at line 4.
• [x] settings.local.json — confirmed: 15 Bash(gh ...:*) permission entries

Files to PRESERVE (verified):

• [x] hooks/post-mcp-merge-rebase.sh — exists, active
• [x] hooks/block-mcp-merge.sh — exists, active
• [x] hooks/remind-mcp-review-loop.sh — exists, active
• [x] WebFetch(domain:github.com) — confirmed at settings.json line 6
• [x] WebFetch(domain:raw.githubusercontent.com) — confirmed at settings.json line 7

Repo Placement

OK — issue filed on ldraney/claude-custom, all file targets are in the same repo.

Dependencies

No blocking dependencies. Board item #1526 (docs/ directory, PR #265) is done. No other in-progress items conflict.

Acceptance Criteria

All 8 AC are concrete and agent-verifiable:

• AC 1-2: file deletion + settings cleanup — verifiable with ls and grep
• AC 3: check-issue.sh cleanup — verifiable with grep
• AC 4-5: permission cleanup — verifiable with grep
• AC 6: preservation — verifiable with grep
• AC 7: MCP hooks untouched — verifiable with git diff
• AC 8: syntax check — verifiable with bash -n

Test command is concrete and correct: bash -n hooks/*.sh && grep -l "post-merge-rebase\|block-pr-merge\|remind-review-loop\|block-upstream" settings.json settings.local.json

Blast Radius

Docs references (not in scope but noted): The 4 dead hooks are referenced in 3 docs files:

• docs/hooks.md — 4 references (lines 31, 34, 85, 86)
• docs/filetree.md — 4 references (lines 41, 42, 68, 72)
• docs/operations.md — 1 reference (line 38)

The issue does NOT include these docs files in its File Targets. This is acceptable because the /update-docs skill runs post-merge and will catch stale doc references. However, an efficient agent could clean these in the same PR.

MCP hook comments: post-mcp-merge-rebase.sh (line 5, 67) and remind-mcp-review-loop.sh (line 5) reference the old hooks in comments. These become stale after deletion but are harmless. Issue correctly says "Do not modify any *-mcp-* hooks."

No functional cross-references: No other hook sources or imports the 4 dead hooks. All references are in settings wiring (being removed), docs (post-merge cleanup), and comments (harmless).

Decomposition Assessment

8 AC across 7 file targets in 1 repo. AC count exceeds the >5 threshold. However:

• This is a pure deletion/cleanup task — no new code to write
• All operations are mechanical: rm, grep-and-delete lines, bash -n verify
• Single repo, no cross-repo coordination
• Estimated agent time: 3-4 minutes

No decomposition needed. The 5-minute rule exists to prevent complex multi-system changes from being bundled. This ticket's high AC count reflects thoroughness of verification, not complexity of implementation.

Recommendation

No action needed. Scope is clean and well-defined for a single agent pass.

Note: The missing arch-hooks note is a pre-existing gap, not introduced by this ticket. Creating it is out of scope for this cleanup task but could be tracked separately.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type
• [x] Lineage
• [x] Repo
• [x] User Story
• [x] Context
• [x] File Targets
• [x] Feature Flag
• [x] Acceptance Criteria
• [x] Test Expectations
• [x] Constraints
• [x] Checklist
• [x] Related

Traceability

• [x] story:operational-reference label -- verified on project-claude-custom user-stories section
• [x] story note verified -- "operational-reference" entry found in project-claude-custom user-stories section
• [ ] arch note MISSING -- [SCOPE] Create architecture note arch-hooks for component hooks. Search for "arch-hooks" returned no results in pal-e-docs.
• [x] arch:hooks label present on board item
• [x] Forgejo issue -- https://forgejo.tail5b443a.ts.net/ldraney/claude-custom/issues/268, open

File Targets

• [ ] hooks/post-merge-rebase.sh -- ISSUE: The issue says to "rewrite trigger: match on MCP tool response JSON" and update settings.json wiring, but hooks/post-mcp-merge-rebase.sh ALREADY EXISTS and is already wired as a PostToolUse hook on mcp__forgejo__merge_approved_pr in settings.json (line 267). AC1 and AC2 (fast-forward + worktree cleanup after MCP merge) are already working. The real scope here is just DELETING post-merge-rebase.sh (dead code that only fires on gh pr merge Bash commands) and removing its settings.json entry from the Bash PostToolUse matcher (line 228).
• [x] hooks/check-issue.sh -- verified: lines 106-123 contain GitHub/gh issue view code paths (github case + unknown platform fallback). Lines 178, 222, 242 contain gh CLI references in error messages.
• [ ] hooks/block-pr-merge.sh -- ISSUE: The issue says "remove gh pr merge detection, evaluate if this hook is still needed." It also handles Forgejo curl-based merges (lines 25-35). However, hooks/block-mcp-merge.sh is already wired for the MCP merge path in settings.json. The curl-based Forgejo merge path in block-pr-merge.sh would only fire if someone used curl directly instead of MCP -- likely dead code. Clarify: should the entire hook be deleted, or should the Forgejo curl path be preserved?
• [x] hooks/block-upstream.sh -- verified: entire hook blocks gh pr/issue create commands. All functionality is dead code since we use Forgejo MCP tools.
• [ ] hooks/remind-review-loop.sh -- PARTIAL ISSUE: The only gh CLI reference is in an advisory string in the Forgejo path (line 30: "use Forgejo API (curl) instead of gh CLI"). The GitHub PR creation trigger (lines 14-19, gh pr create) is dead code. The Forgejo curl-based PR creation trigger (lines 24-35) may also be dead code since remind-mcp-review-loop.sh already exists for the MCP PR submission path. Clarify: delete entire hook or just the GitHub path?
• [x] settings.local.json -- verified: 15 Bash(gh ...:*) entries in allow + 1 Bash(gh pr merge:*) in ask = 16 total entries to remove
• [x] settings.json -- verified: line 4 has Bash(gh api:*) permission to remove. WebFetch domains for github.com and raw.githubusercontent.com present (lines 6-7) -- issue correctly notes these should be evaluated for keeping.
• [ ] settings.json hook wiring -- ISSUE: The issue says "post-merge-rebase.sh matcher should change from Bash to mcp__forgejo__merge_approved_pr in PostToolUse." This is WRONG -- the MCP matcher already exists (line 263) using post-mcp-merge-rebase.sh. The actual work is to REMOVE post-merge-rebase.sh from the Bash PostToolUse matcher (line 228), not move it.

Repo Placement

OK -- all changes are in ldraney/claude-custom, matching the Forgejo issue repo.

Dependencies

No blocking dependencies found. The only other board item is #1526 (docs directory, already in done). The existing post-mcp-merge-rebase.sh and block-mcp-merge.sh hooks are dependencies that are already in place and must NOT be modified.

Acceptance Criteria

• AC1 "After mcp merge, local main fast-forwarded" -- ALREADY WORKS via post-mcp-merge-rebase.sh. This AC is misleading because it implies it's broken. It works. The ticket should reframe this as "verify existing behavior is preserved after dead code removal."
• AC2 "After MCP merge, worktree cleaned up" -- ALREADY WORKS via post-mcp-merge-rebase.sh lines 80-94. Same issue as AC1.
• AC3 "No gh CLI calls remain in any hook" -- verifiable, clear
• AC4 "settings.local.json has no Bash(gh) permissions" -- verifiable, clear
• AC5 "settings.json has no Bash(gh api) permission" -- verifiable, clear
• AC6 "All modified hooks still parse valid JSON" -- verifiable via bash -n

Blast Radius

• hooks/remind-mcp-review-loop.sh (NOT in file targets) also contains an advisory mention of "gh CLI" in its output string (line 10). Harmless but inconsistent if the goal is to eliminate all gh references.
• hooks/forgejo-helper.sh has is_github_repo() -- correctly excluded from scope.
• hooks/session-start-context.sh -- correctly excluded from scope.
• Removing block-upstream.sh and block-pr-merge.sh from settings.json hooks section will also be required -- the issue doesn't mention updating settings.json hook wiring for these two hooks, only for post-merge-rebase.sh.

Decomposition Assessment

8 file targets across 1 repo, 6 acceptance criteria. The work is straightforward deletion/cleanup (not complex logic), and is scoped to a single repo. Despite the high file count, an agent can complete this in a single pass under 5 minutes. No decomposition needed.

Recommendations

• [BODY] Fix file target for post-merge-rebase.sh: The scope should say "DELETE this hook (dead code) and remove its entry from settings.json Bash PostToolUse matcher (line 228)." Do NOT say "rewrite trigger" -- the MCP trigger already exists as post-mcp-merge-rebase.sh.
• [BODY] Fix settings.json hook wiring description: Remove "post-merge-rebase.sh matcher should change from Bash to mcp__forgejo__merge_approved_pr" -- this is already done. Replace with "remove post-merge-rebase.sh from Bash PostToolUse hooks, remove block-pr-merge.sh from Bash PreToolUse hooks, remove block-upstream.sh from Bash PreToolUse hooks, remove remind-review-loop.sh from Bash PostToolUse hooks."
• [BODY] Clarify block-pr-merge.sh scope: Should the Forgejo curl merge path (lines 25-35) be preserved or is it dead code now that block-mcp-merge.sh handles MCP merges?
• [BODY] Clarify remind-review-loop.sh scope: Should the Forgejo curl PR creation trigger (lines 24-35) be preserved or is it dead code now that remind-mcp-review-loop.sh handles MCP PR submissions?
• [BODY] Reframe AC1 and AC2: These features already work. Rewrite as "verify post-mcp-merge-rebase.sh still functions correctly after dead code removal" rather than implying they need to be built.
• [BODY] Add settings.json hook wiring cleanup for block-upstream.sh, block-pr-merge.sh, and remind-review-loop.sh to the File Targets section -- currently only post-merge-rebase.sh wiring change is mentioned.
• [SCOPE] Create architecture note arch-hooks for component hooks.

Verdict: READY

Round 2 review. All three issues from round 1 have been resolved. Scope is solid, traceability is complete, file targets are verified, and the ticket fits a single agent pass.

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone
• [x] Repo — ldraney/claude-custom
• [x] User Story — present
• [x] Context — present, includes CLAUDE.md symlink impact note (round 1 fix)
• [x] File Targets — 7 new docs + README.md rewrite, plus NOT-touch list
• [x] Feature Flag — none (correct for docs-only work)
• [x] Acceptance Criteria — 5 criteria
• [x] Test Expectations — 3 verification commands
• [x] Constraints — 3 constraints listed
• [x] Checklist — present
• [x] Related — references project page, arch note, enforcement-architecture, SOP

Traceability

• [x] story:operational-reference label — present on board item
• [x] story note verified — found in project-claude-custom user-stories section (round 1 fix)
• [x] arch:docs label — present on board item
• [x] arch note verified — arch-docs-claude-custom note exists in pal-e-docs (round 1 fix)
• [x] Forgejo issue — https://forgejo.tail5b443a.ts.net/ldraney/claude-custom/issues/264, state: open

File Targets

• [x] docs/filetree.md — NEW file, docs/ directory exists but is currently empty, confirmed ready for creates
• [x] docs/hooks.md — NEW file
• [x] docs/agents.md — NEW file
• [x] docs/skills.md — NEW file
• [x] docs/settings.md — NEW file
• [x] docs/mcp-servers.md — NEW file
• [x] docs/enforcement.md — NEW file
• [x] README.md — EXISTS (152 lines), will be rewritten as TOC
• [x] CLAUDE.md — verified symlink to README.md (ls -la confirms CLAUDE.md -> README.md)
• [x] NOT-touch list: settings.json, settings.local.json, hooks/* — clear boundaries

Repo Placement

OK — issue filed on ldraney/claude-custom, work targets ldraney/claude-custom. Single repo.

Dependencies

No dependencies. This is the only item on board-claude-custom. No blockers, not blocking anything else.

Acceptance Criteria

All 5 AC are verifiable by an agent:

• AC1: ls docs/*.md | wc -l == 7 — verifiable
• AC2: README.md contains TOC links — verifiable via grep
• AC3: ls -la CLAUDE.md shows symlink — verifiable
• AC4: doc accuracy against current repo state — verifiable by cross-referencing file lists
• AC5: "which file do I edit" question answerable — verifiable by reading docs

Test expectations provide concrete commands. All are real and executable.

Blast Radius

Low. No hooks, skills, or settings currently reference docs/. The README.md rewrite will change the CLAUDE.md content injected into sessions (acknowledged in Context section). No downstream consumers beyond session context injection.

Context Accuracy

Issue says "~40 hooks" (actual: 43 .sh files), "~25 skills" (actual: 28 directories), "3 agents" (actual: 3 .md files), "8 MCP servers" (actual: 8). All counts are close enough with the tilde approximations. No inaccuracies.

Decomposition Assessment

8 file targets in 1 repo, 5 AC. While file count exceeds 3, all files are documentation in a single directory, all in one repo, and the work is straightforward reference writing. Estimated agent time: 3-4 minutes. No decomposition needed.

Round 1 Issues — Resolution Verified

1. project-claude-custom project page — now exists with operational-reference user story in user-stories section. RESOLVED.
2. arch-docs-claude-custom architecture note — now exists with component description, purpose, scope, and conventions. RESOLVED.
3. Issue Context section CLAUDE.md symlink impact — Context section now explicitly states: "This means rewriting README.md will change the CLAUDE.md content injected into Claude Code sessions." RESOLVED.

Recommendation

No action needed.

Architecture: claude-custom docs/

Purpose

Operational reference documentation for the claude-custom configuration system. The docs/ directory provides self-contained reference material describing the structure, behavior, and conventions of every component in the claude-custom harness.

Diagram

graph TB
    CLAUDE_MD["CLAUDE.md (symlink)"] --> README["README.md (TOC)"]
    README --> FT["docs/filetree.md"]
    README --> HK["docs/hooks.md"]
    README --> AG["docs/agents.md"]
    README --> SK["docs/skills.md"]
    README --> ST["docs/settings.md"]
    README --> MC["docs/mcp-servers.md"]
    README --> EN["docs/enforcement.md"]
    README --> OP["docs/operations.md"]
    README --> PL["docs/platform-lifecycle.md"]

    subgraph "Session Start"
        CLAUDE_MD
    end

    subgraph "docs/"
        FT
        HK
        AG
        SK
        ST
        MC
        EN
        OP
        PL
    end

Components

Key Decisions

• docs/ over pal-e-docs for repo reference -- docs/ is co-located with the code it describes, version-controlled in the same repo, and available offline at session start. Pal-e-docs stores cross-project SOPs and conventions; docs/ stores repo-specific operational reference.
• CLAUDE.md as symlink, not standalone -- README.md is the single source of truth. The symlink ensures Claude Code reads it at session start without duplicating content.
• Each doc is self-contained -- no doc depends on reading another first. This allows agents to read only the doc relevant to their task.
• First PR pattern -- new repos always start with CLAUDE.md symlink + README.md TOC + docs/ directory. This ensures documentation infrastructure exists before feature work begins.
• /update-docs post-merge chain -- docs are maintained via the update-docs skill after merges, or directly during feature work in the same PR. This keeps docs synchronized with code changes.

Related

• project-claude-custom -- project page
• board-claude-custom -- project board
• enforcement-architecture -- defense-in-depth enforcement note
• agent-workflow -- main session owns docs, agents own repos
• feedback_first-pr-pattern -- memory file documenting the first PR convention
• arch-mac-bootstrap, arch-asc-provider, arch-tofu-consumers -- sibling arch notes in other projects

Vision

Version-controlled Claude Code configuration — agents, hooks, skills, settings, and MCP wiring — that deploys via symlink to ~/.claude/. The repo is the control plane for how Claude operates across all projects.

User Stories

operational-reference

As the Overseer or any agent working in this repo, I can find which files to modify for any task by consulting structured reference docs, so that onboarding is self-serve and tribal knowledge is eliminated.

sprint-orchestration

As a Superuser (Lucas), I can orchestrate sprints — cross-project waves of parallel agent work — by selecting active projects, triaging backlogs, staging independent tickets, and dispatching agents for simultaneous execution. Success: Wave completion without blocked tickets. All dispatched agents complete independently. Sprint planning takes <30min via paldocs interface.

Architecture

• arch:docs — Reference documentation in docs/ directory
• arch:hooks — Hook enforcement layer (hooks/)
• arch:skills — Skill system (skills/)
• arch:agents — Agent definitions (agents/)
• arch:settings — Settings and permissions (settings.json, settings.local.json)

Repos

• ldraney/claude-custom

Board

board-claude-custom

Ticket

#268 — Remove gh CLI references, fix post-merge hook for Forgejo MCP merges. PR #269 merged via squash.

Environment

Local repo at ~/claude-custom, verified on main branch post-merge.

Checks

Verdict

PASS — all checks green. 327 lines deleted, 19 added.

Discovered Issues

hooks/pypi-pr-checklist.sh is now effectively dead code — its trigger (gh pr create) will never fire. Needs follow-up ticket to delete or convert to MCP trigger.

Ticket

#264 — Add docs/ directory with operational reference documentation. PR #265 merged via squash.

Environment

Local repo at ~/claude-custom, verified on main branch post-merge.

Checks

Verdict

PASS — all checks green.

Discovered Issues

None.