gsd-antigravity-kit 1.32.0 → 2.0.0

package/.agent/skills/gsd/references/workflows/execute-phase.md

@@ -25,6 +25,10 @@ via filesystem and git state.
 
 <required_reading>
 Read STATE.md before any operation to load project context.
+
+@references/docs/agent-contracts.md
+@references/docs/context-budget.md
+@references/docs/gates.md
 </required_reading>
 
 <available_agent_types>
@@ -482,12 +486,55 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
      if [ -n "$WT_BRANCH" ] && [ "$WT_BRANCH" != "HEAD" ]; then
        CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
 
+       # --- Orchestrator file protection (#1756) ---
+       # Snapshot orchestrator-owned files BEFORE merge. If the worktree
+       # branch outlived a milestone transition, its versions of STATE.md
+       # and ROADMAP.md are stale. Main always wins for these files.
+       STATE_BACKUP=$(mktemp)
+       ROADMAP_BACKUP=$(mktemp)
+       git show HEAD:.planning/STATE.md > "$STATE_BACKUP" 2>/dev/null || true
+       git show HEAD:.planning/ROADMAP.md > "$ROADMAP_BACKUP" 2>/dev/null || true
+
+       # Snapshot list of files on main BEFORE merge to detect resurrections
+       PRE_MERGE_FILES=$(git ls-files .planning/)
+
        # Merge the worktree branch into the current branch
        git merge "$WT_BRANCH" --no-edit -m "chore: merge executor worktree ($WT_BRANCH)" 2>&1 || {
          echo "⚠ Merge conflict from worktree $WT_BRANCH — resolve manually"
+         rm -f "$STATE_BACKUP" "$ROADMAP_BACKUP"
          continue
        }
 
+       # Restore orchestrator-owned files (main always wins)
+       if [ -s "$STATE_BACKUP" ]; then
+         cp "$STATE_BACKUP" .planning/STATE.md
+       fi
+       if [ -s "$ROADMAP_BACKUP" ]; then
+         cp "$ROADMAP_BACKUP" .planning/ROADMAP.md
+       fi
+       rm -f "$STATE_BACKUP" "$ROADMAP_BACKUP"
+
+       # Detect files deleted on main but re-added by worktree merge
+       # (e.g., archived phase directories that were intentionally removed)
+       DELETED_FILES=$(git diff --diff-filter=A --name-only HEAD~1 -- .planning/ 2>/dev/null || true)
+       for RESURRECTED in $DELETED_FILES; do
+         # Check if this file was NOT in main's pre-merge tree
+         if ! echo "$PRE_MERGE_FILES" | grep -qxF "$RESURRECTED"; then
+           git rm -f "$RESURRECTED" 2>/dev/null || true
+         fi
+       done
+
+       # Amend merge commit with restored files if any changed
+       if ! git diff --quiet .planning/STATE.md .planning/ROADMAP.md 2>/dev/null || \
+          [ -n "$DELETED_FILES" ]; then
+         # Only amend the commit with .planning/ files if commit_docs is enabled (#1783)
+.agent/skills/gsd/bin/gsd-tools.cjs" config-get commit_docs 2>/dev/null || echo "true")
+         if [ "$COMMIT_DOCS" != "false" ]; then
+           git add .planning/STATE.md .planning/ROADMAP.md 2>/dev/null || true
+           git commit --amend --no-edit 2>/dev/null || true
+         fi
+       fi
+
        # Remove the worktree
        git worktree remove "$WT" --force 2>/dev/null || true
 
@@ -694,6 +741,39 @@ Selected wave finished successfully. This phase still has incomplete plans, so p
 - this means the selected wave happened to be the last remaining work in the phase
 </step>
 
