feat(landscape): add persistent codebase knowledge document

CLAUDE.md

@@ -51,6 +51,7 @@ Skills reference shared protocols in `protocols/` for fragile operations:
 - `context.md` -- Anchor doc and config loading
 - `insights.md` -- External Claude Code insights data access
 - `learning-lifecycle.md` -- Compaction triggers and tiered memory
+- `landscape.md` -- Codebase reference document format and freshness rules
 
 ## Key Rules
 

DESIGN.md

@@ -34,6 +34,11 @@ How the user wants code written. Testing standards, coding conventions, security
 **CHARTER.md** -- Technology Vision
 What is this repo? What are we building? Who are the consumers? Architectural invariants. The things that don't change. Referenced by plan to ensure alignment, validated by verify.
 
+## Reference Documents
+
+**LANDSCAPE.md** -- Codebase Knowledge (optional)
+Persistent cache of codebase structure: architecture, modules, conventions, integration points, gotchas. Not an anchor document — it accelerates design research but never blocks workflow. Created by sw-init (survey phase), read by sw-design (with inline refresh when stale), incrementally updated by sw-learn after shipping. Format and freshness rules in `protocols/landscape.md`.
+
 ## Skills (14)
 
 ### User-Facing (9)
@@ -105,8 +110,9 @@ Extracted once in `protocols/`, referenced by skills. Loaded on demand.
 | `context.md` | Config/state/anchor doc loading | ~100 |
 | `insights.md` | External CC insights data access | ~150 |
 | `learning-lifecycle.md` | Compaction triggers, tier structure, theme format | ~150 |
+| `landscape.md` | Codebase reference doc format, freshness, updates | ~180 |
 
-Total: ~1850 tokens (loaded on demand, not all at once).
+Total: ~2030 tokens (loaded on demand, not all at once).
 
 ## Skill Anatomy
 
@@ -180,6 +186,7 @@ Runtime state (created by init):
 ├── config.json       # Project configuration
 ├── CONSTITUTION.md   # Development practices
 ├── CHARTER.md        # Technology vision
+├── LANDSCAPE.md      # Codebase knowledge (optional)
 ├── state/
 │   └── workflow.json # Current state
 └── work/             # Work unit artifacts (specs, evidence, plans)

README.md

@@ -196,7 +196,7 @@ See `DESIGN.md` for the complete architecture document.
 ```
 specwright/
 ├── skills/       # 14 SKILL.md files (9 user + 5 gates)
-├── protocols/    # 10 shared protocols (loaded on demand)
+├── protocols/    # 11 shared protocols (loaded on demand)
 ├── agents/       # 6 custom subagent definitions
 ├── hooks/        # Session lifecycle hooks
 ├── DESIGN.md     # Full architecture

protocols/context.md

@@ -14,6 +14,11 @@ Load when needed for alignment/verification:
 ### State
 - `.specwright/state/workflow.json` — Current progress, gate results, lock status
 
+### Reference Documents
+Load on demand when codebase structure knowledge is needed:
+
+- `.specwright/LANDSCAPE.md` — Codebase architecture and module knowledge (optional)
+
 ## Initialization Checks
 
 **Before any operation:**

protocols/landscape.md

@@ -0,0 +1,33 @@
+# Landscape Protocol
+
+## Format
+
+`.specwright/LANDSCAPE.md` is a reference document (not an anchor document). Optional. Never blocks workflow.
+
+Required metadata header:
+```
+Snapshot: {ISO 8601 timestamp}
+Files: {count} | Modules: {count}
+```
+
+Required sections: Architecture, Modules (per-module: purpose, key files, public API, dependencies), Conventions, Integration Points, Gotchas.
+
+## Size
+
+- Small projects: 500-1000 words
+- Large projects: 1500-2500 words
+- Hard cap: 3000 words
+
+## Freshness
+
+Parse `Snapshot:` timestamp. Default staleness threshold: 7 days. Configurable via `config.landscape.stalenessThresholdDays` (optional field, default 7).
+
+- Fresh: use as-is
+- Stale: consumer warns user, may refresh inline
+- Missing: no warning, proceed without
+
+## Updates
+
+- **Full rewrite**: initial generation and refresh (replace entire document)
+- **Incremental merge**: post-ship updates (re-scan affected modules only, preserve unchanged sections, update timestamp)
+- Module granularity: one section per logical module, package, or top-level directory

skills/sw-design/SKILL.md

@@ -56,8 +56,8 @@ When warranted: `decisions.md`, `data-model.md`, `contracts.md`, `testing-strate
 - Default to Full when uncertain.
 
 **Research (HIGH freedom):**
