feat(projman): implement 8 improvement issues (#231-#238) #239

lmiranda · 2026-01-28T15:53:12Z

lmiranda commented

2026-01-28 15:53:12 +00:00

Summary

Implements all 8 projman improvement issues identified during Sprint 3 execution:

Issue	Description
#231	Fix MCP branch detection - use project directory
#232	Add structured progress comments for visibility
#233	Add sprint approval requirement before execution
#234	Add file conflict prevention for parallel agents
#235	Add Status labels (In-Progress, Blocked, Failed, Deferred)
#236	Add runaway detection and circuit breaker
#237	Add checkpoint/resume for interrupted work
#238	Add strict task sizing rules (L/XL must break down)

Key Improvements

Agent Reliability:

Self-monitoring with circuit breaker (3x same error → stop)
Hard stop at 100 tool calls with checkpoint
Budget warnings at 50 and 80 calls

Visibility:

Structured progress comments with phase, tool calls, steps
Status labels for accurate issue state tracking
Sprint-status parses progress comments

Safety:

Sprint approval required before execution
File conflict detection before parallel dispatch
Scope enforcement during execution

Resumability:

Checkpoint comments save branch, files, steps
Sprint-start detects and offers resume
Work survives interruptions

Test Plan

Run /sprint-plan - verify approval request appears
Run /sprint-start - verify approval check
Create L task - verify planner refuses without breakdown
Run parallel tasks - verify conflict detection
Simulate agent failure - verify checkpoint saved

Closes #231, #232, #233, #234, #235, #236, #237, #238

🤖 Generated with Claude Code

## Summary Implements all 8 projman improvement issues identified during Sprint 3 execution: | Issue | Description | |-------|-------------| | #231 | Fix MCP branch detection - use project directory | | #232 | Add structured progress comments for visibility | | #233 | Add sprint approval requirement before execution | | #234 | Add file conflict prevention for parallel agents | | #235 | Add Status labels (In-Progress, Blocked, Failed, Deferred) | | #236 | Add runaway detection and circuit breaker | | #237 | Add checkpoint/resume for interrupted work | | #238 | Add strict task sizing rules (L/XL must break down) | ## Key Improvements **Agent Reliability:** - Self-monitoring with circuit breaker (3x same error → stop) - Hard stop at 100 tool calls with checkpoint - Budget warnings at 50 and 80 calls **Visibility:** - Structured progress comments with phase, tool calls, steps - Status labels for accurate issue state tracking - Sprint-status parses progress comments **Safety:** - Sprint approval required before execution - File conflict detection before parallel dispatch - Scope enforcement during execution **Resumability:** - Checkpoint comments save branch, files, steps - Sprint-start detects and offers resume - Work survives interruptions ## Test Plan - [ ] Run `/sprint-plan` - verify approval request appears - [ ] Run `/sprint-start` - verify approval check - [ ] Create L task - verify planner refuses without breakdown - [ ] Run parallel tasks - verify conflict detection - [ ] Simulate agent failure - verify checkpoint saved Closes #231, #232, #233, #234, #235, #236, #237, #238 🤖 Generated with [Claude Code](https://claude.ai/code)

lmiranda added 28 commits 2026-01-28 15:53:12 +00:00

feat(data-platform): add schema diff detection hook (#228 ) eb85ea31bb

Implements PostToolUse hook to warn about potentially breaking schema changes:
- DROP COLUMN/TABLE/INDEX detection
- Column type changes (ALTER TYPE, MODIFY COLUMN)
- NOT NULL constraint additions
- RENAME operations
- ORM model field removals

Non-blocking - outputs warnings only.
Configurable via DATA_PLATFORM_SCHEMA_WARN env var.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

feat(git-flow): add commit message enforcement hook (#225 ) 1b36ca77ab

Implements PreToolUse/Bash hook to validate conventional commit format:
- Validates type(scope): description format
- Supports all 10 types: feat, fix, docs, style, refactor, perf, test, chore, build, ci
- Optional scope support
- Helpful error messages with examples
- Non-commit commands pass through
- Uses Python for reliable JSON parsing

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

feat(clarity-assist): add vagueness detection hook (#227 ) 8048fba931

Implements UserPromptSubmit hook to detect vague prompts:
- Checks for short prompts without context
- Detects ambiguous phrases ("fix it", "help me with")
- Suggests /clarity-assist when beneficial
- Non-blocking, configurable via CLARITY_ASSIST_AUTO_SUGGEST

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

feat(contract-validator): add SessionStart auto-validate hook (#229 ) 7cae21f7c9

Implements smart SessionStart hook for plugin validation:
- Validates plugin contracts only when files change (smart mode)
- Caches file hashes to avoid redundant checks
- Non-blocking warnings for compatibility issues
- Configurable via CONTRACT_VALIDATOR_AUTO_CHECK

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

feat(git-flow): add branch name validation hook (#226 ) af6a42b2ac

Implements PreToolUse/Bash hook to validate branch naming convention:
- Validates type/description format
- Allowed types: feat, fix, chore, docs, refactor, test, perf, debug
- Enforces lowercase, hyphens, max 50 chars
- Non-branch commands pass through

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

feat(contract-validator): add breaking change detection hook (#230 ) 551c60fb45

Implements PostToolUse hook to warn about breaking interface changes:
- Detects changes to plugin.json, hooks.json, .mcp.json, agents/*.md
- Compares with git HEAD to find removed/changed elements
- Warns on: removed hooks, changed matchers, removed MCP servers
- Warns on: plugin name changes, major version bumps
- Non-blocking, configurable via CONTRACT_VALIDATOR_BREAKING_WARN

Depends on #229 (SessionStart auto-validate infrastructure).

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs(changelog): add Sprint 3 hooks implementation b7fce0fafd

- git-flow: commit message and branch name validation hooks
- clarity-assist: vagueness detection hook
- data-platform: schema diff detection hook
- contract-validator: SessionStart auto-validate and breaking change hooks
- Document MCP bug #231 (branch detection from wrong directory)

Sprint 3 - Hooks completed (issues #225-#230)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Merge feat/225-commit-message-hook into development 223a2d626a

Merge feat/226-branch-name-validation into development aee199e6cf

Merge feat/227-vagueness-detection-hook into development b8851a0ae3

Merge feat/228-schema-diff-hook into development a66a2bc519

Merge feat/229-session-auto-validate into development 894e015c01

Merge feat/230-breaking-change-detection into development 5b3da8da85

Resolved conflict in hooks.json - combined SessionStart and PostToolUse hooks

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

fix(gitea-mcp): use project directory for branch detection (#231 ) 8234683bc3

The _get_current_branch() method was running git commands from the
installed plugin directory instead of the user's project directory.
This caused incorrect branch detection (always seeing 'main' from
the marketplace repo instead of the user's actual branch).

Fix: Use CLAUDE_PROJECT_DIR environment variable to get the correct
project directory and pass it as cwd to subprocess.run().

Fixes #231

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

feat(projman): add Status labels for accurate issue state tracking (#235 ) 4bd15e5deb

- Add Status/In-Progress, Status/Blocked, Status/Failed, Status/Deferred labels
- Update orchestrator.md with Status Label Management section
- Update executor.md with honest Status Reporting requirements
- Update labels-reference.md with Status detection guidelines

Status labels enable accurate tracking:
- In-Progress: Work actively being done
- Blocked: Waiting for dependency/external factor
- Failed: Attempted but couldn't complete
- Deferred: Moved to future sprint

Agents must report honestly - never say "completed" when blocked/failed.

Closes #235

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

feat(projman): add structured progress comments for real-time visibility (#232 ) 008187a0a4

Add structured progress comment format for agents:
- Standard format with Status, Phase, Tool Calls budget
- Completed/In-Progress/Blockers/Next sections
- Clear examples for starting, blocked, and failed states
- Guidance on when to post (every 20-30 tool calls)

Update sprint-status.md:
- Document how to parse progress comments
- Show enhanced in-progress display with tool call tracking
- Add progress comment detection to blocker analysis

This enables users to see:
- Real-time agent progress
- Tool call budget consumption
- Current phase and step
- Blockers as they occur

Closes #232

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

feat(projman): add strict task sizing rules to prevent runaway agents (#238 ) 0abf510ec0

Add mandatory task scoping rules:
- XS: 1 file, 0-2 checklist items, ~30 tool calls
- S: 1 file, 2-4 checklist items, ~50 tool calls
- M: 2-3 files, 4-6 checklist items, ~80 tool calls
- L/XL: MUST be broken down into smaller tasks

Sprint 3 showed agents running 400+ tool calls on single tasks,
causing 1+ hour waits with no visibility. This enforces:
- Maximum task scope (M = 2-3 files, 80 tool calls)
- Mandatory breakdown for L/XL tasks
- Clear scoping checklist for planners
- Good/bad examples showing proper breakdown

Planner must refuse to create L/XL tasks without breakdown.

Closes #238

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

feat(projman): add runaway detection and circuit breaker for agents (#236 ) f2a62627d0

Executor self-monitoring:
- 10+ calls without progress → stop and reassess
- Same error 3+ times → circuit breaker, report failure
- 50+ calls → mandatory progress update
- 80+ calls → budget warning, evaluate completion
- 100+ calls → hard stop, save checkpoint

Orchestrator monitoring:
- Detect stuck agents (no progress for X minutes)
- Intervention protocol for runaway agents
- Timeout guidelines by task size (XS: 15min, S: 30min, M: 45min)
- Recovery actions with Status/Failed label

This prevents agents from running indefinitely (400+ tool calls
observed in Sprint 3) and provides clear stopping criteria.

Closes #236

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

feat(projman): add file conflict prevention for parallel agents (#234 ) a69a4d19d0

Add pre-dispatch conflict detection:
- Analyze target files for each task before parallel dispatch
- Check for file overlap between tasks in same batch
- If overlap detected, sequentialize those specific tasks
- Example analysis showing conflict detection workflow

Branch isolation protocol:
- Each task MUST have its own branch
- Never have two agents work on the same branch
- Sequential merge after completion (not simultaneous)
- Handle merge conflicts by stopping second task

Conflict resolution rules:
- Same file → MUST sequentialize
- Same directory → Usually safe, review
- Shared config → Sequentialize
- Shared test fixture → Sequentialize or assign different files

This prevents parallel agents from modifying the same files
and causing git merge conflicts.

Closes #234

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

feat(projman): add checkpoint/resume for interrupted agent work (#237 ) 459550e7d3

Executor checkpointing:
- Standard checkpoint comment format with branch, commit, phase
- Files modified with status (created, modified)
- Completed and pending steps tracking
- State notes for resumption context
- Save checkpoint after major steps, before stopping

Orchestrator resume detection:
- Scan issue comments for "## Checkpoint" markers
- Offer resume options: resume, start fresh, review details
- Verify branch exists and files match before resuming
- Dispatch executor with checkpoint context

Sprint-start integration:
- Checkpoint detection as first workflow step
- Resume flow documentation with example
- Checkpoint format specification

This enables resuming work after:
- Budget exhaustion (100 tool call limit)
- Agent failure/circuit breaker
- Manual interruption
- Session timeout

Closes #237

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

feat(projman): add sprint approval requirement before execution (#233 ) 26310d05f0

Sprint-plan approval workflow:
- Request explicit approval after creating issues
- Present scope summary (branches, files, dependencies)
- User must type "approve sprint N" to authorize
- Record approval in milestone description with timestamp

Sprint-start verification:
- Check milestone for "## Sprint Approval" section
- If missing, STOP and direct to /sprint-plan
- Extract approved scope (branches, files)
- Enforce scope during execution

Orchestrator scope enforcement:
- Verify approval before any execution
- Check each operation against approved scope
- Operations outside scope require re-approval

This separates planning (review) from execution (action),
preventing agents from executing without explicit user consent.

Closes #233

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Merge branch 'fix/235-status-labels' into development ad73c526b7

Merge branch 'fix/232-progress-visibility' into development 445b744196

Merge branch 'fix/238-task-scoping' into development 67f330be6c

Merge branch 'fix/236-runaway-detection' into development ba8e86e31c

Merge branch 'fix/234-parallel-conflicts' into development 235e72d3d7

Merge branch 'fix/237-checkpoint-resume' into development e37653f956

Merge branch 'fix/233-approval-token' into development 67944a7e1c

lmiranda merged commit 351be5a40d into development

2026-01-28 15:53:51 +00:00

lmiranda deleted branch feat/projman-improvements-231-238

2026-01-28 15:53:51 +00:00

lmiranda referenced this issue from a commit