c3a18b5ba0
* docs(#4440): stop telling agents to grep .env files the secret guard denies verification-patterns.md's <environment_config> and user-setup.md's three per-service Verification examples documented reading .env/.env.local directly via grep. Every covered runtime's secret-read guard denies that (Claude Code deny-rules since #768/v1.4.0; the always-on gsd-secret-read-guard hook since #4236/#4221 in 1.13.0) -- verified by piping each documented command through the shipped hook. verification-patterns.md now checks the environment (printenv) instead of the file, with a case statement replacing a broken grep -v alternation (grep's BRE `|` is literal, so the old placeholder filter matched nothing -- PLACEHOLDER/TODO_fill values passed the "substantive" check as real). Verified under sh (dash) against real/placeholder/empty/ unset values. Existence check ([ -f ".env" ] || [ -f ".env.local" ]) is untouched -- it was never denied. user-setup.md's three grep <SERVICE> .env.local lines are removed outright rather than swapped for printenv: those examples describe a Next.js shape where the framework loads .env.local at runtime without exporting it to the shell, so a printenv substitute would wrongly report "not set" on a correctly configured project. Each block's existing service-level check (build/webhook/connection/email test) already verifies the setup. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * docs(#4440): changeset for the secret-guard verification-examples fix Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * docs(#4440): backfill changeset PR number Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> --------- Co-authored-by: sim <sim@local> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
GSD Canonical Artifact Registry
This directory contains the template files for every artifact that GSD workflows officially produce. The table below is the authoritative index: if a .planning/ root file is not listed here, gsd-health will flag it as W019 (unrecognized artifact).
Agents should query this file before treating a .planning/ file as authoritative. If the file name does not appear below, it is not a canonical GSD artifact.
.planning/ Root Artifacts
These files live directly at .planning/ — not inside phase subdirectories.
| File | Template | Produced by | Purpose |
|---|---|---|---|
PROJECT.md |
project.md |
/gsd:new-project |
Project identity, goals, requirements summary |
ROADMAP.md |
roadmap.md |
/gsd:new-milestone, /gsd:new-project |
Phase plan with milestones and progress tracking |
STATE.md |
state.md |
/gsd:new-project, /gsd:health --repair |
Current session state, active phase, last activity |
REQUIREMENTS.md |
requirements.md |
/gsd:new-milestone |
Functional requirements with traceability |
MILESTONES.md |
milestone.md |
/gsd:complete-milestone |
Log of completed milestones with accomplishments |
BACKLOG.md |
(inline) | /gsd-add-backlog |
Pending ideas and deferred work |
LEARNINGS.md |
(inline) | /gsd:extract-learnings, /gsd:execute-phase (gated: features.global_learnings) |
Phase retrospective learnings for future plans |
THREADS.md |
(inline) | /gsd:thread |
Persistent discussion threads |
config.json |
config.json |
/gsd:new-project, /gsd:health --repair |
Project-specific GSD configuration |
CLAUDE.md |
claude-md.md |
/gsd-profile |
Auto-assembled Claude Code context file |
RETROSPECTIVE.md |
(inline) | /gsd:complete-milestone |
Living milestone retrospective updated at each milestone close |
Version-stamped artifacts (pattern: vX.Y-*.md)
| Pattern | Produced by | Purpose |
|---|---|---|
vX.Y-MILESTONE-AUDIT.md |
/gsd:audit-milestone |
Milestone audit report before archiving |
These files are archived to .planning/milestones/ by /gsd:complete-milestone. Finding them at the .planning/ root after completion indicates the archive step was skipped.
Phase Subdirectory Artifacts (.planning/phases/NN-name/)
These files live inside a phase directory. They are NOT checked by W019 (which only inspects the .planning/ root).
| File Pattern | Template | Produced by | Purpose |
|---|---|---|---|
NN-MM-PLAN.md |
phase-prompt.md |
/gsd:plan-phase |
Executable implementation plan |
NN-MM-SUMMARY.md |
summary.md |
/gsd:execute-phase |
Post-execution summary with learnings |
NN-CONTEXT.md |
context.md |
/gsd:discuss-phase |
Scoped discussion decisions for the phase |
NN-RESEARCH.md |
research.md |
/gsd:plan-phase, /gsd:plan-phase --research-phase <N> |
Technical research for the phase |
NN-VALIDATION.md |
VALIDATION.md |
/gsd:plan-phase (Nyquist) |
Validation architecture (Nyquist method) |
NN-UAT.md |
UAT.md |
/gsd:validate-phase |
User acceptance test results |
NN-PATTERNS.md |
(inline) | /gsd:plan-phase (pattern mapper) |
Analog file mapping for the phase |
NN-UI-SPEC.md |
UI-SPEC.md |
/gsd:ui-phase |
UI design contract |
NN-SECURITY.md |
SECURITY.md |
/gsd:secure-phase |
Security threat model |
NN-AI-SPEC.md |
AI-SPEC.md |
/gsd:ai-integration-phase |
AI integration spec with eval strategy |
NN-DEBUG.md |
DEBUG.md |
/gsd:debug |
Debug session log |
NN-REVIEWS.md |
(inline) | /gsd:review |
Cross-AI review feedback |
Milestone Archive (.planning/milestones/)
Files archived by /gsd:complete-milestone. These are never checked by W019.
| File Pattern | Source |
|---|---|
vX.Y-ROADMAP.md |
Snapshot of ROADMAP.md at milestone close |
vX.Y-REQUIREMENTS.md |
Snapshot of REQUIREMENTS.md at milestone close |
vX.Y-MILESTONE-AUDIT.md |
Moved from .planning/ root |
vX.Y-phases/ |
Archived phase directories (if --archive-phases used) |
Adding a New Canonical Artifact
When a new workflow produces a .planning/ root file:
- Add the file name to
CANONICAL_EXACTingsd-core/bin/lib/artifacts.cjs - Add a row to the
.planning/Root Artifacts table above - Add the template to
gsd-core/templates/if one exists