learnship 2.0.11 → 2.1.1

package/learnship/workflows/plan-phase.md

@@ -8,9 +8,15 @@ Create executable plans for a roadmap phase. Default flow: Research → Plan →
 
 On platforms with subagent support (Claude Code, OpenCode, Codex), each stage spawns a dedicated specialist agent with its own full context budget. On all other platforms, all stages run sequentially in the same context.
 
-**Usage:** `plan-phase [N]` — optionally add `--skip-research` or `--skip-verify`
+**Usage:** `plan-phase [N]` — optionally add `--skip-research`, `--skip-verify`, or `--research` (force re-research)
 
-> **Platform note:** Read `parallelization` from `.planning/config.json`. When `true`, researcher/planner/checker each run as a spawned subagent. When `false` (default), all stages run inline using agent persona files.
+**Flags:**
+- `--skip-research` — skip the research stage even if enabled in config
+- `--skip-verify` — skip the plan verification stage
+- `--research` — force re-research even if RESEARCH.md already exists
+- `--gaps` — plan only for gaps found during verification
+
+> **Platform note:** Read `parallelization` from `.planning/config.json`. When enabled, researcher/planner/checker each run as a spawned subagent. When `false` (default), all stages run inline using agent persona files.
 
 ## Step 1: Initialize
 
@@ -23,6 +29,15 @@ Read config:
 cat .planning/config.json
 ```
 
+Read TDD mode:
+```bash
+TDD_MODE=$(node -e "try{const c=JSON.parse(require('fs').readFileSync('.planning/config.json','utf8'));process.stdout.write(String((c.workflow||{}).tdd_mode||false));}catch(e){process.stdout.write('false');}" 2>/dev/null || echo 'false')
+```
+
+When `TDD_MODE` is `true`, instruct the planner to apply `type: tdd` to eligible tasks — the executor will use the red-green-refactor cycle for those tasks.
+
+**Context window scaling:** Check `context_window` in config (default: 200000). At >= 500000, include the 3 most recent prior phase CONTEXT.md and SUMMARY.md files in the planner's context. At < 500000, include only frontmatter from prior phases.
+
 Create the phase directory if it doesn't exist:
 ```bash
 node -e "require('fs').mkdirSync('.planning/phases/[padded_phase]-[phase_slug]',{recursive:true})"

package/learnship/workflows/quick.md

@@ -10,9 +10,11 @@ Execute small, ad-hoc tasks with full agentic guarantees: atomic commits, STATE.
 
 **Flags:**
 - `--discuss` — lightweight discussion phase before planning (surfaces gray areas)
-- `--full` — adds plan-checking and post-execution verification
+- `--research` — spawns a focused research agent before planning (investigates approaches, libraries, pitfalls)
+- `--validate` — enables plan-checking (max 2 iterations) and post-execution verification
+- `--full` — enables all of the above: discussion + research + plan-checking + verification
 
-**Composable:** `quick --discuss --full "add dark mode toggle"` gives discussion + plan-checking + verification.
+**Composable:** Granular flags compose freely. `quick --discuss --research --validate` = `--full`.
 
 ## Step 1: Get Task Description
 
