gsdd-cli 0.18.4 → 0.19.0

package/distilled/templates/brownfield-change/CHANGE.md

@@ -0,0 +1,99 @@
+---
+change: CHANGE-001
+status: active
+type: medium_scope_brownfield
+---
+
+# Brownfield Change: [Short Title]
+
+> This folder is the bounded medium-scope lane.
+> It represents one active medium-scope change only.
+> Do not add phase numbering, roadmap checkboxes, or milestone state here.
+> Instantiate the live operational artifact at `.planning/brownfield-change/CHANGE.md`.
+> `progress` and `resume` read this file first for status, scope, integration surface, and the authoritative next action.
+> If this lane no longer fits one active stream, widen explicitly through `/gsdd-new-project` (first milestone) or `/gsdd-new-milestone` (subsequent milestone) using this folder as the preserved input surface. Do not invent a separate promotion artifact.
+
+## Goal
+
+State the single cohesive outcome this change is meant to achieve.
+
+## Why This Exists
+
+- Why this work matters now.
+- What user, operator, or repo problem it solves.
+
+## In Scope
+
+- What this change includes.
+- Which surfaces are allowed to move.
+
+## Out of Scope
+
+- What this change explicitly does not include.
+- Work that should promote into milestone planning instead of widening this folder.
+
+## Structural Promotion Triggers
+
+Widen into milestone planning only when one or more of these become true:
+
+- The work no longer fits one active stream with one shared goal and closeout path.
+- The change needs roadmap-owned lifecycle state, multiple planned phases, or milestone-level requirement tracking.
+- Independent slices can no longer keep disjoint write ownership under one bounded change.
+- The proof or review burden has grown beyond what one `CHANGE.md` / `HANDOFF.md` / `VERIFICATION.md` chain can carry honestly.
+
+Choose the widening surface case-by-case:
+
+- Use `/gsdd-new-project` when the repo has no shipped milestone history yet.
+- Use `/gsdd-new-milestone` when the repo already has shipped milestone history and this change now needs the next milestone cycle.
+
+## Done When
+
+- Observable outcomes that prove the change is complete.
+- Conditions that must be true before closeout.
+
+## Current Status
+
+- Current posture: `active | blocked | ready_for_verification | closed`
+- Current branch / integration surface:
+- Current owner / runtime:
+
+Keep these labels concrete and current. This section is the canonical operational continuity surface for the active change.
+
+## Next Action
+
+- The single best next move from repo truth.
+- If blocked, name the blocker and the exact unblock step.
+
+Keep the first bullet as the authoritative next action. `HANDOFF.md` may explain why, but it must not become a competing operational source.
+
+## PR Slice Ownership
+
+Use this only when the change spans multiple PRs or working slices.
+Every slice must have disjoint write ownership and still roll up to the same goal and closeout path.
+When possible, list repo-relative paths or module roots in `Owned files / modules` so continuity checks can compare the declared write scope to the live worktree.
+
+| Slice | Scope | Owned files / modules | Status |
+| --- | --- | --- | --- |
+| A | [What this slice does] | [Disjoint write set] | planned |
+
+## Dependencies And Risks
+
+- External dependencies or repo assumptions.
+- Cross-cut risks that would force promotion into milestone planning.
+
+## Widening Handoff
+
+If this bounded change needs milestone planning, reuse this folder directly instead of rediscovering the work:
+
+- `CHANGE.md` carries the active goal, scope, done-when, next action, and declared write scope.
+- `HANDOFF.md` carries the active constraints, unresolved uncertainty, decision posture, and anti-regression rules.
+- `VERIFICATION.md` carries the proof and gap state gathered so far, even when that proof is only partial.
+
+Promotion should preserve this context. Do not create a second durable handoff file before milestone setup begins.
+
+## Closeout Path
+
+1. Update `HANDOFF.md` so the latest decision context is recoverable from disk.
+2. Record closeout evidence in `VERIFICATION.md`.
+3. Close this folder only after the verification surface says the goal is satisfied.
+4. If the work widens instead of closing, keep this folder as the promotion input and move into `/gsdd-new-project` or `/gsdd-new-milestone` explicitly.

package/distilled/templates/brownfield-change/HANDOFF.md

