gsdd-cli 0.18.5 → 0.19.1

package/distilled/templates/auth-matrix.md

@@ -1,78 +1,78 @@
-# Authorization Matrix Template
-
-> OWASP-style authorization matrix for systematic auth verification.
-> Create `.planning/AUTH_MATRIX.md` using this template when your project has multiple user roles or protected resources.
-
-## When to Create This Matrix
-
-Create an authorization matrix when your project has:
-- Multiple user roles (e.g., anonymous, user, admin, owner)
-- Protected resources that vary by role
-- Ownership-scoped data (users can only access their own records)
-- Admin or operator surfaces that must be restricted
-
-Skip this matrix for single-role projects or projects with no auth requirements.
-
-## Matrix Format
-
-Use the OWASP pivot format: rows are resources, columns are roles, cells are permissions.
-
-### Permission Values
-
-| Value | Meaning |
-|-------|---------|
-| ALLOW | Role can perform this action on any matching resource |
-| DENY  | Role must be explicitly rejected (not just "no route") |
-| OWN   | Role can perform this action only on resources they own |
-| N/A   | Action does not apply to this resource |
-
-### Matrix Table
-
-```markdown
-| Resource | Action | anonymous | user | admin |
-|----------|--------|-----------|------|-------|
-| /login   | POST   | ALLOW     | ALLOW| ALLOW |
-| /profile | GET    | DENY      | OWN  | ALLOW |
-| /profile | PUT    | DENY      | OWN  | ALLOW |
-| /users   | GET    | DENY      | DENY | ALLOW |
-| /users   | DELETE | DENY      | DENY | ALLOW |
-| /posts   | GET    | ALLOW     | ALLOW| ALLOW |
-| /posts   | POST   | DENY      | ALLOW| ALLOW |
-| /posts   | DELETE | DENY      | OWN  | ALLOW |
-```
-
-Adapt the table to your project's actual resources, actions, and roles. Add or remove columns as needed.
-
-## Sensitive Surfaces
-
-The following resource categories MUST have matrix coverage when they exist in your project:
-
-- **User-scoped data** (profiles, settings, personal records) — require OWN or DENY
-- **Admin surfaces** (user management, system config, audit logs) — require DENY for non-admin roles
-- **Financial data** (billing, payments, subscriptions) — require explicit DENY or OWN
-- **Destructive actions** (delete, bulk operations, account removal) — require explicit role gates
-- **API keys and credentials** — require DENY for non-owner roles
-
-If a sensitive surface exists in your codebase but is missing from the matrix, the integration checker's narrative auth check (Step 4) will still flag it — Step 4 runs unconditionally regardless of whether this matrix exists. Step 4a only verifies cells that are already in the matrix.
-
-## How the Integration Checker Uses This Matrix
-
-During milestone audits, the integration checker (Step 4a) will:
-
-1. Parse each row of the matrix table(s)
-2. For each cell (resource x role x expected permission):
-   - **ALLOW**: Verify the role can access the resource (no auth gate blocks it)
-   - **DENY**: Verify explicit rejection exists (middleware, guard, or policy denies access)
-   - **OWN**: Verify ownership check is enforced (not just auth, but scoped to the user's records)
-3. Report each cell as:
-   - **VERIFIED**: Implementation matches the matrix expectation
-   - **MISMATCH**: Implementation contradicts the matrix (e.g., DENY expected but no guard found)
-   - **UNTESTED**: Cannot determine from static analysis (e.g., dynamic policy evaluation)
-
-The narrative auth check (Step 4) always runs regardless of whether this matrix exists.
-
-## File Location
-
-Save your project's authorization matrix as `.planning/AUTH_MATRIX.md`.
-
-The integration checker will automatically detect and consume it when present. No configuration needed.
+# Authorization Matrix Template
+
+> OWASP-style authorization matrix for systematic auth verification.
+> Create `.planning/AUTH_MATRIX.md` using this template when your project has multiple user roles or protected resources.
+
+## When to Create This Matrix
+
+Create an authorization matrix when your project has:
+- Multiple user roles (e.g., anonymous, user, admin, owner)
+- Protected resources that vary by role
+- Ownership-scoped data (users can only access their own records)
+- Admin or operator surfaces that must be restricted
+
+Skip this matrix for single-role projects or projects with no auth requirements.
+
+## Matrix Format
+
+Use the OWASP pivot format: rows are resources, columns are roles, cells are permissions.
+
+### Permission Values
+
+| Value | Meaning |
+|-------|---------|
+| ALLOW | Role can perform this action on any matching resource |
+| DENY  | Role must be explicitly rejected (not just "no route") |
+| OWN   | Role can perform this action only on resources they own |
+| N/A   | Action does not apply to this resource |
+
+### Matrix Table
+
+```markdown
+| Resource | Action | anonymous | user | admin |
+|----------|--------|-----------|------|-------|
+| /login   | POST   | ALLOW     | ALLOW| ALLOW |
+| /profile | GET    | DENY      | OWN  | ALLOW |
+| /profile | PUT    | DENY      | OWN  | ALLOW |
+| /users   | GET    | DENY      | DENY | ALLOW |
+| /users   | DELETE | DENY      | DENY | ALLOW |
+| /posts   | GET    | ALLOW     | ALLOW| ALLOW |
+| /posts   | POST   | DENY      | ALLOW| ALLOW |
+| /posts   | DELETE | DENY      | OWN  | ALLOW |
+```
+
+Adapt the table to your project's actual resources, actions, and roles. Add or remove columns as needed.
+
+## Sensitive Surfaces
+
+The following resource categories MUST have matrix coverage when they exist in your project:
+
+- **User-scoped data** (profiles, settings, personal records) — require OWN or DENY
+- **Admin surfaces** (user management, system config, audit logs) — require DENY for non-admin roles
+- **Financial data** (billing, payments, subscriptions) — require explicit DENY or OWN
+- **Destructive actions** (delete, bulk operations, account removal) — require explicit role gates
+- **API keys and credentials** — require DENY for non-owner roles
+
+If a sensitive surface exists in your codebase but is missing from the matrix, the integration checker's narrative auth check (Step 4) will still flag it — Step 4 runs unconditionally regardless of whether this matrix exists. Step 4a only verifies cells that are already in the matrix.
+
+## How the Integration Checker Uses This Matrix
+
+During milestone audits, the integration checker (Step 4a) will:
+
+1. Parse each row of the matrix table(s)
+2. For each cell (resource x role x expected permission):
+   - **ALLOW**: Verify the role can access the resource (no auth gate blocks it)
+   - **DENY**: Verify explicit rejection exists (middleware, guard, or policy denies access)
+   - **OWN**: Verify ownership check is enforced (not just auth, but scoped to the user's records)
+3. Report each cell as:
+   - **VERIFIED**: Implementation matches the matrix expectation
+   - **MISMATCH**: Implementation contradicts the matrix (e.g., DENY expected but no guard found)
+   - **UNTESTED**: Cannot determine from static analysis (e.g., dynamic policy evaluation)
+
+The narrative auth check (Step 4) always runs regardless of whether this matrix exists.
+
+## File Location
+
+Save your project's authorization matrix as `.planning/AUTH_MATRIX.md`.
+
+The integration checker will automatically detect and consume it when present. No configuration needed.

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]*
+