f0a20e4dd7
* feat(2158): add audit.cjs open artifact scanner with security-hardened path handling - Scans 8 .planning/ artifact categories for unresolved state - Debug sessions, quick tasks, threads, todos, seeds, UAT gaps, verification gaps, CONTEXT open questions - requireSafePath with allowAbsolute:true on all file reads - sanitizeForDisplay on all output strings - Graceful per-category error handling, never throws - formatAuditReport returns human-readable report with emoji indicators * feat(2158): add audit-open CLI command to gsd-tools.cjs + Deferred Items to state template - Add audit-open [--json] case to switch router - Add audit-open entry to header comment block - Add Deferred Items section to state.md template for milestone carry-forward * feat(2157): add phase artifact scan step to verify-work workflow - scan_phase_artifacts step runs audit-open --json after UAT completion - Surfaces UAT gaps, VERIFICATION gaps, and CONTEXT open questions for current phase - Prompts user to confirm or decline before marking phase verified - Records acknowledged gaps in VERIFICATION.md Acknowledged Gaps section - SECURITY note: file paths validated, content truncated and sanitized before display * feat(2158): add pre-close artifact audit gate to complete-milestone workflow - pre_close_artifact_audit step runs before verify_readiness - Displays full audit report when open items exist - Three-way choice: Resolve, Acknowledge all, or Cancel - Acknowledge path writes deferred items table to STATE.md - Records deferred count in MILESTONES.md entry - Adds three new success criteria checklist items - SECURITY note on sanitizing all STATE.md writes * test(2157,2158): add milestone audit gate tests - 6 tests for audit.cjs: structured result, graceful missing dirs, open debug detection, resolved session exclusion, formatAuditReport header, all-clear message - 3 tests for complete-milestone.md: pre_close_artifact_audit step, Deferred Items, security note presence - 2 tests for verify-work.md: scan_phase_artifacts step, user prompt for gaps - 1 test for state.md template: Deferred Items section
185 lines
4.6 KiB
Markdown
185 lines
4.6 KiB
Markdown
# State Template
|
||
|
||
Template for `.planning/STATE.md` — the project's living memory.
|
||
|
||
---
|
||
|
||
## File Template
|
||
|
||
```markdown
|
||
# Project State
|
||
|
||
## Project Reference
|
||
|
||
See: .planning/PROJECT.md (updated [date])
|
||
|
||
**Core value:** [One-liner from PROJECT.md Core Value section]
|
||
**Current focus:** [Current phase name]
|
||
|
||
## Current Position
|
||
|
||
Phase: [X] of [Y] ([Phase name])
|
||
Plan: [A] of [B] in current phase
|
||
Status: [Ready to plan / Planning / Ready to execute / In progress / Phase complete]
|
||
Last activity: [YYYY-MM-DD] — [What happened]
|
||
|
||
Progress: [░░░░░░░░░░] 0%
|
||
|
||
## Performance Metrics
|
||
|
||
**Velocity:**
|
||
- Total plans completed: [N]
|
||
- Average duration: [X] min
|
||
- Total execution time: [X.X] hours
|
||
|
||
**By Phase:**
|
||
|
||
| Phase | Plans | Total | Avg/Plan |
|
||
|-------|-------|-------|----------|
|
||
| - | - | - | - |
|
||
|
||
**Recent Trend:**
|
||
- Last 5 plans: [durations]
|
||
- Trend: [Improving / Stable / Degrading]
|
||
|
||
*Updated after each plan completion*
|
||
|
||
## Accumulated Context
|
||
|
||
### Decisions
|
||
|
||
Decisions are logged in PROJECT.md Key Decisions table.
|
||
Recent decisions affecting current work:
|
||
|
||
- [Phase X]: [Decision summary]
|
||
- [Phase Y]: [Decision summary]
|
||
|
||
### Pending Todos
|
||
|
||
[From .planning/todos/pending/ — ideas captured during sessions]
|
||
|
||
None yet.
|
||
|
||
### Blockers/Concerns
|
||
|
||
[Issues that affect future work]
|
||
|
||
None yet.
|
||
|
||
## Deferred Items
|
||
|
||
Items acknowledged and carried forward from previous milestone close:
|
||
|
||
| Category | Item | Status | Deferred At |
|
||
|----------|------|--------|-------------|
|
||
| *(none)* | | | |
|
||
|
||
## Session Continuity
|
||
|
||
Last session: [YYYY-MM-DD HH:MM]
|
||
Stopped at: [Description of last completed action]
|
||
Resume file: [Path to .continue-here*.md if exists, otherwise "None"]
|
||
```
|
||
|
||
<purpose>
|
||
|
||
STATE.md is the project's short-term memory spanning all phases and sessions.
|
||
|
||
**Problem it solves:** Information is captured in summaries, issues, and decisions but not systematically consumed. Sessions start without context.
|
||
|
||
**Solution:** A single, small file that's:
|
||
- Read first in every workflow
|
||
- Updated after every significant action
|
||
- Contains digest of accumulated context
|
||
- Enables instant session restoration
|
||
|
||
</purpose>
|
||
|
||
<lifecycle>
|
||
|
||
**Creation:** After ROADMAP.md is created (during init)
|
||
- Reference PROJECT.md (read it for current context)
|
||
- Initialize empty accumulated context sections
|
||
- Set position to "Phase 1 ready to plan"
|
||
|
||
**Reading:** First step of every workflow
|
||
- progress: Present status to user
|
||
- plan: Inform planning decisions
|
||
- execute: Know current position
|
||
- transition: Know what's complete
|
||
|
||
**Writing:** After every significant action
|
||
- execute: After SUMMARY.md created
|
||
- Update position (phase, plan, status)
|
||
- Note new decisions (detail in PROJECT.md)
|
||
- Add blockers/concerns
|
||
- transition: After phase marked complete
|
||
- Update progress bar
|
||
- Clear resolved blockers
|
||
- Refresh Project Reference date
|
||
|
||
</lifecycle>
|
||
|
||
<sections>
|
||
|
||
### Project Reference
|
||
Points to PROJECT.md for full context. Includes:
|
||
- Core value (the ONE thing that matters)
|
||
- Current focus (which phase)
|
||
- Last update date (triggers re-read if stale)
|
||
|
||
Claude reads PROJECT.md directly for requirements, constraints, and decisions.
|
||
|
||
### Current Position
|
||
Where we are right now:
|
||
- Phase X of Y — which phase
|
||
- Plan A of B — which plan within phase
|
||
- Status — current state
|
||
- Last activity — what happened most recently
|
||
- Progress bar — visual indicator of overall completion
|
||
|
||
Progress calculation: (completed plans) / (total plans across all phases) × 100%
|
||
|
||
### Performance Metrics
|
||
Track velocity to understand execution patterns:
|
||
- Total plans completed
|
||
- Average duration per plan
|
||
- Per-phase breakdown
|
||
- Recent trend (improving/stable/degrading)
|
||
|
||
Updated after each plan completion.
|
||
|
||
### Accumulated Context
|
||
|
||
**Decisions:** Reference to PROJECT.md Key Decisions table, plus recent decisions summary for quick access. Full decision log lives in PROJECT.md.
|
||
|
||
**Pending Todos:** Ideas captured via /gsd-add-todo
|
||
- Count of pending todos
|
||
- Reference to .planning/todos/pending/
|
||
- Brief list if few, count if many (e.g., "5 pending todos — see /gsd-check-todos")
|
||
|
||
**Blockers/Concerns:** From "Next Phase Readiness" sections
|
||
- Issues that affect future work
|
||
- Prefix with originating phase
|
||
- Cleared when addressed
|
||
|
||
### Session Continuity
|
||
Enables instant resumption:
|
||
- When was last session
|
||
- What was last completed
|
||
- Is there a .continue-here file to resume from
|
||
|
||
</sections>
|
||
|
||
<size_constraint>
|
||
|
||
Keep STATE.md under 100 lines.
|
||
|
||
It's a DIGEST, not an archive. If accumulated context grows too large:
|
||
- Keep only 3-5 recent decisions in summary (full log in PROJECT.md)
|
||
- Keep only active blockers, remove resolved ones
|
||
|
||
The goal is "read once, know where we are" — if it's too long, that fails.
|
||
|
||
</size_constraint>
|