@@ -113,6 +115,23 @@ Write `CONTEXT.md` to the task directory:
 </specifics>
 ```
 
+## Step 3b: Research Phase (only with `--research` or `--full`)
+
+**Skip if neither `--research` nor `--full` flag is present.**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► RESEARCHING: [DESCRIPTION]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Using `@./agents/researcher.md` as your research persona, do a focused research pass on the task:
+- What libraries or approaches are relevant?
+- What pitfalls should the implementation avoid?
+- Are there existing patterns in the codebase to follow?
+
+Write a brief `${NEXT_NUM}-RESEARCH.md` (max 50 lines) to the task directory. This feeds into the planner.
+
 ## Step 4: Create Plan
 
 Using `@./agents/planner.md` as your planning persona, read:
@@ -128,16 +147,17 @@ Each task needs:
 - `<verify>` — how to confirm it worked
 - `<done>` — observable completion criteria
 
-If `--full`: also include `must_haves` in plan frontmatter (truths, artifacts, key_links).
+If `--validate` or `--full`: also include `must_haves` in plan frontmatter (truths, artifacts, key_links).
+If `--research` or `--full`: also read the RESEARCH.md from step 3b.
 
 Verify plan was created (substitute actual NEXT_NUM and SLUG values):
 ```bash
 node -e "const fs=require('fs'); console.log(fs.existsSync('.planning/quick/NEXT_NUM-SLUG/NEXT_NUM-PLAN.md') ? 'OK' : 'MISSING')"
 ```
 
-## Step 5: Plan Check (only with `--full`)
+## Step 5: Plan Check (only with `--validate` or `--full`)
 
-**Skip if `--full` flag is not present.**
+**Skip if neither `--validate` nor `--full` flag is present.**
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -187,9 +207,9 @@ After all tasks complete, write `${NEXT_NUM}-SUMMARY.md`:
 [commit hash]
 ```
 
-## Step 7: Verify Results (only with `--full`)
+## Step 7: Verify Results (only with `--validate` or `--full`)
 
-**Skip if `--full` flag is not present.**
+**Skip if neither `--validate` nor `--full` flag is present.**
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -235,7 +255,7 @@ Display completion:
 Quick Task [NEXT_NUM]: [DESCRIPTION]
 
 Summary: .planning/quick/[NEXT_NUM]-[SLUG]/[NEXT_NUM]-SUMMARY.md
-[If --full: Verification: [status]]
+[If --validate/--full: Verification: [status]]
 Commit: [hash]
 
 💡 Solved something notable? `/compound` — capture the solution while context is fresh

package/learnship/workflows/review.md

@@ -198,6 +198,7 @@ git commit -m "fix([scope]): [description from finding]"
 
 ```
 ▶ Next steps:
+- /secure-phase [N] — STRIDE security verification before shipping
 - /ship — run the ship pipeline (test → lint → commit → push → PR)
 - /compound — capture any notable patterns from the review
 ```

package/learnship/workflows/secure-phase.md

