chore(kb): bootstrap sdd knowledge base

.claude/commands/garden.md

@@ -0,0 +1,236 @@
+You are a doc-gardening agent for a repository that uses sdd-knowledge.
+Your job: maintain knowledge/ — verify docs match code, update docs from user intent,
+and discover new documentation that should be migrated into the knowledge structure.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+If `$ARGUMENTS` is `help`, `--help`, or `-h`, show this usage and stop:
+
+```
+/garden              — Full maintenance: verify claims, fix drift, discover & migrate new docs.
+/garden <text>       — Same as above, plus update knowledge based on <text>.
+                       e.g. /garden we switched from JWT to session cookies
+                       e.g. /garden deployment now uses k8s instead of ECS
+                       e.g. /garden added new error handling middleware in src/middleware/errors.ts
+/garden help         — Show this help.
+```
+
+---
+
+## Phase 1: Structural audit
+
+Run `sdd-knowledge . --garden --dry-run` first to report structural errors without making
+changes. If it reports fixable structural issues (broken links, missing index.md,
+constitution drift), run `sdd-knowledge . --garden` to apply those fixes before proceeding.
+
+---
+
+## Phase 2: Update from user intent (only when `$ARGUMENTS` has text)
+
+Skip this phase if `$ARGUMENTS` is empty.
+
+The user has new information — a design change, architectural decision, convention update,
+or factual correction — and wants the right knowledge files updated without manually
+finding them.
+
+### Step 2.1: Extract update intent
+
+From the user's text, extract:
+- **Topic keywords** — the subject area (e.g., "auth", "deployment", "testing strategy")
+- **What changed** — the factual delta (e.g., "JWT → session cookies")
+- **Why** (if stated) — rationale for the change
+
+### Step 2.2: Find affected knowledge files
+
+Search for candidate files using multiple signals (in priority order):
+1. **Grep knowledge/ for topic keywords** — primary signal, search file contents
+2. **Check constitution.md** — scan the table of contents for matching sections
+3. **Check frontmatter tags** — grep for `tags:.*<keyword>` in knowledge/ files
+4. **Category hints** — maps topic keywords to knowledge/ paths using the default
+   profile remap. Non-exhaustive; grep results are the primary signal:
+   - auth/authentication/JWT/OAuth → `security/auth`
+   - deploy/k8s/kubernetes/docker → `ci/deployment` or `ci/workflows`
+   - test/testing/coverage/quality → `tests` or `tests/quality`
+   - build/compile/bundle → `build`
+   - api/endpoint/rest/graphql → `architecture` or `design/api`
+   - pattern/recipe/approach → `patterns`
+   - convention/style/lint → `code-conventions/code-style`
+   - logging/metrics/tracing/alerting → `observability`
+   - git/commit/branch/PR → `code-conventions/git`
+   - onboarding/getting-started/how-to → `guides`
+   - decision/ADR/rationale/trade-off → `code-conventions/decisions`
+   - library/sdk/utility/shared → `libs`
+   - design/UI/UX/wireframe → `design` (only if profile like `--fe` exists)
+   - feature/user-story/epic → `specs`
+   - workflow/setup/script/docker → `ci/workflows`
+   - product/roadmap/requirement/KPI → `specs` or `specs/business`
+
+Collect all matching files. If no matches found, tell the user no knowledge files
+reference this topic — nothing to update.
+
+### Step 2.3: Present plan and get confirmation
+
+Show the user what you found and what you plan to change:
+
+```
+Found N knowledge files related to "<topic>":
+
+1. knowledge/security/auth/jwt-auth.md — mentions JWT auth flow (lines 12-34)
+2. knowledge/patterns/api-auth.md — references JWT token validation
+3. knowledge/architecture/backend/api-layer.md — auth middleware section
+
+Planned changes:
+- File 1: Replace JWT auth flow description with session cookie approach
+- File 2: Update token validation to session validation
+- File 3: Update auth middleware reference
+
+Proceed? (y/n, or adjust)
+```
+
+**Always get confirmation before writing.** The user may want to narrow scope or adjust.
+
+### Step 2.4: Apply updates
+
+For each confirmed file:
+1. Read the full file content
+2. Update the relevant sections — change factual claims to match the new reality
+3. **Update frontmatter**:
+   - Set `verified:` to today's date
+   - Update `tags:` if the topic tags changed (e.g., remove `jwt`, add `session-cookies`)
+   - Leave `contentHash:` for `sdd-knowledge --garden` to regenerate (it computes
+     SHA-256 from the file body with exact newline preservation — manual hashing is fragile)
+4. Preserve document structure, tone, and Diataxis type
+5. Keep changes minimal — only update what the user's input affects
+
+### Step 2.5: Report changes
+
+```
+Updated N files:
+
+| File | What changed | Frontmatter updated |
+|------|-------------|-------------------|
+| security/auth/jwt-auth.md | Replaced JWT flow → session cookies | verified, tags, contentHash |
+| patterns/api-auth.md | Updated validation approach | verified, contentHash |
+```
+
+---
+
+## Phase 3: Verify claims against codebase
+
+For each .md file under knowledge/ (skip index.md and .originals/):
+
+1. Read the file content
+2. Extract factual claims about the codebase — libraries used, architecture patterns,
+   conventions, file paths, API contracts, deployment steps, etc.
+3. Search the codebase (grep, glob, read files) to verify each claim
+4. Classify each claim:
+   - CURRENT — evidence supports it
+   - STALE — partially true but details have changed
+   - OUTDATED — contradicted by current code
+   - UNVERIFIABLE — no evidence found either way
+
+For STALE/OUTDATED claims:
+- If the fix is obvious (e.g. library name changed, file moved), update the doc directly
+- If ambiguous (e.g. feature might have been intentionally removed), add a comment:
+  `<!-- needs-review: [reason] -->`
+- Never delete content you're unsure about
+
+For UNVERIFIABLE claims:
+- Leave them but add: `<!-- unverified: could not find supporting code -->`
+
+**Output** — summary table:
+
+| File | Claims checked | Current | Stale | Outdated | Unverifiable | Actions taken |
+
+---
+
+## Phase 4: Discover and migrate new documentation
+
+Find `.md` files outside `knowledge/` that should be migrated into the knowledge structure.
+
+### Step 4.1: CLI discovery
+
+```bash
+sdd-knowledge . --garden --dry-run
+```
+
+Review output for "new source detected" lines. These are files the CLI's classifier
+(check #12, incremental sync) identified but hasn't migrated yet.
+
+### Step 4.2: Broader search
+
+The CLI only finds files matching its built-in discovery patterns. Also check for:
+
+1. **Glob for all .md files outside knowledge/**:
+   - `**/*.md` excluding: `knowledge/`, `node_modules/`, `.git/`, `.originals/`,
+     `.claude/commands/`, `.claude/skills/`, `.specify/`,
+     `CHANGELOG.md`, `LICENSE.md`
+2. **For each found file**, check if it's already tracked:
+   - Grep `knowledge/` for `source: <relative-path>` in YAML frontmatter
+     or legacy `<!-- source: <relative-path> -->` HTML comments
+   - If either format is found → already tracked, skip
+3. **For untracked files with >50 lines of content** (skip thin stubs):
+   - Read the file
+   - Classify by topic keywords against the knowledge category list
+   - Assess whether content is substantive documentation vs. project scaffolding
+
+### Step 4.3: Present migration plan
+
+If new documentation files are found, show:
+
+```
+Found N untracked documentation files:
+
+| # | Source file | Proposed location | Category | Confidence |
+|---|-------------|------------------|----------|------------|
+| 1 | docs/auth-guide.md | knowledge/security/auth/ | security | high |
+| 2 | .github/CONTRIBUTING.md | knowledge/guides/ | guides | medium |
+| 3 | notes/perf-tuning.md | knowledge/quality/ | quality | low |
+
+Migrate? (all / select by number / none)
+```
+
+If no new files found, report: "No untracked documentation files found."
+
+### Step 4.4: Migrate confirmed files
+
+For each confirmed file:
+1. Read source content
+2. Generate YAML frontmatter:
+   - `category:` from classification
+   - `subcategory:` if placing under a subcategory directory
+   - `source:` relative path to the original file
+   - `verified:` today's date
+   - `confidence:` based on classification score (>20=high, 10-20=medium, <10=low)
+   - `documentType:` infer Diataxis type from category defaults
+   - `tags:` extract top keywords
+   - `contentHash:` leave empty — `sdd-knowledge --garden` will compute it
+   - `scope:` `org` if generic, `repo` if references project-specific paths/entities
+3. Write to `knowledge/<category>/<subcategory>/<slugified-name>.md`
+4. Do NOT move or delete the original file — knowledge/ gets a copy
+
+---
+
+## Phase 5: Final audit
+
+1. Run `sdd-knowledge . --garden` to rebuild indexes, regenerate `contentHash` values,
+   and confirm no structural issues remain (this catches issues introduced by Phases 2-4)
+2. Summarize everything done across all phases
+
+---
+
+## Rules
+
+- Do NOT modify index.md files (they are auto-generated by sdd-knowledge)
+- Do NOT modify files in knowledge/.originals/
+- Keep changes minimal — fix/update what's needed, don't rewrite what's fine
+- If a knowledge file references code that was entirely deleted, flag it for human review
+  rather than deleting the doc
+- Always preserve existing frontmatter fields you're not explicitly updating
+- Leave `contentHash` regeneration to `sdd-knowledge --garden` (Phase 5) — do not compute manually
+- When migrating new files, you MAY create new files/dirs under knowledge/
+- When verifying or updating existing files, do NOT change the knowledge/ directory structure