#151 - fix: drop points enforcement + plan- gate — lean kanban alignment - ldraney/claude-custom

forgejo_admin commented

2026-03-24 17:18:02 +00:00

Author

Contributor

PR #151 Review

DOMAIN REVIEW

Tech stack: Bash hooks + JSON schema (Claude Code hook framework). Two files changed: hooks/check-board-item.sh (board item validation) and schemas/agent-spawn-requirements.json (agent spawn gate definitions).

Shell scripting quality:

check-board-item.sh: The POINTS variable is still extracted at line 23 (POINTS=$(echo "$INPUT" | jq -r '.tool_input.points // empty')) but is never referenced after the enforcement block was removed. This is dead code -- an unnecessary jq invocation on every board item creation. Non-blocking but worth cleaning up.
Remaining validation logic (labels, type-specific checks, fail-open pattern) is sound and unchanged.

Schema quality:

agent-spawn-requirements.json: Both dottie and general-purpose now have required_patterns: [], which means the hook at check-agent-spawn.sh line 47 will exit 0 immediately for both types. This is correct behavior for the stated intent.
Pre-existing observation: The hook normalizes dottie -> general-purpose at line 32-34 of check-agent-spawn.sh, which means the dottie entry in the schema is never actually looked up at runtime. The PR updated the dottie description anyway -- harmless since both entries are now identical in effect, but the dottie schema entry is technically dead code. Not introduced by this PR.
Descriptions are updated to reflect the new convention-based (not gate-based) approach. Good.

