learnship 1.9.22 → 2.0.0

package/learnship/workflows/review.md

@@ -0,0 +1,226 @@
+---
+description: Multi-persona code review — correctness, testing, security, performance, maintainability
+---
+
+# Review
+
+Multi-persona code review that examines changes through six lenses: correctness, testing, security, performance, maintainability, and adversarial. Produces a severity-ranked findings report with confidence scores.
+
+**Usage:** `review` — review current branch changes
+**Usage:** `review [mode]` — modes: `interactive` (default), `report-only`, `autofix`
+
+**Sequencing:** Run after `verify-work` (spec compliance) and before `/ship` (deploy pipeline).
+
+## Step 1: Determine Scope
+
+Compute the diff:
+
+```bash
+# Detect base branch
+BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||')
+[ -z "$BASE_BRANCH" ] && BASE_BRANCH="main"
+
+# Get current branch
+CURRENT=$(git rev-parse --abbrev-ref HEAD)
+
+# Compute diff
+git fetch origin "$BASE_BRANCH" --quiet 2>/dev/null
+BASE=$(git merge-base "origin/$BASE_BRANCH" HEAD 2>/dev/null || echo "origin/$BASE_BRANCH")
+echo "FILES:" && git diff --name-only $BASE
+echo "DIFF:" && git diff -U10 $BASE
+echo "STATS:" && git diff --stat $BASE
+```
+
+If no diff found: "Nothing to review — no changes against $BASE_BRANCH." Stop.
+
+## Step 2: Discover Intent
+
+Understand what the change is trying to accomplish:
+
+```bash
+echo "BRANCH:" && git rev-parse --abbrev-ref HEAD
+echo "COMMITS:" && git log --oneline ${BASE}..HEAD
+```
+
+Combined with conversation context and any SUMMARY.md files from the current phase, write a 2-3 line intent summary:
+
+```
+Intent: [what the changes are trying to accomplish]
+```
+
+## Step 3: Select Personas
+
+Read the diff and file list. Select which review personas to activate:
+
+**Always-on (every review):**
+
+| Persona | Focus |
+|---------|-------|
+| **correctness** | Logic errors, edge cases, state bugs, error propagation |
+| **testing** | Coverage gaps, weak assertions, brittle tests |
+| **maintainability** | Coupling, complexity, naming, dead code, abstraction debt |
+
+**Conditional (selected per diff):**
+
+| Persona | Select when diff touches... |
+|---------|---------------------------|
+| **security** | Auth, public endpoints, user input, permissions, secrets |
+| **performance** | DB queries, data transforms, caching, async, loops |
+| **adversarial** | Diff ≥50 changed non-test lines, or auth/payments/data mutations |
+
+**Brownfield enhancement:** If `.planning/codebase/CONVENTIONS.md` exists, the maintainability persona reads it for project-specific patterns.
+
+Announce the review team:
+```
+Review team:
+- correctness (always)
+- testing (always)
+- maintainability (always)
+- security — [justification if selected]
+- performance — [justification if selected]
+- adversarial — [justification if selected]
+```
+
+## Step 4: Run Review
+
+Read `parallelization` from `.planning/config.json` (defaults to `false`).
+
+**If `parallelization` is `true` (subagent mode — Claude Code, OpenCode, Codex):**
+
+Spawn a dedicated code-reviewer agent for each selected persona:
+
+```
+Task(
+  subagent_type="learnship-code-reviewer",
+  prompt="
+    <objective>
+    Review the following diff as the [PERSONA] reviewer.
+    Focus: [persona-specific focus areas]
+    Return findings as structured text with severity (P0-P3) and confidence (0.0-1.0).
+    Do NOT edit any files. Read-only review.
+    </objective>
+
+    <context>
+    Intent: [intent summary]
+    Files: [file list]
+    Diff: [diff content]
+    [If maintainability + CONVENTIONS.md exists: include conventions]
+    </context>
+  "
+)
+```
+
+Wait for all personas to complete.
+
+**If `parallelization` is `false` (sequential mode):**
+
+Using `@./agents/code-reviewer.md` as your review persona, run each selected persona sequentially. For each persona:
+
+1. Adopt the persona's focus lens
+2. Read the diff through that lens
+3. Record findings with severity and confidence
+
+## Step 5: Merge & Deduplicate Findings
+
+Combine findings from all personas:
+
+1. **Confidence gate** — suppress findings below 0.60 confidence. Exception: P0 findings at 0.50+ survive.
+2. **Deduplicate** — when multiple personas flag the same issue (same file + nearby lines + similar title), merge: keep highest severity, keep highest confidence, note which personas flagged it.
+3. **Cross-persona agreement** — when 2+ personas flag the same issue, boost confidence by 0.10 (capped at 1.0).
+4. **Sort** — order by severity (P0 first) → confidence (descending) → file path → line number.
+
+## Step 6: Present Report
+
+### Severity Scale
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| **P0** | Critical breakage, exploitable vulnerability, data loss | Must fix before merge |
+| **P1** | High-impact defect likely hit in normal usage | Should fix |
+| **P2** | Moderate issue — edge case, perf regression, maintainability trap | Fix if straightforward |
+| **P3** | Low-impact, minor improvement | Discretion |
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► CODE REVIEW COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Intent: [intent summary]
+Reviewers: [list]
+Mode: [interactive | report-only | autofix]
+
+## Findings
+
+### P0 — Critical
+| # | File | Issue | Reviewer(s) | Confidence |
+|---|------|-------|-------------|------------|
+| 1 | [file:line] | [issue] | [personas] | [0.XX] |
+
+### P1 — High
+[table or "None"]
+
+### P2 — Moderate
+[table or "None"]
+
+### P3 — Low
+[table or "None"]
+
+---
+
+## Verdict
+
+[PASS — no P0/P1 findings]
+[PASS WITH CONCERNS — P1 findings present but manageable]
+[FAIL — P0 findings must be resolved before merge]
+
+Total: [N] findings ([P0 count] critical, [P1 count] high, [P2 count] moderate, [P3 count] low)
+```
+
+## Step 7: Handle Mode
+
+**Interactive (default):**
+For each P0/P1 finding, ask: "Fix this now, or defer?"
+- **Fix now** → apply the fix, commit
+- **Defer** → note in report
+
+**Report-only:**
+Display the report. No edits, no commits. Stop.
+
+**Autofix:**
+Apply fixes for P0/P1 findings automatically where the fix is deterministic and safe. Commit each fix:
+```bash
+git add [files]
+git commit -m "fix([scope]): [description from finding]"
+```
+
+## Step 8: Suggest Next Steps
+
+```
+▶ Next steps:
+- /ship — run the ship pipeline (test → lint → commit → push → PR)
+- /compound — capture any notable patterns from the review
+```
+
+---
+
+## Config Options
+
+- `"workflow.review": true` — enable/disable the review workflow
+- `"review.auto_after_verify": false` — automatically run review after verify-work passes
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** After review, offer:
+
+> 💡 **Learning moment:** Code review is one of the highest-signal learning activities:
+>
+> `@agentic-learning learn [finding domain]` — Active retrieval on the concept behind the most significant finding. Why did it happen? How would you catch it earlier?
+>
+> `@agentic-learning quiz [codebase area]` — Test your understanding of the code area that had the most findings. Gaps in recall predict future bugs.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning learn [domain]` to turn review findings into lasting patterns."*