+<step name="code_review_gate" required="true">
+**This step is REQUIRED and must not be skipped.** Auto-invoke code review on the phase's source changes. Advisory only — never blocks execution flow.
+
+**Config gate:**
+```bash
+.agent/skills/gsd/bin/gsd-tools.cjs" config-get workflow.code_review 2>/dev/null || echo "true")
+```
+
+If `CODE_REVIEW_ENABLED` is `"false"`: display "Code review skipped (workflow.code_review=false)" and proceed to next step.
+
+**Invoke review:**
+```
+Skill(skill="gsd:code-review", args="${PHASE_NUMBER}")
+```
+
+**Check results using deterministic path (not glob):**
+```bash
+PADDED=$(printf "%02d" "${PHASE_NUMBER}")
+REVIEW_FILE="${PHASE_DIR}/${PADDED}-REVIEW.md"
+REVIEW_STATUS=$(sed -n '/^---$/,/^---$/p' "$REVIEW_FILE" | grep "^status:" | head -1 | cut -d: -f2 | tr -d ' ')
+```
+
+If REVIEW_STATUS is not "clean" and not "skipped" and not empty, display:
+```
+Code review found issues. Consider running:
+/gsd-code-review-fix ${PHASE_NUMBER}
+```
+
+**Error handling:** If the Skill invocation fails or throws, catch the error, display "Code review encountered an error (non-blocking): {error}" and proceed to next step. Review failures must never block execution.
+
+Regardless of review result, ALWAYS proceed to close_parent_artifacts → regression_gate → verify_phase_goal.
+</step>
+
 <step name="close_parent_artifacts">
 **For decimal/polish phases only (X.Y pattern):** Close the feedback loop by resolving parent UAT and debug artifacts.
 