@@ -0,0 +1,38 @@
+---
+change: CHANGE-001
+updated: 2026-04-21
+---
+
+# Brownfield Change Handoff
+
+Use this file for rolling judgment and cross-session continuity on the active change.
+Do not duplicate milestone roadmap state here.
+Operational state still lives in `CHANGE.md`.
+This file explains constraints, uncertainty, posture, and anti-regression context; it must not become a second status or routing authority.
+If this change widens into milestone planning, this file remains the preserved judgment input to `/gsdd-new-project` or `/gsdd-new-milestone`; do not copy it into a second promotion artifact.
+
+## Active Constraints
+
+- Boundaries that the next session must keep.
+- Explicit no-touch surfaces or approval gates.
+
+## Unresolved Uncertainty
+
+- Open questions that still affect execution or verification.
+- Unknowns that are safe to keep open for now.
+
+## Decision Posture
+
+- What approach was chosen and why.
+- What was intentionally deferred.
+
+## Anti-Regression
+
+- Invariants future work must not break.
+- Contract rules that keep this lane bounded.
+
+## Next Action
+
+- Record only the decision context behind the `CHANGE.md` next action.
+- If the work is blocked, name the unblock path exactly, but keep the authoritative operational next step in `CHANGE.md`.
+- If the work widens into milestone planning, keep the why/why-not context here so the milestone workflow can reuse it without rediscovery.

package/distilled/templates/brownfield-change/VERIFICATION.md

@@ -0,0 +1,56 @@
+---
+change: CHANGE-001
+verified: 2026-04-21
+status: pending
+delivery_posture: repo_only
+required_evidence:
+  - code
+recommended_evidence:
+  - test
+---
+
+# Brownfield Change Verification
+
+Use this file as the existing proof surface even when the bounded change widens before closeout.
+Milestone-init workflows should read it for preserved proof and remaining gaps instead of forcing the user to restate what is already verified.
+
+## Goal Verification
+
+- Restate the change goal in observable terms.
+- Say whether the goal is verified, partially verified, or blocked.
+
+## Evidence
+
+List the evidence used to support closure. Use the shared evidence vocabulary:
+- `code`
+- `test`
+- `runtime`
+- `delivery`
+- `human`
+
+## Artifact Checks
+
+| Artifact | Exists | Substantive | Wired | Notes |
+| --- | --- | --- | --- | --- |
+| [path] | yes | yes | yes | [notes] |
+
+## Gaps
+
+- Missing proof, missing behavior, or unresolved blockers.
+- If required evidence is missing, say so explicitly.
+
+## Widening Reuse
+
+- Preserve already-confirmed proof when the change widens into milestone planning.
+- Carry partial verification or known gaps forward so the milestone workflow can plan from current truth.
+- Do not reset this evidence surface just because the work is moving into a larger lifecycle.
+
+## Human Verification
+
+- Manual checks still needed before closure, if any.
+
+## Closeout Decision
+
+- `passed` when the bounded change is proven complete.
+- `gaps_found` when implementation or proof is still missing.
+- `human_needed` when machine checks pass but human confirmation remains.

package/distilled/templates/codebase/architecture.md