package/learnship/workflows/set-profile.md

@@ -15,9 +15,9 @@ If no argument provided:
 Usage: set-profile [profile]
 
 Profiles:
-  quality   — Opus for all agents (highest quality, highest cost)
-  balanced  — Opus for planning, Sonnet for execution (recommended)
-  budget    — Sonnet for writing, Haiku for research/verification (lowest cost)
+  quality   — large-tier models for all agents (highest quality, highest cost)
+  balanced  — large for planning, medium for execution (recommended)
+  budget    — medium for writing, small for research/verification (lowest cost)
 
 Current profile: [read from .planning/config.json]
 ```
@@ -70,9 +70,9 @@ git commit -m "chore(config): set model profile to [profile]"
 ```
 Profile updated: [old] → [profile]
 
-[quality]  — Opus agents for all tasks. Use for production milestones.
-[balanced] — Opus for planning, Sonnet for execution. Best default.
-[budget]   — Sonnet/Haiku. Use for prototyping or exploration.
+[quality]  — Large-tier agents for all tasks. Use for production milestones.
+[balanced] — Large for planning, medium for execution. Best default.
+[budget]   — Medium/small tier. Use for prototyping or exploration.
 
 Takes effect immediately on the next workflow run.
 ```

package/learnship/workflows/settings.md

@@ -30,7 +30,7 @@ cp templates/config.json .planning/config.json 2>/dev/null || cat > .planning/co
     "research": true,
     "plan_check": true,
     "verifier": true,
-    "nyquist_validation": true
+    "validation": true
   },
   "git": {
     "branching_strategy": "none",
@@ -67,7 +67,7 @@ Current configuration:
 [5] Research agent:    [on/off]
 [6] Plan check agent:  [on/off]
 [7] Verifier agent:    [on/off]
-[8] Nyquist validation:[on/off]
+[8] Test validation:  [on/off]
 [9] Git branching:     [current] (none | phase | milestone)
 [10] Commit docs:      [on/off]
 
@@ -102,9 +102,9 @@ Current: [current]. New value?
 **[3] Model profile:**
 ```
 Model profile controls which model tier each agent uses:
-- quality: Opus for all decision-making agents (highest cost, best results)
-- balanced: Opus for planning, Sonnet for execution (default — good balance)
-- budget: Sonnet for writing code, Haiku for research/verification (lowest cost)
+- quality: large-tier for all decision-making agents (highest cost, best results)
+- balanced: large for planning, medium for execution (default — good balance)
+- budget: medium for writing code, small for research/verification (lowest cost)
 
 Current: [current]. New value?
 ```
@@ -127,9 +127,9 @@ Current: [current]. New value?
 Current: [current]. New value? (on/off)
 ```
 
-**[8] Nyquist validation:**
+**[8] Test validation:**
 ```
-Nyquist validation maps automated test coverage to requirements during plan-phase.
+Test validation maps automated test coverage to requirements during plan-phase.
 - on: plans include automated verify commands per task (recommended)
 - off: skip validation research (good for rapid prototyping)
 
@@ -174,7 +174,7 @@ cat > .planning/config.json << EOF
     "research": [true/false],
     "plan_check": [true/false],
     "verifier": [true/false],
-    "nyquist_validation": [true/false]
+    "validation": [true/false]
   },
   "git": {
     "branching_strategy": "[value]",

package/learnship/workflows/ship.md

@@ -0,0 +1,219 @@
+---
+description: Ship pipeline — test, lint, commit, push, PR
+---
+
+# Ship
+
+End-to-end ship pipeline: detect test runner → run tests → lint → stage → conventional commit → push → create PR with auto-description. Closes the loop from verified code to production-ready PR.
+
+**Usage:** `ship` — run the full ship pipeline
+**Usage:** `ship --skip-tests` — skip test execution (use when tests were just run)
+
+**Sequencing:** Run after `/review` (code quality) and before `/compound` (capture learnings).
+
+## Step 1: Pre-flight Check
+
+```bash
+# Current branch
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+echo "Branch: $BRANCH"
+
+# Check we're not on main/master
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  echo "ERROR: Cannot ship from $BRANCH. Create a feature branch first."
+  exit 1
+fi
+
+# Check for uncommitted changes
+git status --porcelain
+```
+
+If uncommitted changes exist, ask: "You have uncommitted changes. Stage and commit them as part of the ship, or stash first?"
+
+## Step 2: Run Tests
+
+**Skip if:** `--skip-tests` flag, or `ship.auto_test` is `false` in config.
+
+Detect the test runner:
+
+```bash
+# Check for common test runners
+[ -f "package.json" ] && grep -q '"test"' package.json && echo "npm test"
+[ -f "Makefile" ] && grep -q '^test:' Makefile && echo "make test"
+[ -f "pytest.ini" ] || [ -f "setup.cfg" ] && echo "pytest"
+[ -f "Cargo.toml" ] && echo "cargo test"
+[ -f "go.mod" ] && echo "go test ./..."
+```
+
+Run the detected test command:
+
+```bash
+[detected test command]
+```
+
+If tests fail:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► TESTS FAILED — SHIP ABORTED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[test output]
+
+Fix the failing tests, then run /ship again.
+▶ Or: /debug [test failure description]
+```
+
+Stop. Do not proceed with a failing test suite.
+
+## Step 3: Lint (Optional)
+
+Detect and run the linter if available:
+
+```bash
+[ -f "package.json" ] && grep -q '"lint"' package.json && echo "npm run lint"
+[ -f ".eslintrc" ] || [ -f ".eslintrc.json" ] || [ -f ".eslintrc.js" ] && echo "npx eslint ."
+[ -f "pyproject.toml" ] && grep -q "ruff" pyproject.toml && echo "ruff check ."
+[ -f ".rubocop.yml" ] && echo "rubocop"
+```
+
+If linter found, run it. Report warnings but don't block on them. Block on errors.
+
+## Step 4: Stage Changes
+
+```bash
+# Show what will be committed
+git diff --stat
+
+# Stage all tracked changes
+git add -u
+
+# Check for untracked files that should be included
+UNTRACKED=$(git ls-files --others --exclude-standard)
+if [ -n "$UNTRACKED" ]; then
+  echo "Untracked files found:"
+  echo "$UNTRACKED"
+fi
+```
+
+If untracked files exist, ask: "These files are new and untracked. Include them in the commit?"
+- **Yes, include all** → `git add .`
+- **Let me choose** → present list, user selects
+- **No, skip them** → proceed with tracked only
+
+## Step 5: Conventional Commit
+
+**If `ship.conventional_commits` is `true` in config (default: `true`):**
+
+Analyze the staged changes to determine the commit type:
+
+| Type | When |
+|------|------|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `style` | Formatting, no logic change |
+| `refactor` | Code restructuring, no behavior change |
+| `test` | Adding or updating tests |
+| `chore` | Build, config, tooling |
+
+Generate the commit message:
+```
+[type]([scope]): [short description]
+
+[optional body — what changed and why, max 3 lines]
+```
+
+Present the proposed commit message. Ask: "Use this commit message, or edit?"
+
+```bash
+git commit -m "[commit message]"
+```
+
+## Step 6: Push
+
+```bash
+git push origin $BRANCH
+```
+
+If this is the first push for the branch:
+```bash
+git push -u origin $BRANCH
+```
+
+## Step 7: Create PR
+
+**If `ship.pr_template` is `true` in config (default: `true`):**
+
+Auto-generate the PR description from:
+- Commit messages on the branch
+- SUMMARY.md files from the current phase (if exists)
+- Test results from Step 2
+
+```bash
+# Get base branch
+BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||')
+[ -z "$BASE_BRANCH" ] && BASE_BRANCH="main"
+
+# Get commit log for PR body
+COMMITS=$(git log --oneline origin/$BASE_BRANCH..HEAD)
+```
+
+Create the PR using available tooling:
+
+```bash
+# GitHub CLI
+gh pr create --base "$BASE_BRANCH" --head "$BRANCH" --title "[type]([scope]): [description]" --body "[auto-generated description]"
+
+# Or if gh not available, output the PR URL
+echo "Create PR: https://github.com/[org]/[repo]/compare/$BASE_BRANCH...$BRANCH"
+```
+
+## Step 8: Confirm
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► SHIPPED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Branch: [branch]
+Tests: passed ✓
+Lint: passed ✓ | skipped
+Commit: [hash] [type]([scope]): [description]
+PR: [URL]
+
+💡 Compound this work? Run `/compound` to capture any notable solutions
+or patterns while context is fresh.
+
+▶ Next steps:
+- Review the PR and request reviews
+- /compound — capture learnings from this work
+```
+
+---
+
+## Config Options
+
+- `"ship.auto_test": true` — run tests before shipping
+- `"ship.conventional_commits": true` — use conventional commit format
+- `"ship.pr_template": true` — auto-generate PR description
+
+---
+
+## Integration Points
+
+- `verify-work` banner: "▶ Next: /ship" after UAT passes
+- `complete-milestone`: "Did you /ship first?" if unshipped changes exist
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** After shipping, offer:
+
+> 💡 **Learning moment:** Shipping is a natural reflection point:
+>
+> `@agentic-learning reflect` — What went well in this phase? What would you do differently? Reflection after shipping cements the lessons before context fades.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning reflect` to consolidate lessons from this shipping cycle."*