@@ -1034,6 +1114,29 @@ These items are tracked and will appear in `/gsd-progress` and `/gsd-audit-uat`.
 ```
 </step>
 
+<step name="auto_copy_learnings">
+**Auto-copy phase learnings to global store (when enabled).**
+
+This step runs AFTER phase completion and SUMMARY.md is written. It copies any LEARNINGS.md
+entries from the completed phase to the global learnings store at `~/.gsd/knowledge/`.
+
+**Check config gate:**
+```bash
+.agent/skills/gsd/bin/gsd-tools.cjs" config-get features.global_learnings --raw 2>/dev/null || echo "false")
+```
+
+**If `GL_ENABLED` is not `true`:** Skip this step entirely (feature disabled by default).
+
+**If enabled:**
+
+1. Check if LEARNINGS.md exists in the phase directory (use the `phase_dir` value from init context)
+2. If found, copy to global store:
+```bash
+.agent/skills/gsd/bin/gsd-tools.cjs" learnings copy 2>/dev/null || echo "⚠ Learnings copy failed — continuing"
+```
+Copy failure must NOT block phase completion.
+</step>
+
 <step name="update_project_md">
 **Evolve PROJECT.md to reflect phase completion (prevents planning document drift — #956):**
 

package/.agent/skills/gsd/references/workflows/explore.md

@@ -0,0 +1,139 @@
+<purpose>
+Socratic ideation workflow. Guides the developer through exploring an idea via probing questions,
+offers mid-conversation research when useful, then routes crystallized outputs to GSD artifacts.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+
+@references/docs/questioning.md
+@references/docs/domain-probes.md
+</required_reading>
+
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-phase-researcher — Researches specific questions and returns concise findings
+</available_agent_types>
+
+<process>
+
+## Step 1: Open the conversation
+
+If a topic was provided, acknowledge it and begin exploring:
+```
+## Explore: {topic}
+
+Let's think through this together. I'll ask questions to help clarify the idea
+before we commit to any artifacts.
+```
+
+If no topic, ask:
+```
+## Explore
+
+What's on your mind? This could be a feature idea, an architectural question,
+a problem you're trying to solve, or something you're not sure about yet.
+```
+
+## Step 2: Socratic conversation (2-5 exchanges)
+
+Guide the conversation using principles from `questioning.md` and `domain-probes.md`:
+
+- Ask **one question at a time** (never a list of questions)
+- Questions should probe: constraints, tradeoffs, users, scope, dependencies, risks
+- Use domain-specific probes contextually when the topic touches a known domain
+- Listen for signals: "or" / "versus" / "tradeoff" indicate competing priorities worth exploring
+- Reflect back what you hear to confirm understanding before moving forward
+
+**Conversation should feel natural, not formulaic.** Avoid rigid sequences. Follow the developer's energy — if they're excited about one aspect, go deeper there.
+
+## Step 3: Mid-conversation research offer (after 2-3 exchanges)
+
+If the conversation surfaces factual questions, technology comparisons, or unknowns that research could resolve, offer:
+
+```
+This touches on [specific question]. Want me to do a quick research pass before we continue?
+This would take ~30 seconds and might surface useful context.
+
+[Yes, research this] / [No, let's keep exploring]
+```
+
+If yes, spawn a research agent:
+```
+Task(
+  prompt="Quick research: {specific_question}. Return 3-5 key findings, no more than 200 words.",
+  subagent_type="gsd-phase-researcher"
+)
+```
+
+Share findings and continue the conversation.
+
+If the topic doesn't warrant research, skip this step entirely. **Don't force it.**
+
+## Step 4: Crystallize outputs (after 3-6 exchanges)
+
+When the conversation reaches natural conclusions or the developer signals readiness, propose outputs. Analyze the conversation to identify what was discussed and suggest **up to 4 outputs** from:
+
+| Type | Destination | When to suggest |
+|------|-------------|-----------------|
+| Note | `.planning/notes/{slug}.md` | Observations, context, decisions worth remembering |
+| Todo | `.planning/todos/pending/{slug}.md` | Concrete actionable tasks identified |
+| Seed | `.planning/seeds/{slug}.md` | Forward-looking ideas with trigger conditions |
+| Research question | `.planning/research/questions.md` (append) | Open questions that need deeper investigation |
+| Requirement | `REQUIREMENTS.md` (append) | Clear requirements that emerged from discussion |
+| New phase | `ROADMAP.md` (append) | Scope large enough to warrant its own phase |
+
+Present suggestions:
+```
+Based on our conversation, I'd suggest capturing:
+
+1. **Note:** "Authentication strategy decisions" — your reasoning about JWT vs sessions
+2. **Todo:** "Evaluate Passport.js vs custom middleware" — the comparison you want to do
+3. **Seed:** "OAuth2 provider support" — trigger: when user management phase starts
+
+Create these? You can select specific ones or modify them.
+
+[Create all] / [Let me pick] / [Skip — just exploring]
+```
+
+**Never write artifacts without explicit user selection.**
+
+## Step 5: Write selected outputs
+
+For each selected output, write the file:
+
+- **Notes:** Create `.planning/notes/{slug}.md` with frontmatter (title, date, context)
+- **Todos:** Create `.planning/todos/pending/{slug}.md` with frontmatter (title, date, priority)
+- **Seeds:** Create `.planning/seeds/{slug}.md` with frontmatter (title, trigger_condition, planted_date)
+- **Research questions:** Append to `.planning/research/questions.md`
+- **Requirements:** Append to `.planning/REQUIREMENTS.md` with next available REQ ID
+- **Phases:** Use existing `/gsd-add-phase` command via SlashCommand
+
+Commit if `commit_docs` is enabled:
+```bash
+.agent/skills/gsd/bin/gsd-tools.cjs" commit "docs: capture exploration — {topic_slug}" --files {file_list}
+```
+
+## Step 6: Close
+
+```
+## Exploration Complete
+
+**Topic:** {topic}
+**Outputs:** {count} artifact(s) created
+{list of created files}
+
+Continue exploring with `/gsd-explore` or start working with `/gsd-next`.
+```
+
+</process>
+
+<success_criteria>
+- [ ] Socratic conversation follows questioning.md principles
+- [ ] Questions asked one at a time, not in batches
+- [ ] Research offered contextually (not forced)
+- [ ] Up to 4 outputs proposed from conversation
+- [ ] User explicitly selects which outputs to create
+- [ ] Files written to correct destinations
+- [ ] Commit respects commit_docs config
+</success_criteria>

package/.agent/skills/gsd/references/workflows/import.md

@@ -0,0 +1,274 @@
+# Import Workflow
+
+External plan ingestion with conflict detection and agent delegation.
+
+- **--from**: Import external plan → conflict detection → write PLAN.md → validate via gsd-plan-checker
+
+Future: `--prd` mode (PRD extraction into PROJECT.md + REQUIREMENTS.md + ROADMAP.md) is planned for a follow-up PR.
+
+---
+
+<step name="banner">
+
+Display the stage banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► IMPORT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+</step>
+
+<step name="parse_arguments">
+
+Parse `$ARGUMENTS` to determine the execution mode:
+
+- If `--from` is present: extract FILEPATH (the next token after `--from`), set MODE=plan
+- If `--prd` is present: display message that `--prd` is not yet implemented and exit:
+  ```
+  GSD > --prd mode is planned for a future release. Use --from to import plan files.
+  ```
+- If neither flag is found: display usage and exit:
+
+```
+Usage: /gsd-import --from <path>
+
+  --from <path>   Import an external plan file into GSD format
+```
+
+**Validate the file path:**
+
+Verify the path does not contain traversal sequences and the file exists:
+
+```bash
+case "{FILEPATH}" in
+  *..* ) echo "SECURITY_ERROR: path contains traversal sequence"; exit 1 ;;
+esac
+test -f "{FILEPATH}" || echo "FILE_NOT_FOUND"
+```
+
+If FILE_NOT_FOUND: display error and exit:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+File not found: {FILEPATH}
+
+**To fix:** Verify the file path and try again.
+```
+
+</step>
+
+---
+
+## Path A: MODE=plan (--from)
+
+<step name="plan_load_context">
+
+Load project context for conflict detection:
+
+1. Read `.planning/ROADMAP.md` — extract phase structure, phase numbers, dependencies
+2. Read `.planning/PROJECT.md` — extract project constraints, tech stack, scope boundaries.
+   **If PROJECT.md does not exist:** skip constraint checks that rely on it and display:
+   ```
+   GSD > Note: No PROJECT.md found. Conflict checks against project constraints will be skipped.
+   ```
+3. Read `.planning/REQUIREMENTS.md` — extract existing requirements for overlap and contradiction checks.
+   **If REQUIREMENTS.md does not exist:** skip requirement conflict checks and continue.
+4. Glob for all CONTEXT.md files across phase directories:
+   ```bash
+   find .planning/phases/ -name "*-CONTEXT.md" -o -name "CONTEXT.md" 2>/dev/null
+   ```
+   Read each CONTEXT.md found — extract locked decisions (any decision in a `<decisions>` block)
+
+Store loaded context for conflict detection in the next step.
+
+</step>
+
+<step name="plan_read_input">
+
+Read the imported file at FILEPATH.
+
+Determine the format:
+- **GSD PLAN.md format**: Has YAML frontmatter with `phase:`, `plan:`, `type:` fields
+- **Freeform document**: Any other format (markdown spec, design doc, task list, etc.)
+
+Extract from the imported content:
+- **Phase target**: Which phase this plan belongs to (from frontmatter or inferred from content)
+- **Plan objectives**: What the plan aims to accomplish
+- **Tasks listed**: Individual work items described in the plan
+- **Files modified**: Any files mentioned as targets
+- **Dependencies**: Any referenced prerequisites
+
+</step>
+
+<step name="plan_conflict_detection">
+
+Run conflict checks against the loaded project context. Output as a plain-text conflict report using [BLOCKER], [WARNING], and [INFO] labels. Do NOT use markdown tables (no `|---|` format).
+
+### BLOCKER checks (any one prevents import):
+
+- Plan targets a phase number that does not exist in ROADMAP.md → [BLOCKER]
+- Plan specifies a tech stack that contradicts PROJECT.md constraints → [BLOCKER]
+- Plan contradicts a locked decision in any CONTEXT.md `<decisions>` block → [BLOCKER]
+- Plan contradicts an existing requirement in REQUIREMENTS.md → [BLOCKER]
+
+### WARNING checks (user confirmation required):
+
+- Plan partially overlaps existing requirement coverage in REQUIREMENTS.md → [WARNING]
+- Plan has `depends_on` referencing plans that are not yet complete → [WARNING]
+- Plan modifies files that overlap with existing incomplete plans → [WARNING]
+- Plan phase number conflicts with existing phase numbering in ROADMAP.md → [WARNING]
+
+### INFO checks (informational, no action needed):
+
+- Plan uses a library not currently in the project tech stack → [INFO]
+- Plan adds a new phase to the ROADMAP.md structure → [INFO]
+
+Display the full Conflict Detection Report:
+
+```
+## Conflict Detection Report
+
+### BLOCKERS ({N})
+
+[BLOCKER] {Short title}
+  Found: {what the imported plan says}
+  Expected: {what project context requires}
+  → {Specific action to resolve}
+
+### WARNINGS ({N})
+
+[WARNING] {Short title}
+  Found: {what was detected}
+  Impact: {what could go wrong}
+  → {Suggested action}
+
+### INFO ({N})
+
+[INFO] {Short title}
+  Note: {relevant information}
+```
+
+**If any [BLOCKER] exists:**
+
+Display:
+```
+GSD > BLOCKED: {N} blockers must be resolved before import can proceed.
+```
+
+Exit WITHOUT writing any files. This is the safety gate — no PLAN.md is written when blockers exist.
+
+**If only WARNINGS and/or INFO (no blockers):**
+
+Ask via AskUserQuestion using the approve-revise-abort pattern:
+- question: "Review the warnings above. Proceed with import?"
+- header: "Approve?"
+- options: Approve | Abort
+
+If user selects "Abort": exit cleanly with message "Import cancelled."
+
+</step>
+
+<step name="plan_convert">
+
+Convert the imported content to GSD PLAN.md format.
+
+Ensure the PLAN.md has all required frontmatter fields:
+```yaml
+---
+phase: "{NN}-{slug}"
+plan: "{NN}-{MM}"
+type: "feature|refactor|config|test|docs"
+wave: 1
+depends_on: []
+files_modified: []
+autonomous: true
+must_haves:
+  truths: []
+  artifacts: []
+---
+```
+
+**Reject PBR naming conventions in source content:**
+If the imported plan references PBR plan naming (e.g., `PLAN-01.md`, `plan-01.md`), rename all references to GSD `{NN}-{MM}-PLAN.md` convention during conversion.
+
+Apply GSD naming convention for the output filename:
+- Format: `{NN}-{MM}-PLAN.md` (e.g., `04-01-PLAN.md`)
+- NEVER use `PLAN-01.md`, `plan-01.md`, or any other format
+- NN = phase number (zero-padded), MM = plan number within the phase (zero-padded)
+
+Determine the target directory:
+```
+.planning/phases/{NN}-{slug}/
+```
+
+If the directory does not exist, create it:
+```bash
+mkdir -p ".planning/phases/{NN}-{slug}/"
+```
+
+Write the PLAN.md file to the target directory.
+
+</step>
+
+<step name="plan_validate">
+
+Delegate validation to gsd-plan-checker:
+
+```
+Task({
+  subagent_type: "gsd-plan-checker",
+  prompt: "Validate: .planning/phases/{phase}/{plan}-PLAN.md — check frontmatter completeness, task structure, and GSD conventions. Report any issues."
+})
+```
+
+If the checker returns errors:
+- Display the errors to the user
+- Ask the user to resolve issues before the plan is considered imported
+- Do not delete the written file — the user can fix and re-validate manually
+
+If the checker returns clean:
+- Display: "Plan validation passed"
+
+</step>
+
+<step name="plan_finalize">
+
+Update `.planning/ROADMAP.md` to reflect the new plan:
+- Add the plan to the Plans list under the correct phase section
+- Include the plan name and description
+
+Update `.planning/STATE.md` if appropriate (e.g., increment total plan count).
+
+Commit the imported plan and updated files:
+```bash
+.agent/skills/gsd/bin/gsd-tools.cjs" commit "docs({phase}): import plan from {basename FILEPATH}" --files .planning/phases/{phase}/{plan}-PLAN.md .planning/ROADMAP.md
+```
+
+Display completion:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► IMPORT COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Show: plan filename written, phase directory, validation result, next steps.
+
+</step>
+
+---
+
+## Anti-Patterns
+
+Do NOT:
+- Use markdown tables (`|---|`) in the conflict detection report — use plain-text [BLOCKER]/[WARNING]/[INFO] labels
+- Write PLAN.md files as `PLAN-01.md` or `plan-01.md` — always use `{NN}-{MM}-PLAN.md`
+- Use `pbr:plan-checker` or `pbr:planner` — use `gsd-plan-checker` and `gsd-planner`
+- Write `.planning/.active-skill` — this is a PBR pattern with no GSD equivalent
+- Reference `pbr-tools`, `pbr:`, or `PLAN-BUILD-RUN` anywhere
+- Write any PLAN.md file when blockers exist — the safety gate must hold
+- Skip path validation on the --from file argument