@@ -0,0 +1,147 @@
+---
+description: Per-phase security verification — STRIDE threat register, mitigation check, SECURITY.md generation
+---
+
+# Secure Phase
+
+Verify threat mitigations for a completed phase. Reads PLAN.md threat data if present, analyzes the codebase for security concerns, classifies threats, and generates a per-phase SECURITY.md using `@./templates/security.md`.
+
+**Usage:** `secure-phase [N]`
+
+**Sequencing:** Run after `execute-phase [N]` and before or alongside `verify-work [N]`.
+
+## Step 1: Initialize
+
+Read `.planning/config.json` for `workflow.security_enforcement` (defaults to `true`).
+
+If `security_enforcement` is `false`: exit with "Security enforcement disabled. Enable via `/settings`."
+
+Find the phase directory and verify it has been executed (SUMMARY.md exists):
+
+```bash
+ls ".planning/phases/[padded_phase]-[phase_slug]/"*-SUMMARY.md 2>/dev/null
+```
+
+If no SUMMARY.md: "Phase [N] not executed yet. Run `execute-phase [N]` first."
+
+Display:
+```
+learnship > SECURE PHASE [N]: [name]
+```
+
+## Step 2: Discovery
+
+### 2a. Read Phase Artifacts
+
+Read all PLAN.md files for this phase. Look for `<threat_model>` blocks or security-related task descriptions (auth, encryption, input validation, access control, etc.).
+
+### 2b. Read Summary Threat Flags
+
+Read SUMMARY.md files. Look for any security-related notes, deviations, or flags.
+
+### 2c. Analyze Codebase
+
+Scan files modified in this phase for common security patterns:
+
+```bash
+git log --name-only --format="" --grep="([padded_phase]" | sort -u
+```
+
+For each file, check for:
+- Input validation (or lack thereof)
+- Authentication/authorization checks
+- Sensitive data handling (secrets, PII, tokens)
+- SQL/command injection vectors
+- Hardcoded credentials
+- Insecure defaults
+
+## Step 3: Build Threat Register
+
+For each identified concern, create a threat entry:
+
+| Field | Value |
+|-------|-------|
+| Threat ID | T-{phase}-{NN} |
+| Category | STRIDE category (Spoofing/Tampering/Repudiation/Info Disclosure/DoS/Elevation) |
+| Component | Which file or module |
+| Disposition | mitigate / accept / transfer |
+| Status | open / closed |
+
+Classify each threat:
+- **CLOSED** — mitigation found in code OR accepted risk documented OR transferred to third-party
+- **OPEN** — none of the above
+
+## Step 4: Present Threat Plan
+
+If all threats are CLOSED: skip to Step 6.
+
+If open threats exist, present them:
+
+```
+Open Threats ([N]):
+
+| ID | Category | Component | Description |
+|----|----------|-----------|-------------|
+| T-03-01 | Info Disclosure | api/auth.ts | JWT secret in environment without validation |
+
+Options:
+1. Verify all open threats — investigate and resolve
+2. Accept all open — document as accepted risks
+3. Review individually — decide per threat
+```
+
+Wait for user response.
+
+## Step 5: Resolve Open Threats
+
+For option 1 (verify all): Using `@./agents/verifier.md`, check each open threat against the codebase. Update status based on findings.
+
+For option 2 (accept all): Add each to the Accepted Risks Log with user's rationale.
+
+For option 3 (individual): Present each threat one at a time with options: Verify / Accept / Skip.
+
+## Step 6: Write SECURITY.md
+
+Write `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-SECURITY.md` using `@./templates/security.md`:
+
+- Fill in trust boundaries from the analysis
+- Fill in the complete threat register
+- Fill in accepted risks log
+- Fill in audit trail
+- Update frontmatter: `threats_open` count, `status` (draft/verified)
+
+If `threats_open` is 0: set `status: verified`.
+
+Commit:
+```bash
+git add ".planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-SECURITY.md"
+git commit -m "security([padded_phase]): phase security verification"
+```
+
+## Step 7: Report
+
+```
+learnship > SECURE PHASE [N] COMPLETE
+
+Threats found: [total]
+Closed: [N]  |  Accepted: [N]  |  Open: [N]
+
+Status: [verified / needs attention]
+Report: [path to SECURITY.md]
+```
+
+If open threats remain: warn that the phase has unresolved security concerns.
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:**
+
+> **Learning moment:** Security verification surfaces patterns worth internalizing:
+>
+> `@agentic-learning learn [security topic]` — Active retrieval on the security concepts encountered. STRIDE categories, common vulnerability patterns, and mitigation strategies build lasting defensive instincts.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning learn [topic]` to deepen security knowledge from this verification."*

package/learnship/workflows/session-report.md

@@ -0,0 +1,133 @@
+---
+description: Generate a post-session summary with work performed, outcomes, and estimated resource usage
+---
+
+# Session Report
+
+Generate a post-session summary capturing work performed, outcomes achieved, and git activity. Writes a report to `.planning/reports/` for human review and stakeholder sharing.
+
+**Usage:** `session-report`
+
+## Step 1: Gather Session Data
+
+Collect data from available sources:
+
+### 1a. Git Activity
+
+```bash
+git log --oneline --since="24 hours ago" --no-merges 2>/dev/null || echo "No recent commits"
+
+git diff --stat HEAD~10 HEAD 2>/dev/null | tail -1 || echo "No diff available"
+
+git log --format="%ai" --since="24 hours ago" 2>/dev/null | head -1
+git log --format="%ai" --since="24 hours ago" 2>/dev/null | tail -1
+```
+
+### 1b. Planning State
+
+Read `.planning/STATE.md` to get:
+- Current milestone and phase
+- Progress percentage
+- Active blockers
+- Recent decisions
+
+Read `.planning/ROADMAP.md` to get milestone name and phase goals.
+
+### 1c. Phase Artifacts
+
+```bash
+find .planning/phases -name "*-SUMMARY.md" -newer .planning/STATE.md 2>/dev/null
+find .planning/phases -name "*-UAT.md" -newer .planning/STATE.md 2>/dev/null
+find .planning/phases -name "*-VERIFICATION.md" -newer .planning/STATE.md 2>/dev/null
+```
+
+### 1d. Previous Reports
+
+```bash
+ls -la .planning/reports/SESSION_REPORT*.md 2>/dev/null || echo "No previous reports"
+```
+
+## Step 2: Generate Report
+
+```bash
+node -e "require('fs').mkdirSync('.planning/reports',{recursive:true})"
+```
+
+Write `.planning/reports/SESSION-[YYYYMMDD].md`:
+
+```markdown
+# Session Report
+
+**Generated:** [timestamp]
+**Project:** [from PROJECT.md title or directory name]
+**Milestone:** [N] — [milestone name]
+
+---
+
+## Session Summary
+
+**Duration:** [estimated from first to last commit timestamp, or "Single session"]
+**Phase Progress:** [from STATE.md]
+**Plans Executed:** [count of summaries written this session]
+**Commits Made:** [count from git log]
+
+## Work Performed
+
+| Phase | Plans | Status | Key Deliverables |
+|-------|-------|--------|-----------------|
+| [N]   | [IDs] | [complete/partial] | [what was built] |
+
+## Decisions Made
+
+[Decisions captured during this session, from STATE.md or DECISIONS.md changes]
+
+## Issues Encountered
+
+[Any blockers, bugs, or deviations noted in SUMMARYs]
+
+## Files Changed
+
+[Top 10 most-changed files from git diff --stat]
+
+---
+
+## Next Steps
+
+[What STATE.md says is next]
+
+---
+
+*Generated by learnship session-report*
+```
+
+## Step 3: Commit and Present
+
+```bash
+git add .planning/reports/
+git commit -m "docs: session report [date]"
+```
+
+```
+learnship > SESSION REPORT COMPLETE
+
+Report: .planning/reports/SESSION-[date].md
+Duration: [estimate]
+Commits: [N]
+Plans completed: [M]
+
+Share this report with stakeholders or use it for team standups.
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:**
+
+> **Learning moment:** End of session is a natural reflection point:
+>
+> `@agentic-learning reflect` — What was the most valuable thing accomplished this session? What would you do differently? Structured reflection at session boundaries builds compounding insight.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning reflect` to consolidate lessons from this session."*

package/learnship/workflows/settings.md

@@ -18,11 +18,10 @@ If missing, create from template:
 ```bash
 cp templates/config.json .planning/config.json 2>/dev/null || cat > .planning/config.json << 'EOF'
 {
-  "mode": "yolo",
+  "mode": "interactive",
   "granularity": "standard",
   "model_profile": "balanced",
   "learning_mode": "auto",
-  "parallelization": false,
   "test_first": false,
   "planning": {
     "commit_docs": true,
@@ -35,7 +34,30 @@ cp templates/config.json .planning/config.json 2>/dev/null || cat > .planning/co
     "verifier": true,
     "validation": true,
     "review": true,
-    "solutions_search": true
+    "solutions_search": true,
+    "security_enforcement": true,
+    "discuss_mode": "discuss",
+    "tdd_mode": false
+  },
+  "parallelization": {
+    "enabled": false,
+    "plan_level": true,
+    "task_level": false,
+    "max_concurrent_agents": 5,
+    "min_plans_for_parallel": 2
+  },
+  "gates": {
+    "confirm_project": true,
+    "confirm_phases": true,
+    "confirm_roadmap": true,
+    "confirm_plan": true,
+    "execute_next_plan": true,
+    "issues_review": true,
+    "confirm_transition": true
+  },
+  "safety": {
+    "always_confirm_destructive": true,
+    "always_confirm_external_services": true
   },
   "review": {
     "auto_after_verify": false
@@ -45,6 +67,9 @@ cp templates/config.json .planning/config.json 2>/dev/null || cat > .planning/co
     "conventional_commits": true,
     "pr_template": true
   },
+  "hooks": {
+    "context_warnings": true
+  },
   "git": {
     "branching_strategy": "none",
     "phase_branch_template": "phase-{phase}-{slug}",
@@ -84,12 +109,16 @@ Current configuration:
 [9] Test validation:   [on/off]
 [10] Review workflow:   [on/off]
 [11] Solutions search:  [on/off]
-[12] Auto-review after verify: [on/off]
-[13] Ship: auto-test:   [on/off]
-[14] Ship: conventional commits: [on/off]
-[15] Ship: PR template: [on/off]
-[16] Git branching:     [current] (none | phase | milestone)
-[17] Commit docs:       [on/off]
+[12] Security enforcement: [on/off]
+[13] Auto-review after verify: [on/off]
+[14] Ship: auto-test:   [on/off]
+[15] Ship: conventional commits: [on/off]
+[16] Ship: PR template: [on/off]
+[17] Parallelization:   [on/off] (max agents: [N])
+[18] Git branching:     [current] (none | phase | milestone)
+[19] Commit docs:       [on/off]
+[20] Safety: confirm destructive: [on/off]
+[21] Context warnings:  [on/off]
 
 Enter a number to change a setting, or 'done' to save.
 ```
@@ -222,45 +251,10 @@ Current: [current]. New value? (on/off)
 
 ## Step 5: Save Config
 
-After user types "done", write the updated config:
+After user types "done", read the current config, apply all changes, and write the complete updated JSON. Preserve any fields not shown in the menu (gates, hooks, etc.) — never drop fields the user didn't modify.
 
 ```bash
-cat > .planning/config.json << EOF
-{
-  "mode": "[value]",
-  "granularity": "[value]",
-  "model_profile": "[value]",
-  "learning_mode": "[value]",
-  "parallelization": [true/false],
-  "test_first": [true/false],
-  "planning": {
-    "commit_docs": [true/false],
-    "commit_mode": "[auto/manual]",
-    "search_gitignored": false
-  },
-  "workflow": {
-    "research": [true/false],
-    "plan_check": [true/false],
-    "verifier": [true/false],
-    "validation": [true/false],
-    "review": [true/false],
-    "solutions_search": [true/false]
-  },
-  "review": {
-    "auto_after_verify": [true/false]
-  },
-  "ship": {
-    "auto_test": [true/false],
-    "conventional_commits": [true/false],
-    "pr_template": [true/false]
-  },
-  "git": {
-    "branching_strategy": "[value]",
-    "phase_branch_template": "phase-{phase}-{slug}",
-    "milestone_branch_template": "{milestone}-{slug}"
-  }
-}
-EOF
+node -e "const fs=require('fs');const c=JSON.parse(fs.readFileSync('.planning/config.json','utf8'));/* apply changes to c */;fs.writeFileSync('.planning/config.json',JSON.stringify(c,null,2)+'\n');"
 ```
 
 ## Step 6: Commit

package/learnship/workflows/ship.md

@@ -187,6 +187,8 @@ or patterns while context is fresh.
 ▶ Next steps:
 - Review the PR and request reviews
 - /compound — capture learnings from this work
+- /session-report — generate a session summary for stakeholders
+- /extract-learnings [N] — capture decisions, lessons, patterns from this phase
 ```
 
 ---

package/learnship/workflows/undo.md

@@ -0,0 +1,151 @@
+---
+description: Safe git revert for phase or plan commits — preserves history, checks dependencies
+---
+
+# Undo
+
+Safe git revert workflow. Rolls back phase or plan commits using git revert (NEVER git reset) to preserve history. Includes dependency checks and a confirmation gate.
+
+**Usage:**
+- `undo --last N` — show last N commits for interactive selection
+- `undo --phase NN` — revert all commits for phase NN
+- `undo --plan NN-MM` — revert all commits for plan NN-MM
+
+## Step 1: Parse Arguments
+
+Parse for the undo mode:
+
+- `--last N` — MODE=last, COUNT=N (default 10 if N missing)
+- `--phase NN` — MODE=phase, TARGET_PHASE=NN
+- `--plan NN-MM` — MODE=plan, TARGET_PLAN=NN-MM
+
+If no valid argument, display usage and exit.
+
+## Step 2: Gather Commits
+
+**MODE=last:**
+
+```bash
+git log --oneline --no-merges -${COUNT}
+```
+
+Filter for conventional commits matching `type(scope): message` pattern. Display numbered list. Ask user to select which commits to revert (numbers or "all").
+
+**MODE=phase:**
+
+```bash
+git log --oneline --no-merges --all --grep="(${TARGET_PHASE})" | head -30
+git log --oneline --no-merges --all --grep="phase-${TARGET_PHASE}" | head -30
+```
+
+Collect all commits whose scope references the target phase.
+
+**MODE=plan:**
+
+```bash
+git log --oneline --no-merges --all --grep="(${TARGET_PLAN})" | head -20
+```
+
+Collect all commits whose scope references the target plan.
+
+If no commits found: "No commits found for [target]. Check the phase/plan number."
+
+## Step 3: Dependency Check
+
+For each commit to be reverted, check if later commits depend on the files it modified:
+
+```bash
+for COMMIT in $COMMITS; do
+  FILES=$(git diff-tree --no-commit-id --name-only -r $COMMIT)
+  for FILE in $FILES; do
+    LATER=$(git log --oneline ${COMMIT}..HEAD -- "$FILE" | head -5)
+    if [ -n "$LATER" ]; then
+      echo "WARNING: $FILE was modified in later commits:"
+      echo "$LATER"
+    fi
+  done
+done
+```
+
+If dependencies found, warn:
+```
+WARNING: These commits have downstream dependencies.
+Reverting may break later work. Files affected:
+
+- [file]: modified in [N] later commits
+
+Proceed anyway? [Yes, revert] / [No, cancel]
+```
+
+## Step 4: Confirmation Gate
+
+Display the revert plan:
+```
+Commits to revert ([N] total):
+
+  [hash] [message]
+  [hash] [message]
+
+This will create [N] new revert commits preserving full history.
+
+[Confirm revert] / [Cancel]
+```
+
+Wait for explicit confirmation.
+
+## Step 5: Execute Revert
+
+For each commit in reverse chronological order:
+
+```bash
+git revert --no-commit [hash]
+```
+
+After all reverts staged:
+
+```bash
+git commit -m "revert([scope]): undo [description]
+
+Reverted commits:
+- [hash]: [message]
+- [hash]: [message]"
+```
+
+## Step 6: Update State
+
+If `.planning/STATE.md` exists, add a note about the revert:
+
+```markdown
+### Revert Log
+- [date]: Reverted [N] commits for [target] — [reason if provided]
+```
+
+```bash
+git add .planning/STATE.md
+git commit -m "docs(state): record revert"
+```
+
+## Step 7: Report
+
+```
+learnship > UNDO COMPLETE
+
+Reverted [N] commits for [target].
+New revert commit: [hash]
+
+All original commits preserved in history.
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:**
+
+> **Learning moment:** Needing to undo is a signal worth examining:
+>
+> `@agentic-learning either-or` — What led to needing the undo? Was it a plan deficiency, an execution error, or a changed requirement? Log the reasoning so the pattern is visible next time.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning either-or` to log why the undo was needed."*