gsd-pi 2.10.12 → 2.12.0

package/dist/resources/extensions/gsd/templates/milestone-summary.md

@@ -0,0 +1,73 @@
+---
+id: {{milestoneId}}
+provides:
+  - {{whatThisMilestoneProvides}}
+key_decisions:
+  - {{decision}}
+patterns_established:
+  - {{pattern}}
+observability_surfaces:
+  - {{status endpoint, structured log, persisted failure state, diagnostic command, or none}}
+requirement_outcomes:
+  - id: {{requirementId}}
+    from_status: {{active|blocked|deferred}}
+    to_status: {{validated|deferred|blocked|out_of_scope}}
+    proof: {{whatEvidenceSupportsThisTransition}}
+duration: {{duration}}
+verification_result: passed
+completed_at: {{date}}
+---
+
+# {{milestoneId}}: {{milestoneTitle}}
+
+<!-- One-liner must say what the milestone actually delivered, not just that it completed.
+     Good: "State machine integrity with completing-milestone gating, doctor audits, and observability validation"
+     Bad: "Milestone 2 completed" -->
+
+**{{oneLiner}}**
+
+## What Happened
+
+<!-- Cross-slice narrative: compress all slice summaries into a coherent story.
+     Focus on what was built, how the slices connected, and what the milestone
+     achieved as a whole — not a task-by-task replay. -->
+
+{{crossSliceNarrative}}
+
+## Cross-Slice Verification
+
+<!-- How were the milestone's success criteria verified?
+     Reference specific tests, commands, browser checks, or observable behaviors.
+     Each success criterion from the roadmap should have a corresponding verification entry. -->
+
+{{howSuccessCriteriaWereVerified}}
+
+## Requirement Changes
+
+<!-- Transitions with evidence. Each requirement that changed status during this milestone
+     should be listed with the proof that supports the transition. -->
+
+- {{requirementId}}: {{fromStatus}} → {{toStatus}} — {{evidence}}
+
+## Forward Intelligence
+
+<!-- Write what you wish you'd known at the start of this milestone.
+     This section is read by the next milestone's planning and research steps.
+     Be specific and concrete — this is the most valuable context you can transfer. -->
+
+### What the next milestone should know
+- {{insightThatWouldHelpDownstreamWork}}
+
+### What's fragile
+- {{fragileAreaOrThinImplementation}} — {{whyItMatters}}
+
+### Authoritative diagnostics
+- {{whereAFutureAgentShouldLookFirst}} — {{whyThisSignalIsTrustworthy}}
+
+### What assumptions changed
+- {{originalAssumption}} — {{whatActuallyHappened}}
+
+## Files Created/Modified
+
+- `{{filePath}}` — {{description}}
+- `{{filePath}}` — {{description}}

package/dist/resources/extensions/gsd/templates/plan.md