-- Understand the codebase BEFORE designing. Scan code, dependencies, APIs, existing patterns.
-- Check `.specwright/patterns.md` and `.specwright/learnings/INDEX.md` if they exist. Reference relevant patterns in design.md.
+- If `.specwright/LANDSCAPE.md` exists, load it first. If stale per `protocols/landscape.md`, refresh inline and update `Snapshot:` timestamp. If missing, proceed without. Use as baseline for research.
+- Scan code, dependencies, APIs, existing patterns. Check `.specwright/patterns.md` and `.specwright/learnings/INDEX.md` if they exist.
 - Delegate to `specwright-researcher` (external docs) and `specwright-architect` (deep analysis) as needed.
 - Produce `context.md` summarizing findings for downstream agents.
 
@@ -70,7 +70,7 @@ When warranted: `decisions.md`, `data-model.md`, `contracts.md`, `testing-strate
 - Skip for straightforward requests.
 
 **Change requests (MEDIUM freedom):**
-- If `design.md` exists with argument: treat as change request, re-run critic. Without argument: ask — redesign, continue, or describe changes.
+- `design.md` exists + argument: change request, re-run critic. No argument: ask — redesign, continue, or changes.
 
 **User checkpoints:**
 - Ask for hard constraints before research (record in design.md). Share findings after research, alternatives after design, resolutions after critic.
@@ -88,6 +88,7 @@ When warranted: `decisions.md`, `data-model.md`, `contracts.md`, `testing-strate
 - `protocols/context.md` -- anchor doc and config loading
 - `protocols/delegation.md` -- agent delegation for research and critic
 - `protocols/recovery.md` -- compaction recovery
+- `protocols/landscape.md` -- codebase reference document format
 
 ## Failure Modes
 

skills/sw-init/SKILL.md

@@ -40,10 +40,12 @@ When complete, ALL of the following exist:
 ## Constraints
 
 **Detection (MEDIUM freedom):**
-- Scan the codebase to detect: language(s), framework(s), package manager,
-  test runner, existing linting/formatting, git workflow, CI/CD presence.
-- Read dependency manifests (package.json, go.mod, requirements.txt, Cargo.toml, etc.).
-- Don't guess what you can detect. Don't ask what you can infer.
+- Scan codebase: language(s), framework(s), package manager, test runner, linting/formatting, git workflow, CI/CD. Read dependency manifests. Don't guess what you can detect.
+
+**Survey (MEDIUM freedom):**
+- After detection, survey the codebase using Glob/Grep/Read: directory structure, entry points, module dependencies, conventions, integration points, gotchas.
+- Produce `.specwright/LANDSCAPE.md` per `protocols/landscape.md` format. User approves before saving.
+- Optional — if user declines, skip. LANDSCAPE.md is never required.
 
 **User conversation (HIGH freedom):**
 - Ask the user about things you CANNOT detect from the codebase:
@@ -71,38 +73,27 @@ When complete, ALL of the following exist:
 - The user must approve the charter before it's saved.
 
 **Git workflow configuration (MEDIUM freedom):**
-- Detect git workflow by scanning:
-  - Branch names (`git branch -a`): look for `develop`, `release/*`, `hotfix/*` (→ gitflow), feature branches (→ github-flow/trunk-based)
-  - Remote configuration (`git remote -v`)
-  - CI files referencing branch names (`.github/workflows/*.yml`, `.gitlab-ci.yml`, `Jenkinsfile`)
-- Present detected workflow with confidence level to the user.
-- Use AskUserQuestion to confirm or override:
-  - Strategy: trunk-based, github-flow, gitflow, custom
-  - Branch prefix (default: `feat/` or detected)
-  - Merge strategy: squash, rebase, merge
-  - PR required: yes/no
-  - Commit format: conventional, freeform, custom
-- Store results in `config.json` `git` section. See `protocols/git.md` for field reference.
-- If existing `config.json` has old git schema (missing new fields like `mergeStrategy`, `prRequired`, `branchPerWorkUnit`): offer to migrate by adding new fields with sensible defaults.
+- Detect workflow by scanning branch names, remotes, CI files. Present detected strategy with confidence.
+- Confirm via AskUserQuestion: strategy (trunk-based/github-flow/gitflow/custom), branch prefix, merge strategy, PR required, commit format.
+- Store in `config.json` `git` section per `protocols/git.md`.
+- If old git schema detected: offer migration with sensible defaults.
 
 **Configuration (LOW freedom):**
 - Write `.specwright/config.json` with detected and configured values.
 - Create `.specwright/state/workflow.json` with empty initial state.
