feat: v0.4.0 — Project Wiki, Evolution Pipeline, CLI Consolidation

.selfmodel/playbook/context-protocol.md

@@ -84,7 +84,9 @@ Claude Code 的自动 compaction 会压缩历史消息，但：
 
 | 信息类型 | 外部化目标 |
 |----------|-----------|
-| 架构决策 | `playbook/lessons-learned.md` |
+| 架构决策 | `wiki/decisions/` (ADR) + `playbook/lessons-learned.md` |
+| 模块知识 | `wiki/modules/<module>.md` |
+| 发现的模式 | `wiki/patterns/<pattern>.md` |
 | Sprint 进度 | `state/next-session.md` |
 | 团队状态 | `state/team.json` |
 | 质量评分 | `state/quality.jsonl` |

.selfmodel/playbook/orchestration-loop.md

@@ -215,6 +215,14 @@ LOOP:
           - Write feedback: "Post-merge regression detected: <error>"
           - Agent must fix in worktree, re-rebase, re-merge
 
+  7.6. POST-MERGE WIKI SYNC (after smoke test passes)
+       a. Extract changed files: git diff HEAD~1 --name-only
+       b. Map to wiki/modules/ pages
+       c. Check Sprint contract ## Wiki Impact — listed pages not updated → log warning
+       d. Update wiki/index.md if new pages created
+       e. Informational only — does NOT block merge
+       f. Append to wiki/log.md: [timestamp] SYNC sprint-<N>: <summary>
+
   8. CHECKPOINT
      - Write next-session.md (current phase + completed sprints + pending)
      - Append to quality.jsonl
@@ -228,6 +236,10 @@ LOOP:
           ii.  Log: phase=<N> event=evolution_detect candidates=<N>
           iii. If candidates > 0: notify user "N evolution candidates. Run /selfmodel:evolve"
           iv.  Update team.json: evolution.last_review_sprint = current_sprint
+          v.   Wiki health audit: run `selfmodel status` wiki health check
+               - If health < 7: log warning "wiki health degraded: <score>/10"
+               - If stale > 5: log warning "N wiki pages stale — schedule wiki refresh"
+               - Append to orchestration.log: phase=<N> event=wiki_audit health=<score> stale=<N> empty=<N>
        d. If count < 10: skip
 
   9. CHECK context health

.selfmodel/playbook/sprint-template.md

@@ -41,3 +41,7 @@ DRAFT → ACTIVE → DELIVERED → REVIEWED → MERGED | REJECTED
 - Budget: 5m
 - Threshold: resilience >= 70
 (Leader dispatches `/rampage --selfmodel` after E2E PASS, see quality-gates.md Step 4.7)
+
+## Wiki Impact (optional — which wiki pages this Sprint affects)
+- <wiki page path, e.g. wiki/modules/auth.md>
+(Agent updates these pages as part of delivery. Leader validates in post-merge.)

.selfmodel/playbook/wiki-protocol.md