@@ -0,0 +1,131 @@
+# {{sliceId}}: {{sliceTitle}}
+
+**Goal:** {{goal}}
+**Demo:** {{demo}}
+
+## Must-Haves
+
+- {{mustHave}}
+- {{mustHave}}
+
+## Proof Level
+
+<!-- Omit this section entirely for simple slices where the answer is trivially obvious. -->
+
+- This slice proves: {{contract | integration | operational | final-assembly}}
+- Real runtime required: {{yes/no}}
+- Human/UAT required: {{yes/no}}
+
+## Verification
+
+<!-- Define what "done" looks like BEFORE detailing tasks.
+     This section is the slice's objective stopping condition — execution isn't done
+     until everything here passes.
+
+     For non-trivial projects:
+     - Write actual test files into the codebase during the first task
+     - Tests should assert on the slice's demo outcome and boundary contracts
+     - Name the test files here so execution has an unambiguous target
+
+     For simple projects or scripts:
+     - Executable verification commands (bash assertions, curl checks, etc.) are sufficient
+
+     If the project has no test framework and the work is non-trivial,
+     the first task should set one up. A test runner costs 2 minutes
+     and pays for itself immediately.
+
+     For non-trivial backend, integration, async, stateful, or UI work:
+     - Include at least one verification check for an observability or failure-path signal
+     - Verify not just that the feature works, but that a future agent can inspect its state when it fails -->
+
+- {{testFileOrCommand — e.g. `npm test -- --grep "auth flow"` or `bash scripts/verify-s01.sh`}}
+- {{testFileOrCommand}}
+
+## Observability / Diagnostics
+
+<!-- Include this section for non-trivial backend, integration, async, stateful, or UI slices.
+     OMIT ENTIRELY for simple slices where all fields would be "none".
+
+     When included, describe how a future agent will inspect current state, detect failure,
+     and localize the problem with minimal ambiguity. Keep it concise and high-signal. -->
+
+- Runtime signals: {{structured log/event, state transition, metric, or none}}
+- Inspection surfaces: {{status endpoint, CLI command, script, UI state, DB table, or none}}
+- Failure visibility: {{last error, retry count, phase, timestamp, correlation id, or none}}
+- Redaction constraints: {{secret/PII boundary or none}}
+
+## Integration Closure
+
+<!-- Omit this section entirely for simple slices with no meaningful integration concerns. -->
+
+- Upstream surfaces consumed: {{specific files / modules / contracts}}
+- New wiring introduced in this slice: {{entrypoint / composition / runtime hookup, or none}}
+- What remains before the milestone is truly usable end-to-end: {{list or "nothing"}}
+
+## Tasks
+
+<!--
+  If every task below is completed exactly as written, the Goal and Demo above
+  should be true at the stated proof level. Tasks should close the loop on the
+  slice, not merely prepare for later work unless the Demo truthfully says the
+  slice only proves fixture/contract-level behavior.
+
+  Write each task as an executable increment, not a vague intention.
+
+  Prefer action-oriented titles:
+  - "Wire real auth middleware into dashboard routes"
+  - "Persist job status and expose failure diagnostics"
+  - "Add browser test covering empty-state recovery"
+
+  Avoid vague titles:
+  - "Set up auth"
+  - "Handle errors"
+  - "Improve UI"
+
+  Each task should usually include:
+  - Why: why this task exists / what part of the slice it closes
+  - Files: the main files likely touched
+  - Do: concrete implementation steps and important constraints
+  - Verify: the command, test, or runtime check that proves it worked
+  - Done when: a measurable acceptance condition
+
+  Keep the checkbox line format exactly:
+  - [ ] **T01: Title** `est:30m`
+-->
+
+- [ ] **T01: {{taskTitle}}** `est:{{estimate}}`
+  - Why: {{whyThisTaskExists}}
+  - Files: `{{filePath}}`, `{{filePath}}`
+  - Do: {{specificImplementationStepsAndConstraints}}
+  - Verify: {{testCommandOrRuntimeCheck}}
+  - Done when: {{measurableAcceptanceCondition}}
+- [ ] **T02: {{taskTitle}}** `est:{{estimate}}`
+  - Why: {{whyThisTaskExists}}
+  - Files: `{{filePath}}`, `{{filePath}}`
+  - Do: {{specificImplementationStepsAndConstraints}}
+  - Verify: {{testCommandOrRuntimeCheck}}
+  - Done when: {{measurableAcceptanceCondition}}
+- [ ] **T03: {{taskTitle}}** `est:{{estimate}}`
+  - Why: {{whyThisTaskExists}}
+  - Files: `{{filePath}}`, `{{filePath}}`
+  - Do: {{specificImplementationStepsAndConstraints}}
+  - Verify: {{testCommandOrRuntimeCheck}}
+  - Done when: {{measurableAcceptanceCondition}}
+
+<!--
+  Format rules (parsers depend on this exact structure):
+  - Checkbox line: - [ ] **T01: Title** `est:30m`
+  - Description:   indented text on the next line(s)
+  - Mark done:     change [ ] to [x]
+  - Tasks execute sequentially in order (T01, T02, T03, ...)
+  - est: is informational (e.g. 30m, 1h, 2h) and optional
+
+  Integration closure rule:
+  - At least one slice in any multi-boundary milestone should perform real composition/wiring, not just contract hardening
+  - For the final assembly slice, verification must exercise the real entrypoint or runtime path
+-->
+
+## Files Likely Touched
+
+- `{{filePath}}`
+- `{{filePath}}`