@@ -1,110 +1,110 @@
-# Codebase Architecture
-
-**Analysis Date:** [YYYY-MM-DD]
-
-<guidelines>
-- This document is durable intent: boundaries, layering, entrypoints, and change-routing rules.
-- Do NOT write a static directory tree. It rots. Instead: reference a few canonical entrypoints and show "where changes go".
-- Every layer/abstraction must include concrete file paths.
-- Include "where to add new code" rules. This prevents downstream agents from scattering logic across random files.
-</guidelines>
-
-## Pattern Overview
-
-Overall:
-- [Pattern name]
-
-Key characteristics:
-- [Characteristic 1]
-- [Characteristic 2]
-- [Characteristic 3]
-
-## Layers (Boundaries)
-
-Layer: [Layer name]
-- Purpose: [What this layer does]
-- Location: `[path(s)]`
-- Owns: [What it is responsible for]
-- Does NOT own: [Explicit non-responsibilities]
-- Depends on: [What it uses]
-- Used by: [What uses it]
-
-## Entry Points
-
-Entrypoint: [Name]
-- Location: `[path]`
-- Triggers: [What invokes it]
-- Responsibilities: [What it does]
-
-## Data Flow (One Or Two Canonical Flows)
-
-Flow: [Name]
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-State management:
-- [How state is handled]
-
-## Key Abstractions
-
-Abstraction: [Name]
-- Purpose: [What it represents]
-- Examples: `[file paths]`
-- Pattern: [Pattern used]
-
-## Error Handling Strategy
-
-Strategy:
-- [Approach]
-- Examples: `[file paths]`
-
-## Cross-Cutting Concerns
-
-Logging:
-- [Approach] - examples: `[file paths]`
-
-Validation:
-- [Approach] - examples: `[file paths]`
-
-Authentication/Authorization:
-- [Approach] - examples: `[file paths]`
-
-## Change Routing (Where To Add New Code)
-
-When making a change, follow these rules:
-
-| Change type | Add/modify here | Do NOT do this | Example paths |
-|---|---|---|---|
-| New API endpoint / handler | [file or folder pattern] | [anti-pattern] | `[paths]` |
-| New domain capability / business rule | [location] | [anti-pattern] | `[paths]` |
-| New UI page / screen | [location] | [anti-pattern] | `[paths]` |
-| New background job / worker | [location] | [anti-pattern] | `[paths]` |
-| DB schema change / migration | [location] | [anti-pattern] | `[paths]` |
-| New external integration | [location] | [anti-pattern] | `[paths]` |
-| Adding a new module/package | [location] | [anti-pattern] | `[paths]` |
-
-<good_examples>
-Example (good):
-- "New routes live in `src/server/routes/*.ts` and are registered in `src/server/app.ts`. Business rules never go in route handlers; they live in `src/domain/*`. See `src/server/routes/users.ts` and `src/domain/user/createUser.ts`."
-
-Example (bad):
-- "Add routes wherever it makes sense."
-</good_examples>
-
-## Golden Files Per Layer
-
-For each architectural layer, identify the single most-instructive file using inbound import frequency as the signal: the most-imported file in a layer is the most stable and most understood.
-
-| Layer | Golden File | Why |
-|-------|-------------|-----|
-| [Layer name] | `[path/to/file.ts]` | [Why it's the most-imported / most-instructive for this layer] |
-| [Layer name] | `[path/to/file.ts]` | [Why] |
-| [Layer name] | `[path/to/file.ts]` | [Why] |
-
-To find the most-imported file in a layer: grep for imports of each candidate file and count occurrences. The highest count is the golden file.
-
----
-
-*Architecture analysis: [date]*
-
+# Codebase Architecture
+
+**Analysis Date:** [YYYY-MM-DD]
+
+<guidelines>
+- This document is durable intent: boundaries, layering, entrypoints, and change-routing rules.
+- Do NOT write a static directory tree. It rots. Instead: reference a few canonical entrypoints and show "where changes go".
+- Every layer/abstraction must include concrete file paths.
+- Include "where to add new code" rules. This prevents downstream agents from scattering logic across random files.
+</guidelines>
+
+## Pattern Overview
+
+Overall:
+- [Pattern name]
+
+Key characteristics:
+- [Characteristic 1]
+- [Characteristic 2]
+- [Characteristic 3]
+
+## Layers (Boundaries)
+
+Layer: [Layer name]
+- Purpose: [What this layer does]
+- Location: `[path(s)]`
+- Owns: [What it is responsible for]
+- Does NOT own: [Explicit non-responsibilities]
+- Depends on: [What it uses]
+- Used by: [What uses it]
+
+## Entry Points
+
+Entrypoint: [Name]
+- Location: `[path]`
+- Triggers: [What invokes it]
+- Responsibilities: [What it does]
+
+## Data Flow (One Or Two Canonical Flows)
+
+Flow: [Name]
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+State management:
+- [How state is handled]
+
+## Key Abstractions
+
+Abstraction: [Name]
+- Purpose: [What it represents]
+- Examples: `[file paths]`
+- Pattern: [Pattern used]
+
+## Error Handling Strategy
+
+Strategy:
+- [Approach]
+- Examples: `[file paths]`
+
+## Cross-Cutting Concerns
+
+Logging:
+- [Approach] - examples: `[file paths]`
+
+Validation:
+- [Approach] - examples: `[file paths]`
+
+Authentication/Authorization:
+- [Approach] - examples: `[file paths]`
+
+## Change Routing (Where To Add New Code)
+
+When making a change, follow these rules:
+
+| Change type | Add/modify here | Do NOT do this | Example paths |
+|---|---|---|---|
+| New API endpoint / handler | [file or folder pattern] | [anti-pattern] | `[paths]` |
+| New domain capability / business rule | [location] | [anti-pattern] | `[paths]` |
+| New UI page / screen | [location] | [anti-pattern] | `[paths]` |
+| New background job / worker | [location] | [anti-pattern] | `[paths]` |
+| DB schema change / migration | [location] | [anti-pattern] | `[paths]` |
+| New external integration | [location] | [anti-pattern] | `[paths]` |
+| Adding a new module/package | [location] | [anti-pattern] | `[paths]` |
+
+<good_examples>
+Example (good):
+- "New routes live in `src/server/routes/*.ts` and are registered in `src/server/app.ts`. Business rules never go in route handlers; they live in `src/domain/*`. See `src/server/routes/users.ts` and `src/domain/user/createUser.ts`."
+
+Example (bad):
+- "Add routes wherever it makes sense."
+</good_examples>
+
+## Golden Files Per Layer
+
+For each architectural layer, identify the single most-instructive file using inbound import frequency as the signal: the most-imported file in a layer is the most stable and most understood.
+
+| Layer | Golden File | Why |
+|-------|-------------|-----|
+| [Layer name] | `[path/to/file.ts]` | [Why it's the most-imported / most-instructive for this layer] |
+| [Layer name] | `[path/to/file.ts]` | [Why] |
+| [Layer name] | `[path/to/file.ts]` | [Why] |
+
+To find the most-imported file in a layer: grep for imports of each candidate file and count occurrences. The highest count is the golden file.
+
+---
+
+*Architecture analysis: [date]*
+

package/distilled/templates/codebase/concerns.md

@@ -1,95 +1,95 @@
-# Codebase Concerns
-
-**Analysis Date:** [YYYY-MM-DD]
-
-<guidelines>
-- Every concern must include concrete file paths.
-- Be specific with measurements (e.g., "p95 500ms") not adjectives ("slow").
-- Include reproduction steps for bugs, and "safe change" advice for fragile areas.
-- This document is about risk and leverage: what breaks, where, and how to change safely.
-</guidelines>
-
-## Tech Debt
-
-Area/component: [Name]
-- Issue: [What's the shortcut/workaround]
-- Files: `[file paths]`
-- Impact: [What breaks or degrades]
-- Fix approach: [How to address it]
-
-## Known Bugs
-
-Bug: [Description]
-- Symptoms: [What happens]
-- Files: `[file paths]`
-- Trigger: [How to reproduce]
-- Workaround: [If any]
-
-## Security Considerations
-
-Area: [Name]
-- Risk: [What could go wrong]
-- Files: `[file paths]`
-- Current mitigation: [What's in place]
-- Recommendations: [What should be added]
-
-## Performance Bottlenecks
-
-Operation: [Name]
-- Problem: [What is slow]
-- Files: `[file paths]`
-- Measurement: [numbers, if known]
-- Suspected cause: [why]
-- Improvement path: [how]
-
-## Fragile Areas
-
-Component/module: [Name]
-- Files: `[file paths]`
-- Why fragile: [what makes it break easily]
-- Safe modification: [how to change safely]
-- Test coverage: [gaps]
-
-## Dependency Risks
-
-Dependency: [Package/service]
-- Risk: [what is wrong]
-- Impact: [what breaks]
-- Mitigation: [what to do]
-
-## Missing Critical Features (If Any)
-
-Feature gap: [Name]
-- Problem: [what is missing]
-- Blocks: [what can't be done]
-
-## Test Coverage Gaps
-
-Untested area: [Name]
-- What's not tested: [specific functionality]
-- Files: `[file paths]`
-- Risk: [what could break unnoticed]
-- Priority: [High/Medium/Low]
-
-<good_examples>
-Example (good):
-- "Auth refresh tokens are stored unencrypted in `src/auth/tokenStore.ts` and logged in `src/auth/logger.ts` (risk: credential leakage). Fix: remove token logging and encrypt at rest. Repro: enable debug logging and observe tokens in logs."
-- "Checkout endpoint p95 is 1.8s in staging due to N+1 queries in `src/db/orders.ts` (see `getOrdersForUser`). Fix: batch query and add integration test asserting query count."
-</good_examples>
-
-## Downstream Impact Ranking
-
-Rank the top 3 concerns by how much future work they block. Use the Change Routing table in ARCHITECTURE.md as reference: concerns that block multiple change-routing rows rank highest.
-
-| Rank | Concern | Blocks | Severity | Fix effort |
-|------|---------|--------|----------|------------|
-| 1 | [Concern name] | [Which change types from ARCHITECTURE.md this blocks] | critical/moderate/minor | [small/medium/large] |
-| 2 | [Concern name] | [Blocks] | [Severity] | [Effort] |
-| 3 | [Concern name] | [Blocks] | [Severity] | [Effort] |
-
-Ranking heuristic: a concern that blocks 3 change-routing rows ranks above one that blocks 1, even if the latter is more severe in isolation.
-
----
-
-*Concerns audit: [date]*
-
+# Codebase Concerns
+
+**Analysis Date:** [YYYY-MM-DD]
+
+<guidelines>
+- Every concern must include concrete file paths.
+- Be specific with measurements (e.g., "p95 500ms") not adjectives ("slow").
+- Include reproduction steps for bugs, and "safe change" advice for fragile areas.
+- This document is about risk and leverage: what breaks, where, and how to change safely.
+</guidelines>
+
+## Tech Debt
+
+Area/component: [Name]
+- Issue: [What's the shortcut/workaround]
+- Files: `[file paths]`
+- Impact: [What breaks or degrades]
+- Fix approach: [How to address it]
+
+## Known Bugs
+
+Bug: [Description]
+- Symptoms: [What happens]
+- Files: `[file paths]`
+- Trigger: [How to reproduce]
+- Workaround: [If any]
+
+## Security Considerations
+
+Area: [Name]
+- Risk: [What could go wrong]
+- Files: `[file paths]`
+- Current mitigation: [What's in place]
+- Recommendations: [What should be added]
+
+## Performance Bottlenecks
+
+Operation: [Name]
+- Problem: [What is slow]
+- Files: `[file paths]`
+- Measurement: [numbers, if known]
+- Suspected cause: [why]
+- Improvement path: [how]
+
+## Fragile Areas
+
+Component/module: [Name]
+- Files: `[file paths]`
+- Why fragile: [what makes it break easily]
+- Safe modification: [how to change safely]
+- Test coverage: [gaps]
+
+## Dependency Risks
+
+Dependency: [Package/service]
+- Risk: [what is wrong]
+- Impact: [what breaks]
+- Mitigation: [what to do]
+
+## Missing Critical Features (If Any)
+
+Feature gap: [Name]
+- Problem: [what is missing]
+- Blocks: [what can't be done]
+
+## Test Coverage Gaps
+
+Untested area: [Name]
+- What's not tested: [specific functionality]
+- Files: `[file paths]`
+- Risk: [what could break unnoticed]
+- Priority: [High/Medium/Low]
+
+<good_examples>
+Example (good):
+- "Auth refresh tokens are stored unencrypted in `src/auth/tokenStore.ts` and logged in `src/auth/logger.ts` (risk: credential leakage). Fix: remove token logging and encrypt at rest. Repro: enable debug logging and observe tokens in logs."
+- "Checkout endpoint p95 is 1.8s in staging due to N+1 queries in `src/db/orders.ts` (see `getOrdersForUser`). Fix: batch query and add integration test asserting query count."
+</good_examples>
+
+## Downstream Impact Ranking
+
+Rank the top 3 concerns by how much future work they block. Use the Change Routing table in ARCHITECTURE.md as reference: concerns that block multiple change-routing rows rank highest.
+
+| Rank | Concern | Blocks | Severity | Fix effort |
+|------|---------|--------|----------|------------|
+| 1 | [Concern name] | [Which change types from ARCHITECTURE.md this blocks] | critical/moderate/minor | [small/medium/large] |
+| 2 | [Concern name] | [Blocks] | [Severity] | [Effort] |
+| 3 | [Concern name] | [Blocks] | [Severity] | [Effort] |
+
+Ranking heuristic: a concern that blocks 3 change-routing rows ranks above one that blocks 1, even if the latter is more severe in isolation.
+
+---
+
+*Concerns audit: [date]*
+