-- Create directory structure: `.specwright/state/`, `.specwright/work/`, `.specwright/baselines/`, `.specwright/learnings/`.
+- Create directory structure: `.specwright/state/`, `.specwright/work/`, `.specwright/baselines/`, `.specwright/learnings/`. If survey produced LANDSCAPE.md, include it (optional).
 - Follow `protocols/state.md` for state file format.
 
 **Gate configuration (MEDIUM freedom):**
-- Ask the user which quality checks matter to them.
-- Default gates: build, security, spec-compliance. Others based on what's available.
-- If the project has a test runner: enable test quality gate.
-- If the project has a linter: enable lint gate.
-- Configure thresholds based on user's stated expectations.
+- Ask user which quality checks matter. Defaults: build, security, spec-compliance.
+- Enable test/lint gates if detected. Configure thresholds per user expectations.
 
 ## Protocol References
 
 - `protocols/state.md` -- workflow.json initialization
 - `protocols/context.md` -- config.json format
 - `protocols/git.md` -- git config field reference and strategy definitions
+- `protocols/landscape.md` -- codebase reference document format
 
 ## Failure Modes
 

skills/sw-learn/SKILL.md

@@ -9,6 +9,7 @@ allowed-tools:
   - Read
   - Write
   - Edit
+  - Bash
   - Glob
   - Grep
   - AskUserQuestion
@@ -70,19 +71,18 @@ work benefits.
 - If directory empty, missing, or <2 files: silently skip.
 
 **Persistence (LOW freedom):**
-- Write `.specwright/learnings/{work-id}.json` only when at least one finding is promoted. No file on all-dismissed.
-- Schema: `{ workId, timestamp (ISO 8601), findings: [{ category, source, description, proposedRule, disposition }] }`
-- Categories: `build | security | testing | architecture | friction`. Sources: `gate-evidence | git-log | plan | insights`. Dispositions: `promoted-constitution | promoted-patterns | dismissed`.
+- Write `.specwright/learnings/{work-id}.json` only when at least one finding is promoted.
+- Schema: `{ workId, timestamp, findings: [{ category, source, description, proposedRule, disposition }] }`
+
+**Landscape update (MEDIUM freedom):**
+- After persistence, if `.specwright/LANDSCAPE.md` exists: identify affected modules from evidence and plan artifacts, re-scan those modules, merge updates. Show diff, user approves. Update `Snapshot:` timestamp.
+- If LANDSCAPE.md doesn't exist: silently skip.
 
 **Enrichment (MEDIUM freedom):**
-- Optional phase governed by `protocols/insights.md` for session pattern enrichment.
-- Reference the protocol for facets, privacy, staleness, and fallback behavior.
-- Silently skip if insights unavailable or stale per protocol rules.
+- Optional per `protocols/insights.md`. Silently skip if unavailable or stale.
 
 **Compaction (MEDIUM freedom):**
-- Runs after persistence when triggers met, governed by `protocols/learning-lifecycle.md`.
-- Groups raw learnings into themed summaries with INDEX.md. Reference protocol for thresholds and formats.
-- Silently skip if threshold not met per protocol rules.
+- Per `protocols/learning-lifecycle.md`. Silently skip if threshold not met.
 
 ## Protocol References
 
@@ -91,6 +91,7 @@ work benefits.
 - `protocols/state.md` -- workflow state reading
 - `protocols/insights.md` -- session pattern enrichment
 - `protocols/learning-lifecycle.md` -- compaction triggers and lifecycle
+- `protocols/landscape.md` -- codebase reference document format
 
 ## Failure Modes