package/dist/resources/extensions/gsd/templates/preferences.md

@@ -0,0 +1,23 @@
+---
+version: 1
+always_use_skills: []
+prefer_skills: []
+avoid_skills: []
+skill_rules: []
+custom_instructions: []
+models: {}
+skill_discovery:
+auto_supervisor: {}
+git:
+  auto_push:
+  push_branches:
+  remote:
+  snapshots:
+  pre_merge_check:
+  commit_type:
+unique_milestone_ids:
+---
+
+# GSD Skill Preferences
+
+See `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.

package/dist/resources/extensions/gsd/templates/project.md

@@ -0,0 +1,31 @@
+# Project
+
+## What This Is
+
+{{whatTheProjectDoes — plain language, current state, not aspirational}}
+
+## Core Value
+
+<!-- This is the primary value anchor for prioritization and tradeoffs.
+     If scope must shrink, this should survive. -->
+
+{{theOneThingThatMustWorkEvenIfEverythingElseIsCut}}
+
+## Current State
+
+{{whatHasBeenBuiltSoFar — what works, what exists, what's deployed}}
+
+## Architecture / Key Patterns
+
+{{howItsStructured — conventions, tech stack, key modules, established patterns}}
+
+## Capability Contract
+
+See `.gsd/REQUIREMENTS.md` for the explicit capability contract, requirement status, and coverage mapping.
+
+## Milestone Sequence
+
+<!-- Check off milestones as they complete. One-liners should describe intent, not implementation detail. -->
+
+- [ ] M001: {{title}} — {{oneLiner}}
+- [ ] M002: {{title}} — {{oneLiner}}

package/dist/resources/extensions/gsd/templates/reassessment.md

@@ -0,0 +1,28 @@
+---
+date: {{YYYY-MM-DD}}
+triggering_slice: {{milestoneId/sliceId}}
+verdict: {{no-change | modified}}
+---
+
+# Reassessment: {{triggering_slice}}
+
+## Changes Made
+
+<!-- What changed in the roadmap as a result of this reassessment.
+     Write "No changes." if verdict is no-change. -->
+
+{{placeholder}}
+
+## Requirement Coverage Impact
+
+<!-- Which requirements were added, removed, deferred, or reordered.
+     Write "None." if no requirements were affected. -->
+
+{{placeholder}}
+
+## Decision References
+
+<!-- D-numbers from DECISIONS.md that informed or resulted from this reassessment.
+     Write "None." if no recorded decisions apply. -->
+
+{{placeholder}}

package/dist/resources/extensions/gsd/templates/requirements.md

@@ -0,0 +1,81 @@
+# Requirements
+
+This file is the explicit capability and coverage contract for the project.
+
+Use it to track what is actively in scope, what has been validated by completed work, what is intentionally deferred, and what is explicitly out of scope.
+
+Guidelines:
+- Keep requirements capability-oriented, not a giant feature wishlist.
+- Requirements should be atomic, testable, and stated in plain language.
+- Every **Active** requirement should be mapped to a slice, deferred, blocked with reason, or moved out of scope.
+- Each requirement should have one accountable primary owner and may have supporting slices.
+- Research may suggest requirements, but research does not silently make them binding.
+- Validation means the requirement was actually proven by completed work and verification, not just discussed.
+
+## Active
+
+### R001 — {{requirementTitle}}
+- Class: {{core-capability | primary-user-loop | launchability | continuity | failure-visibility | integration | quality-attribute | operability | admin/support | compliance/security | differentiator | constraint | anti-feature}}
+- Status: active
+- Description: {{what must be true in plain language}}
+- Why it matters: {{why this matters to actual product usefulness/completeness}}
+- Source: {{user | inferred | research | execution}}
+- Primary owning slice: {{M001/S01 | none yet}}
+- Supporting slices: {{M001/S02, M001/S03 | none}}
+- Validation: {{unmapped | mapped | partial | validated}}
+- Notes: {{constraints / acceptance nuance / why not yet validated}}
+
+## Validated
+
+### R010 — {{requirementTitle}}
+- Class: {{failure-visibility}}
+- Status: validated
+- Description: {{what was proven}}
+- Why it matters: {{why it matters}}
+- Source: {{user | inferred | research | execution}}
+- Primary owning slice: {{M001/S01}}
+- Supporting slices: {{none}}
+- Validation: validated
+- Notes: {{what verification proved this}}
+
+## Deferred
+
+### R020 — {{requirementTitle}}
+- Class: {{admin/support}}
+- Status: deferred
+- Description: {{useful later, not now}}
+- Why it matters: {{why it might matter later}}
+- Source: {{user | inferred | research | execution}}
+- Primary owning slice: {{none}}
+- Supporting slices: {{none}}
+- Validation: unmapped
+- Notes: {{why deferred now}}
+
+## Out of Scope
+
+### R030 — {{requirementTitle}}
+- Class: {{anti-feature | constraint | core-capability}}
+- Status: out-of-scope
+- Description: {{what is explicitly excluded}}
+- Why it matters: {{what scope confusion this prevents}}
+- Source: {{user | inferred | research | execution}}
+- Primary owning slice: {{none}}
+- Supporting slices: {{none}}
+- Validation: n/a
+- Notes: {{why excluded}}
+
+## Traceability
+
+| ID | Class | Status | Primary owner | Supporting | Proof |
+|---|---|---|---|---|---|
+| R001 | primary-user-loop | active | M001/S01 | none | mapped |
+| R010 | failure-visibility | validated | M001/S01 | none | validated |
+| R020 | admin/support | deferred | none | none | unmapped |
+| R030 | anti-feature | out-of-scope | none | none | n/a |
+
+## Coverage Summary
+
+- Active requirements: {{count}}
+- Mapped to slices: {{count}}
+- Validated: {{count}}
+- Unmapped active requirements: {{count}}

package/dist/resources/extensions/gsd/templates/research.md

@@ -0,0 +1,46 @@
+# {{scope}} — Research
+
+**Date:** {{date}}
+
+## Summary
+
+{{summary — 2-3 paragraphs with primary recommendation}}
+
+## Recommendation
+
+{{whatApproachToTake_AND_why}}
+
+## Don't Hand-Roll
+
+| Problem | Existing Solution | Why Use It |
+|---------|------------------|------------|
+| {{problem}} | {{solution}} | {{why}} |
+
+## Existing Code and Patterns
+
+- `{{filePath}}` — {{whatItDoesAndHowToReuseIt}}
+- `{{filePath}}` — {{patternToFollowOrAvoid}}
+
+## Constraints
+
+- {{hardConstraintFromCodebaseOrRuntime}}
+- {{constraintFromDependencies}}
+
+## Common Pitfalls
+
+- **{{pitfall}}** — {{howToAvoid}}
+- **{{pitfall}}** — {{howToAvoid}}
+
+## Open Risks
+
+- {{riskThatCouldSurfaceDuringExecution}}
+
+## Skills Discovered
+
+| Technology | Skill | Status |
+|------------|-------|--------|
+| {{technology}} | {{owner/repo@skill}} | {{installed / available / none found}} |
+
+## Sources
+
+- {{whatWasLearned}} (source: [{{title}}]({{url}}))

package/dist/resources/extensions/gsd/templates/roadmap.md

@@ -0,0 +1,118 @@
+# {{milestoneId}}: {{milestoneTitle}}
+
+**Vision:** {{vision}}
+
+## Success Criteria
+
+<!-- Write success criteria as observable truths, not implementation tasks.
+     Prefer user-visible or runtime-visible outcomes that can be re-checked at
+     milestone completion.
+
+     Good:
+     - "User can complete the full import flow end-to-end"
+     - "The daemon reconnects automatically after restart"
+
+     Bad:
+     - "Add import API and UI"
+     - "Refactor reconnect logic" -->
+
+- {{criterion}}
+- {{criterion}}
+
+## Key Risks / Unknowns
+
+<!-- List the real risks and uncertainties that shape how slices are ordered.
+     If the project is straightforward, this section can be short or empty.
+     Don't invent risks — only list things that could actually invalidate downstream work. -->
+
+- {{risk}} — {{whyItMatters}}
+- {{risk}} — {{whyItMatters}}
+
+## Proof Strategy
+
+<!-- For each real risk above, name which slice retires it and what "proven" looks like.
+     Proof comes from building the real thing, not from spikes or research.
+     Skip this section for straightforward projects with no major unknowns. -->
+
+- {{riskOrUnknown}} → retire in {{sliceId}} by proving {{whatWillBeProven}}
+- {{riskOrUnknown}} → retire in {{sliceId}} by proving {{whatWillBeProven}}
+
+## Verification Classes
+
+- Contract verification: {{tests / shell verifiers / fixtures / artifact checks}}
+- Integration verification: {{real subsystem interaction that must be exercised, or none}}
+- Operational verification: {{service lifecycle / restart / reconnect / supervision / deploy-install behavior, or none}}
+- UAT / human verification: {{what needs real human judgment, or none}}
+
+## Milestone Definition of Done
+
+This milestone is complete only when all are true:
+
+- {{all slice deliverables are complete}}
+- {{shared components are actually wired together}}
+- {{the real entrypoint exists and is exercised}}
+- {{success criteria are re-checked against live behavior, not just artifacts}}
+- {{final integrated acceptance scenarios pass}}
+
+## Requirement Coverage
+
+- Covers: {{R001, R002}}
+- Partially covers: {{R003 or none}}
+- Leaves for later: {{R004 or none}}
+- Orphan risks: {{none or what is still unmapped}}
+
+## Slices
+
+- [ ] **S01: {{sliceTitle}}** `risk:high` `depends:[]`
+  > After this: {{whatIsDemoableWhenThisSliceIsDone}}
+- [ ] **S02: {{sliceTitle}}** `risk:medium` `depends:[S01]`
+  > After this: {{whatIsDemoableWhenThisSliceIsDone}}
+- [ ] **S03: {{sliceTitle}}** `risk:low` `depends:[S01]`
+  > After this: {{whatIsDemoableWhenThisSliceIsDone}}
+
+<!--
+  Format rules (parsers depend on this exact structure):
+  - Checkbox line: - [ ] **S01: Title** `risk:high|medium|low` `depends:[S01,S02]`
+  - Demo line:     >  After this: one sentence showing what's demoable
+  - Mark done:     change [ ] to [x]
+  - Order slices by risk (highest first)
+  - Each slice must be a vertical, demoable increment — not a layer
+  - If all slices are completed exactly as written, the milestone's promised outcome should actually work at the stated proof level
+  - depends:[X,Y] means X and Y must be done before this slice starts
+
+  Planning quality rules:
+  - Every slice must ship real, working, demoable code — no research-only or foundation-only slices
+  - Early slices should prove the hardest thing works by building through the uncertain path
+  - Each slice should establish a stable surface that downstream slices can depend on
+  - Demo lines should describe concrete, verifiable evidence — not vague claims
+  - In brownfield projects, ground slices in existing modules and patterns
+  - If a slice doesn't produce something testable end-to-end, it's probably a layer — restructure it
+  - If the milestone crosses multiple runtime boundaries (for example daemon + API + UI, bot + subprocess + service manager, or extension + RPC + filesystem), include an explicit final integration slice that proves the assembled system works end-to-end in a real environment
+  - Contract or fixture proof does not replace final assembly proof when the user-visible outcome depends on live wiring
+  - Each "After this" line must be truthful about proof level: if only fixtures or tests prove it, say so; do not imply the user can already perform the live end-to-end behavior unless that has actually been exercised
+-->
+
+## Boundary Map
+
+<!-- Be specific. Name concrete outputs: API endpoints, event payloads, shared types/interfaces,
+     persisted record shapes, CLI contracts, file formats, or invariants.
+     "Produces: auth system" is too vague. "Produces: session middleware that attaches
+     authenticated user to request context" is useful.
+     Consumes should name what downstream slices assume is already available and stable.
+     If the project has a test framework, boundary contracts should ideally be exercised by tests. -->
+
+### S01 → S02
+
+Produces:
+- {{concreteOutput — API, type, data shape, interface, or invariant}}
+
+Consumes:
+- nothing (first slice)
+
+### S01 → S03
+
+Produces:
+- {{concreteOutput — API, type, data shape, interface, or invariant}}
+
+Consumes:
+- nothing (first slice)

package/dist/resources/extensions/gsd/templates/secrets-manifest.md

@@ -0,0 +1,22 @@
+# Secrets Manifest
+
+<!-- This file lists predicted API keys and secrets for the milestone.
+     Each H3 section defines one secret with setup guidance.
+     The parser extracts entries by H3 heading (the env var name).
+     Bold fields: Service, Dashboard, Format hint, Status, Destination.
+     Guidance is a numbered list under each entry. -->
+
+**Milestone:** {{milestone}}
+**Generated:** {{generatedAt}}
+
+### {{ENV_VAR_NAME}}
+
+**Service:** {{serviceName}}
+**Dashboard:** {{dashboardUrl}}
+**Format hint:** {{formatHint}}
+**Status:** pending
+**Destination:** dotenv
+
+1. {{Step 1 guidance}}
+2. {{Step 2 guidance}}
+3. {{Step 3 guidance}}

package/dist/resources/extensions/gsd/templates/slice-context.md

@@ -0,0 +1,58 @@
+---
+id: {{sliceId}}
+milestone: {{milestoneId}}
+status: {{draft|ready|in_progress|complete}}
+---
+
+# {{sliceId}}: {{sliceTitle}} — Context
+
+<!-- Slice-scoped context. Milestone-only sections (acceptance criteria, completion class,
+     milestone sequence) do not belong here — those live in the milestone context. -->
+
+## Goal
+
+<!-- One sentence: what this slice delivers when it is done. -->
+
+{{sliceGoal}}
+
+## Why this Slice
+
+<!-- Why this slice is being done now. What does it unblock, and why does order matter? -->
+
+{{whyNowAndWhatItUnblocks}}
+
+## Scope
+
+<!-- What is and is not in scope for this slice. Be explicit about non-goals. -->
+
+### In Scope
+
+- {{inScopeItem}}
+
+### Out of Scope
+
+- {{outOfScopeItem}}
+
+## Constraints
+
+<!-- Known constraints: time-boxes, hard dependencies, prior decisions this slice must respect. -->
+
+- {{constraint}}
+
+## Integration Points
+
+<!-- Artifacts or subsystems this slice consumes and produces. -->
+
+### Consumes
+
+- `{{fileOrArtifact}}` — {{howItIsUsed}}
+
+### Produces
+
+- `{{fileOrArtifact}}` — {{whatItProvides}}
+
+## Open Questions
+
+<!-- Unresolved questions at planning time. Answer them before or during execution. -->
+
+- {{question}} — {{currentThinking}}