@@ -0,0 +1,145 @@
+# Wiki Protocol
+
+Project knowledge wiki maintenance protocol. Agents and Leader follow these rules to keep the wiki accurate and useful.
+
+---
+
+## Page Format
+
+Every wiki page uses this structure:
+
+```markdown
+# Title
+
+## Overview
+Brief description: what this is, why it exists.
+
+## Details
+In-depth content, code references, architecture notes, diagrams.
+
+## See Also
+- [[related-page]]
+
+## Last Updated
+Sprint <N> (<date or "init">)
+```
+
+### Page Types
+
+| Type | Location | Naming | Purpose |
+|------|----------|--------|---------|
+| Module | `wiki/modules/<dir-name>.md` | matches top-level directory name | per-module documentation |
+| Decision | `wiki/decisions/<NNN>-<slug>.md` | numbered, append-only | architectural decision records |
+| Pattern | `wiki/patterns/<pattern-name>.md` | descriptive slug | reusable design patterns |
+| Entity | `wiki/entities/<entity-name>.md` | domain noun | domain model entities |
+
+---
+
+## Update Rules
+
+### Sprint-Level Updates
+
+1. **Contract declaration**: Sprint contracts SHOULD include a `## Wiki Impact` section listing wiki pages that need updating.
+2. **Agent responsibility**: When a Sprint modifies code in a module, the agent SHOULD update the corresponding `wiki/modules/<name>.md` page with relevant changes.
+3. **Leader validation**: During post-merge review (Step 7), Leader checks if code-changed modules have corresponding wiki page updates. Missing updates are logged to `wiki/log.md` as warnings, not treated as blockers.
+
+### Update Workflow
+
+```
+1. Agent modifies code in src/auth/
+2. Agent updates wiki/modules/src.md (or wiki/modules/auth.md if nested)
+3. Agent updates "## Last Updated" to current Sprint number
+4. Leader verifies wiki update in post-merge diff review
+5. If missed: Leader appends warning to wiki/log.md
+```
+
+### Decision Records
+
+- Create a new decision record when making significant architectural choices.
+- Decision records are append-only — never modify past decisions.
+- Format: `decisions/<NNN>-<descriptive-slug>.md` where NNN is zero-padded sequential.
+- Include: context, options considered, chosen option, rationale, consequences.
+
+---
+
+## Lint Rules
+
+These rules detect wiki staleness and inconsistency:
+
+### 1. Page Count vs Module Count
+Every code-bearing top-level directory should have a corresponding `wiki/modules/<name>.md` page. Run `selfmodel adapt` to auto-generate missing pages.
+
+**Detection**: Compare `ls -d */` (excluding ignored dirs) against `ls wiki/modules/*.md`.
+
+### 2. Stale Pages
+Pages not updated in the last 10 Sprints are flagged as potentially stale.
+
+**Detection**: Parse `## Last Updated` line, extract Sprint number, compare against current Sprint from `team.json`.
+
+### 3. Broken Internal Links
+Wiki links (`[[target]]`) must resolve to an existing `.md` file under `wiki/`.
+
+**Detection**: Extract all `[[...]]` references, verify each resolves to a file at `wiki/<reference>.md`.
+
+### 4. Empty Pages
+Pages with 3 or fewer non-blank lines are flagged as stubs needing content.
+
+**Detection**: `awk 'NF' <file> | wc -l` for each wiki page.
+
+---
+
+## Auto-Sync Spec
+
+Post-merge automation to detect wiki-code drift:
+
+### Trigger
+After each Sprint merge to main.
+
+### Detection Logic
+```bash
+# 1. Get changed code files from Sprint
+changed_dirs=$(git diff --name-only HEAD~1..HEAD | \
+  grep -v '^\.' | \
+  cut -d/ -f1 | \
+  sort -u)
+
+# 2. For each changed dir, check if wiki page was also updated
+for dir_name in $changed_dirs; do
+    wiki_page="wiki/modules/${dir_name}.md"
+    if [ -f ".selfmodel/$wiki_page" ]; then
+        # Check if wiki page was in the diff
+        if ! git diff --name-only HEAD~1..HEAD | grep -q ".selfmodel/$wiki_page"; then
+            # Wiki page exists but was not updated
+            echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] WARN: ${dir_name} code changed but wiki page not updated" >> .selfmodel/wiki/log.md
+        fi
+    fi
+done
+```
+
+### Output
+Warnings are appended to `wiki/log.md`. They are informational — they do not block merges or fail CI.
+
+---
+
+## Wiki Scaffolding
+
+### During `selfmodel init`
+1. `create_structure()` creates `wiki/{modules,decisions,patterns,entities}` with `.gitkeep` files.
+2. `generate_wiki()` creates:
+   - `schema.md` — page format conventions
+   - `modules/<name>.md` — skeleton page for each detected code-bearing directory (max 20)
+   - `architecture.md` — seeded from `detect_stack` results
+   - `index.md` — listing all generated pages
+   - `log.md` — with initial INIT entry
+
+### During `selfmodel adapt`
+1. If `wiki/` missing → full `generate_wiki()` run.
+2. If `wiki/` exists → `reconcile_wiki()`:
+   - Scan for new code-bearing directories not yet in `wiki/modules/`.
+   - Generate skeleton pages for new modules.
+   - Rebuild `index.md` from current state.
+   - Append ADAPT entry to `log.md`.
+
+### Excluded Directories
+The following directories are never treated as modules:
+`.git`, `node_modules`, `__pycache__`, `.venv`, `venv`, `vendor`, `dist`, `build`, `.selfmodel`, `.claude`, `.github`, `.vscode`, `.idea`, `.next`, `.nuxt`, `coverage`, `tmp`, `temp`, `.cache`, `.turbo`, `target`, `out`, `bin`, `obj`

CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.0] - 2026-04-07
+
+### Added
+- **Project Wiki** — auto-generated knowledge base at `.selfmodel/wiki/`, woven into existing flows:
+  - `selfmodel init` scaffolds wiki with detected module pages and architecture overview
+  - Session-start hook injects wiki/index.md into Leader context
+  - Sprint contracts gain `## Wiki Impact` section for agent wiki updates
+  - Post-merge Step 7.6 detects stale wiki pages from code diffs
+  - `selfmodel status` reports wiki health score (pages, staleness, completeness)
+  - Inspired by [Karpathy's LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
+- **Evolution-to-PR Pipeline** (`selfmodel evolve`) — detect local improvements, classify generalizability, submit upstream PRs:
+  - 5 generalizability heuristics (path detection, project name, generic pattern, hook fix, scoring calibration)
+  - 4-phase pipeline: DETECT → STAGE → SUBMIT → TRACK
+  - Orchestration loop Step 8.5 auto-triggers detection every 10 merged sprints
+  - Human approval gate before any PR submission
+- **Wiki Protocol** (`wiki-protocol.md`) — page format, update rules, lint rules, auto-sync spec
+- **Evolution Protocol** (`evolution-protocol.md`) — full pipeline spec with schema, heuristics, PR template
+
+### Changed
+- **CLI consolidated** — smart dashboard as default (`selfmodel` with no args), idempotent init (absorbs adapt), interactive evolve default, two-tier help
+- **`selfmodel init`** is now idempotent — safe to re-run on existing projects (runs adapt logic)
+- **`selfmodel adapt`** deprecated — prints warning, delegates to `selfmodel init`
+- **`selfmodel evolve`** (no flags) runs full interactive pipeline (detect → stage → offer submit), was detect-only
+- **`selfmodel`** (no args) shows smart dashboard with next-action suggestion, was help text
+- **Help text** split into two tiers: dashboard shows 8-line reference, `--help` shows full detail
+- **README** restructured: 3-step quickstart, Terminal vs Claude Code command tables
+- Slash commands `/selfmodel:init`, `/selfmodel:status`, `/selfmodel:evolve` marked as convenience (CLI preferred)
+
+### Fixed
+- **bash 3.2 compatibility** — replaced `unset 'array[-1]'` (requires bash 4.3+) with portable `_wiki_find_code()` helper for macOS default bash
+- **`cmd_evolve` exit vs return** inconsistency — `exit 1` changed to `return 1`
+
 ## [0.3.0] - 2026-04-05
 
 ### Added

CLAUDE.md

@@ -254,6 +254,7 @@ Contract template → read `.selfmodel/playbook/sprint-template.md`
 | E2E 验证协议 v2 | `.selfmodel/playbook/e2e-protocol-v2.md` |
 | 混沌渗透测试（Rampage） | `/rampage` skill (`~/.claude/skills/rampage/SKILL.md`) |
 | Context checkpoint + reset protocol | `.selfmodel/playbook/context-protocol.md` |
+| Wiki protocol + page format | `.selfmodel/playbook/wiki-protocol.md` |
 
 ## Context Management
 
@@ -266,6 +267,7 @@ Contract template → read `.selfmodel/playbook/sprint-template.md`
 2. Read .selfmodel/state/next-session.md (last handoff)
 3. Read .selfmodel/state/team.json (team state)
 4. Scan .selfmodel/contracts/active/ (pending contracts)
+4.5. Scan .selfmodel/wiki/index.md (wiki catalog — auto-injected by session-start hook)
 5. PRE-FLIGHT CHECK:
    a. git branch --show-current → MUST be "main", else STOP and fix
    b. git worktree list → MUST show only main, else merge/discard orphan branches
@@ -348,6 +350,15 @@ selfmodel/
     ├── inbox/evaluator/               # Leader→Evaluator eval files
     ├── inbox/e2e/                     # Leader→E2E Agent v2 验证任务
     ├── artifacts/                     # 验证产物（E2E 截图/日志 + Rampage 韧性报告）
+    ├── wiki/                          # Project knowledge base (auto-managed)
+    │   ├── index.md                   # Content catalog
+    │   ├── log.md                     # Update log (append-only)
+    │   ├── schema.md                  # Page conventions
+    │   ├── architecture.md            # System overview
+    │   ├── modules/                   # Per-module pages
+    │   ├── decisions/                 # Architecture Decision Records
+    │   ├── patterns/                  # Code patterns
+    │   └── entities/                  # Key concepts
     ├── state/team.json                # Team state
     ├── state/next-session.md          # Session handoff
     ├── state/plan.md                  # Orchestration plan (phases + sprints)