Stale references in session-start-context.sh (NOT in this PR's scope):

Line 271: get_note(slug="agent-spawn-conventions") -- the axiom: no plan, no agent -- this inline comment still references the "no plan, no agent" axiom which this PR relaxes. Agents reading this at session start will receive contradictory guidance.
Line 562: create_board_item with points and labels -- still mentions "points" as if required alongside labels. After this PR, points are optional.

These are in a file NOT touched by this PR. They represent discovered scope that should be tracked as a follow-up issue.

BLOCKERS

None.

This PR modifies hook enforcement logic (removing a gate), which is a policy change, not new functionality requiring test coverage. The test plan in the PR body covers the expected behavioral matrix (with/without points, with project- vs plan- reference). The changes are deletion-oriented -- removing enforcement rather than adding code paths -- so the BLOCKER criteria for "new functionality with zero test coverage" does not apply.

No secrets, no unvalidated input (these hooks validate input, they don't accept user input from the network), no DRY violations.

NITS

Dead variable in check-board-item.sh: Line 23 extracts POINTS but it is never used. Remove the extraction to avoid confusion and save a jq call:
```
# Remove this line:
POINTS=$(echo "$INPUT" | jq -r '.tool_input.points // empty')
```
Stale session context (discovered scope): hooks/session-start-context.sh lines 271 and 562 reference the old "no plan, no agent" axiom and "with points" language. These should be updated in a follow-up to avoid contradictory agent guidance. File a Forgejo issue for this.
Dead dottie schema entry (pre-existing): Since check-agent-spawn.sh normalizes dottie -> general-purpose before schema lookup, the dottie entry in the JSON is never read at runtime. Consider removing it or removing the normalization in the hook. Pre-existing, not introduced here.

SOP COMPLIANCE

Branch named after issue: 200-agent-spawn-drop-plan-gate references issue #200
PR body has: Summary, Changes, Test Plan, Related (uses "Review Checklist" instead of standard "Test Plan" header but content is equivalent)
Related references plan slug -- PR references Closes forgejo_admin/pal-e-docs#200 and Closes forgejo_admin/pal-e-docs#202 (issue references, not plan slug). Acceptable for board-driven work without a parent plan.
No secrets committed
No unnecessary file changes -- exactly 2 files, both directly related to the issues
Commit messages are descriptive (PR title: fix: drop points enforcement + plan- gate -- lean kanban alignment)

PROCESS OBSERVATIONS

Change failure risk: LOW. This is a gate relaxation (removing enforcement), not adding new enforcement. The failure mode is "agents can now do things they previously couldn't" rather than "agents are blocked from things they need to do." Rollback is trivial (re-add the patterns/enforcement).
Deployment frequency impact: POSITIVE. Removing the plan- gate for dottie/general-purpose agents unblocks board-driven projects from needing artificial plan references in spawn prompts. This should reduce friction in agent dispatch.
Documentation gap: The session-start-context.sh stale references (nit #2) should be tracked as a follow-up issue to avoid confusing agents at session start with the old "no plan, no agent" axiom.

VERDICT: APPROVED

## PR #151 Review ### DOMAIN REVIEW **Tech stack:** Bash hooks + JSON schema (Claude Code hook framework). Two files changed: `hooks/check-board-item.sh` (board item validation) and `schemas/agent-spawn-requirements.json` (agent spawn gate definitions). **Shell scripting quality:** - `check-board-item.sh`: The `POINTS` variable is still extracted at line 23 (`POINTS=$(echo "$INPUT" | jq -r '.tool_input.points // empty')`) but is never referenced after the enforcement block was removed. This is dead code -- an unnecessary `jq` invocation on every board item creation. Non-blocking but worth cleaning up. - Remaining validation logic (labels, type-specific checks, fail-open pattern) is sound and unchanged. **Schema quality:** - `agent-spawn-requirements.json`: Both `dottie` and `general-purpose` now have `required_patterns: []`, which means the hook at `check-agent-spawn.sh` line 47 will exit 0 immediately for both types. This is correct behavior for the stated intent. - Pre-existing observation: The hook normalizes `dottie` -> `general-purpose` at line 32-34 of `check-agent-spawn.sh`, which means the `dottie` entry in the schema is never actually looked up at runtime. The PR updated the `dottie` description anyway -- harmless since both entries are now identical in effect, but the `dottie` schema entry is technically dead code. Not introduced by this PR. - Descriptions are updated to reflect the new convention-based (not gate-based) approach. Good. **Stale references in `session-start-context.sh` (NOT in this PR's scope):** - Line 271: `get_note(slug="agent-spawn-conventions") -- the axiom: no plan, no agent` -- this inline comment still references the "no plan, no agent" axiom which this PR relaxes. Agents reading this at session start will receive contradictory guidance. - Line 562: `create_board_item with points and labels` -- still mentions "points" as if required alongside labels. After this PR, points are optional. These are in a file NOT touched by this PR. They represent discovered scope that should be tracked as a follow-up issue. ### BLOCKERS None. This PR modifies hook enforcement logic (removing a gate), which is a policy change, not new functionality requiring test coverage. The test plan in the PR body covers the expected behavioral matrix (with/without points, with project- vs plan- reference). The changes are deletion-oriented -- removing enforcement rather than adding code paths -- so the BLOCKER criteria for "new functionality with zero test coverage" does not apply. No secrets, no unvalidated input (these hooks validate input, they don't accept user input from the network), no DRY violations. ### NITS 1. **Dead variable in `check-board-item.sh`**: Line 23 extracts `POINTS` but it is never used. Remove the extraction to avoid confusion and save a `jq` call: ``` # Remove this line: POINTS=$(echo "$INPUT" | jq -r '.tool_input.points // empty') ``` 2. **Stale session context (discovered scope)**: `hooks/session-start-context.sh` lines 271 and 562 reference the old "no plan, no agent" axiom and "with points" language. These should be updated in a follow-up to avoid contradictory agent guidance. File a Forgejo issue for this. 3. **Dead `dottie` schema entry (pre-existing)**: Since `check-agent-spawn.sh` normalizes `dottie` -> `general-purpose` before schema lookup, the `dottie` entry in the JSON is never read at runtime. Consider removing it or removing the normalization in the hook. Pre-existing, not introduced here. ### SOP COMPLIANCE - [x] Branch named after issue: `200-agent-spawn-drop-plan-gate` references issue #200 - [x] PR body has: Summary, Changes, Test Plan, Related (uses "Review Checklist" instead of standard "Test Plan" header but content is equivalent) - [ ] Related references plan slug -- PR references `Closes forgejo_admin/pal-e-docs#200` and `Closes forgejo_admin/pal-e-docs#202` (issue references, not plan slug). Acceptable for board-driven work without a parent plan. - [x] No secrets committed - [x] No unnecessary file changes -- exactly 2 files, both directly related to the issues - [x] Commit messages are descriptive (PR title: `fix: drop points enforcement + plan- gate -- lean kanban alignment`) ### PROCESS OBSERVATIONS - **Change failure risk: LOW.** This is a gate relaxation (removing enforcement), not adding new enforcement. The failure mode is "agents can now do things they previously couldn't" rather than "agents are blocked from things they need to do." Rollback is trivial (re-add the patterns/enforcement). - **Deployment frequency impact: POSITIVE.** Removing the `plan-` gate for `dottie`/`general-purpose` agents unblocks board-driven projects from needing artificial plan references in spawn prompts. This should reduce friction in agent dispatch. - **Documentation gap:** The `session-start-context.sh` stale references (nit #2) should be tracked as a follow-up issue to avoid confusing agents at session start with the old "no plan, no agent" axiom. ### VERDICT: APPROVED

2026-03-24 17:15:57 +00:00

Summary

Align hooks with lean kanban philosophy: points are optional metadata (lead time is the metric), and board-driven projects don't need plan references.

Changes

schemas/agent-spawn-requirements.json: Remove plan- required_patterns from general-purpose and dottie agent types. Board-driven projects reference project- instead.
hooks/check-board-item.sh: Remove Fibonacci points enforcement. Points become optional metadata. Lead time (timestamps) is the real metric per lean kanban philosophy.

Test Plan

Create board item without points — should succeed
Create board item with points — should still work (optional)
Spawn general-purpose agent with project- reference — should succeed
Spawn general-purpose agent with plan- reference — should still work

Review Checklist

No unrelated changes
Hook still validates type: labels
Hook still validates forgejo_issue_url for issue items
Hook still validates note_slug for phase items

Closes forgejo_admin/pal-e-docs#200
Closes forgejo_admin/pal-e-docs#202

## Summary Align hooks with lean kanban philosophy: points are optional metadata (lead time is the metric), and board-driven projects don't need plan references. ## Changes - `schemas/agent-spawn-requirements.json`: Remove `plan-` required_patterns from `general-purpose` and `dottie` agent types. Board-driven projects reference `project-` instead. - `hooks/check-board-item.sh`: Remove Fibonacci points enforcement. Points become optional metadata. Lead time (timestamps) is the real metric per lean kanban philosophy. ## Test Plan - [x] Create board item without points — should succeed - [x] Create board item with points — should still work (optional) - [x] Spawn general-purpose agent with `project-` reference — should succeed - [x] Spawn general-purpose agent with `plan-` reference — should still work ## Review Checklist - [x] No unrelated changes - [x] Hook still validates type: labels - [x] Hook still validates forgejo_issue_url for issue items - [x] Hook still validates note_slug for phase items ## Related Closes forgejo_admin/pal-e-docs#200 Closes forgejo_admin/pal-e-docs#202

forgejo_admin added 2 commits

fix: drop plan- gate from general-purpose and dottie agent types 6d583fd908

Board-driven projects don't have plans. The plan- pattern was blocking
agent spawns for legitimate board-driven work (e.g., svelte-playground
ticket reviews). Convention still says reference context — just no
hard regex enforcement.

Closes forgejo_admin/pal-e-docs#200

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: drop points enforcement + plan- gate — lean kanban alignment 729ed204ab

Points are optional metadata, not required. Lead time (timestamps) is
the real metric. Removes Fibonacci enforcement from check-board-item.sh.

Also drops plan- pattern requirement from general-purpose and dottie
agent types — board-driven projects reference project- instead.

Closes forgejo_admin/pal-e-docs#200
Closes forgejo_admin/pal-e-docs#202

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>