package/learnship/workflows/sync-docs.md

@@ -0,0 +1,159 @@
+---
+description: Detect stale documentation after code changes
+---
+
+# Sync Docs
+
+Scan documentation against recent code changes to detect stale sections, outdated references, and drift between docs and implementation. Auto-update simple cases, flag complex ones for manual review.
+
+**Usage:** `sync-docs` — scan all docs for staleness
+**Usage:** `sync-docs [path]` — scan docs for a specific module or directory
+
+## Step 1: Discover Documentation
+
+Find all documentation files in the project:
+
+```bash
+# README and top-level docs
+find . -maxdepth 1 -name "*.md" -type f 2>/dev/null
+
+# Docs directory
+find docs/ -name "*.md" -type f 2>/dev/null
+
+# API docs, guides, etc.
+find . -path "*/docs/*" -name "*.md" -type f 2>/dev/null | head -30
+
+# Planning docs
+find .planning/ -name "*.md" -type f 2>/dev/null | grep -v "phases\|debug\|milestones" | head -20
+```
+
+If a path argument was provided, narrow the scan to docs related to that module.
+
+## Step 2: Identify Recent Changes
+
+```bash
+# Get files changed in last 30 commits
+git log --oneline -30 --format="" --name-only | sort -u
+
+# Get files changed since last tag/release
+LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)
+if [ -n "$LAST_TAG" ]; then
+  git diff --name-only "$LAST_TAG"..HEAD
+fi
+```
+
+Map changed source files to their documentation:
+- `src/auth/` changes → check docs mentioning auth, authentication, login
+- API route changes → check API documentation
+- Config changes → check setup/installation docs
+- Schema changes → check data model docs
+
+## Step 3: Scan for Staleness
+
+For each documentation file, check:
+
+1. **Dead references** — does the doc reference files, functions, or APIs that no longer exist?
+```bash
+# Extract code references from doc (backtick-wrapped paths, function names)
+grep -oE '`[^`]+\.(ts|js|py|rb|go)`' [doc_file] 2>/dev/null
+# Check if referenced files exist
+```
+
+2. **Outdated descriptions** — does the doc describe behavior that's changed?
+- Compare doc descriptions against actual code behavior
+- Check version numbers, dependency names, command syntax
+
+3. **Missing coverage** — are there new files/features with no documentation?
+```bash
+# Find source files with no corresponding doc mention
+for file in $(git log --oneline -30 --format="" --name-only | sort -u | grep -E '\.(ts|js|py|rb|go)$'); do
+  BASENAME=$(basename "$file" | sed 's/\.[^.]*$//')
+  grep -ril "$BASENAME" docs/ 2>/dev/null | wc -l | tr -d ' '
+done
+```
+
+## Step 4: Report Findings
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► DOC SYNC REPORT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Scanned: [N] documentation files
+Changes since: [last tag or last 30 commits]
+
+## Stale Sections
+
+| Doc | Section | Issue | Severity |
+|-----|---------|-------|----------|
+| [file] | [heading] | [what's wrong] | high/medium/low |
+
+## Dead References
+
+| Doc | Reference | Status |
+|-----|-----------|--------|
+| [file] | `[reference]` | removed / renamed to [new name] |
+
+## Missing Documentation
+
+| New File/Feature | Suggested Doc |
+|------------------|---------------|
+| [file] | Add to [existing doc] or create new |
+
+## Auto-Fixable
+
+[N] issues can be auto-fixed (renamed references, updated paths)
+```
+
+## Step 5: Auto-Fix Simple Cases
+
+For issues that can be fixed automatically (renamed files, updated paths, version numbers):
+
+```bash
+# Apply fixes
+sed -i 's/old_reference/new_reference/g' [doc_file]
+
+git add [fixed files]
+git commit -m "docs: sync — fix [N] stale references"
+```
+
+For complex issues (rewritten behavior, new feature descriptions), present to user:
+
+```
+These [N] issues need manual review:
+1. [doc]: [section] — [what needs updating and why]
+2. [doc]: [section] — [what needs updating and why]
+```
+
+## Step 6: Confirm
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► DOC SYNC COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Auto-fixed: [N] issues
+Manual review needed: [M] issues
+Missing docs: [K] new features without documentation
+```
+
+---
+
+## Integration Points
+
+- `complete-milestone`: optionally run `/sync-docs` before releasing
+- `release`: suggest `/sync-docs` as pre-release checklist item
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** After sync, offer:
+
+> 💡 **Learning moment:** Documentation drift is a signal about process:
+>
+> `@agentic-learning reflect` — Why did these docs get stale? Is there a pattern (e.g., docs always lag behind API changes)? Reflecting on the drift pattern prevents it next time.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning reflect` to understand why docs drifted and prevent it."*