superspecs 0.1.0 → 0.2.0

package/.skills/verify-wiki/SKILL.md

@@ -11,6 +11,8 @@ You are distilling the completed feature into the living project wiki.
 
 The feature works. The tests pass. Now you extract the knowledge that should survive beyond this session — so future planning, future features, and future sessions start informed.
 
+The wiki lives at `superspec/wiki/` and doubles as an **Obsidian vault**. Write every page to be navigable in Obsidian: use `[[wikilinks]]` for internal links, YAML frontmatter with `tags:`, and keep each page focused on a single knowledge unit.
+
 ## What to distill (and what not to)
 
 **Distill:**
@@ -26,6 +28,23 @@ The feature works. The tests pass. Now you extract the knowledge that should sur
 - Task checklists or execution logs
 - The full spec (it lives in `superspec/specs/`)
 
+## Provenance
+
+Mark the origin of every claim so future readers know what is fact vs. synthesis:
+
+- Default (no marker): directly extracted from source material
+- `^[inferred]` — synthesized by the agent; not stated verbatim in sources
+- `^[ambiguous]` — sources disagree or the claim is uncertain
+
+Example:
+```
+The team chose Redis over Postgres for session storage because of latency requirements.
+A TTL of 15 minutes was selected as the balance point. ^[inferred]
+Note: the DISCUSS.md mentions 10 minutes but the spec says 15 — see review-log. ^[ambiguous]
+```
+
+---
+
 ## Steps
 
 ### 1. Gather the source material
@@ -36,26 +55,87 @@ Read:
 - `superspec/phases/<slug>-execute/review-log.md`
 - The implementation itself (key files touched)
 
-### 2. Determine wiki structure
+---
+
+### 2. Scan existing wiki pages first
+
+**Before writing anything new**, scan the existing wiki for related content.
+
+```
+superspec/wiki/
+├── Home.md              ← read first: domain index
+├── log.md               ← read: recent activity
+└── <domain>/
+    ├── Home.md          ← domain index
+    └── *.md             ← existing knowledge pages
+```
+
+For each existing page that overlaps with this feature:
+- **Update it** — don't create a duplicate. Add a new `## <New Section>` or extend existing sections.
+- Mark it with `updated: <today>` in the YAML frontmatter.
+- Note it in the "pages_updated" list for the manifest and log.
+
+**Rule:** One knowledge unit = one page. Merge, don't proliferate.
+
+---
+
+### 3. Determine wiki structure
+
+Read `superspec/wiki/_meta/taxonomy.md` → build the canonical domain set from the `## Domains` table.
+
+**Domain routing — use this decision tree for every knowledge unit:**
+
+1. **Reusable cross-cutting pattern** (error handling, caching, retry, logging, testing patterns)?  
+   → `patterns/`
+
+2. **Architecture decision** — why X was chosen over Y, with trade-offs documented?  
+   → `decisions/`
+
+3. **Authentication, authorization, sessions, or tokens**?  
+   → `auth/`
+
+4. **API contract, endpoint design, versioning, or request/response shape**?  
+   → `api/`
+
+5. **Data model, schema, or storage decision**?  
+   → `data/`
+
+6. **Infrastructure, deployment, CI/CD, or environment config**?  
+   → `infra/`
+
+7. **Frontend, UI component, routing, or styling pattern**?  
+   → `ui/`
 
-Check `superspec/wiki/_index.md`. Identify:
-- Which domain folder this belongs in (create one if needed)
-- Whether any existing pages should be updated vs. new pages created
+8. **Feature-specific knowledge that fits none of the above**?  
+   → Create a domain named after the feature slug (e.g. `payment-flow/`)  
+   → Add the new domain to `_meta/taxonomy.md` under "Project Domains" before creating the folder
 
-Domain examples: `auth/`, `api/`, `data/`, `ui/`, `infra/`, `patterns/`, `decisions/`
+**Rules:**
+- **One domain per page.** If a page spans multiple concerns, split it into separate pages.
+- **Prefer existing domains.** Only create a new domain if nothing in the taxonomy fits.
+- **Feature traceability lives in `spec:` frontmatter**, not in the folder name. A `payment-flow` feature can have pages in `api/`, `data/`, and `patterns/` — all tagged `spec: "[[payment-flow]]"`.
 
-### 3. Write wiki pages
+After routing: does the chosen domain folder have a `Home.md`? If not, create a domain index listing its pages.
 
-For each meaningful knowledge unit:
+---
+
+### 4. Write wiki pages
+
+For each new knowledge unit, create `superspec/wiki/<domain>/<topic>.md`:
 
 ```markdown
 ---
 title: <Page Title>
+summary: <1–2 sentence summary used for fast query previews — what this is and why it matters>
 tags: [<domain>, <feature-slug>, <topic-tags>]
-spec: superspec/specs/<slug>/spec.md
-created: <date>
-updated: <date>
-sources: [<slug>]
+spec: "[[<slug>]]"
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+provenance:
+  sources: [specs/<slug>/spec.md, phases/<slug>-execute/review-log.md]
+  extracted: ~70%
+  inferred: ~25%
+  ambiguous: ~5%
 ---
 
 # <Page Title>
@@ -74,9 +154,6 @@ When and why this was built. What problem it solves.
 **Because:** <reason>
 **Trade-off:** <what was given up>
 
-### <Decision Topic>
-...
-
 ## Patterns
 
 ### <Pattern Name>
@@ -100,26 +177,82 @@ When and why this was built. What problem it solves.
 - [ ] <Unresolved question deferred to future work>
 
 ## Related
-- [[<wikilink>]] — <what it covers>
+- [[<domain>/<page>]] — <what it covers>
 - `<path/to/key/file>` — <what it does>
 ```
 
-### 4. Update the wiki index
+**Provenance markers in body text:**
+- No marker = extracted directly from source material
+- `^[inferred]` = agent synthesis, not stated verbatim
+- `^[ambiguous]` = sources disagree or claim is uncertain
+
+**Obsidian linking rules:**
+- Internal links: always use `[[page-title]]` or `[[folder/page]]`, never markdown `[text](path.md)`
+- File references: use backtick code spans for source file paths (`src/auth/jwt.ts`)
+- Tags: lowercase, hyphenated (`auth`, `jwt-tokens`, `session-management`)
+- Tags must come from `_meta/taxonomy.md` if it exists; add new tags there if needed
+
+---
+
+### 5. Update the vault home page
 
-Update `superspec/wiki/_index.md`:
+Update `superspec/wiki/Home.md`:
 
 ```markdown
+---
+title: Wiki Home
+tags: [index, home]
+updated: <YYYY-MM-DD>
+---
+
+# Project Wiki
+
+...
+
 ## Domains
 
-- [[auth/]] — Authentication & authorization
-- [[<new-domain>/]] — <description>
+| Domain | Pages | Last updated |
+|--------|-------|-------------|
+| [[auth/Home\|auth]] | N | YYYY-MM-DD |
 
 ## Recent Updates
 
-- <date>: [[<domain>/<page>]] — <brief description> (from `<slug>`)
+_(last 10 — full history in [[log]])_
+
+- <YYYY-MM-DD>: [[<domain>/<page>]] — <brief description>
+```
+
+Each domain folder should also have its own `Home.md` listing its pages.
+
+---
+
+### 6. Cross-link
+
+After writing all pages:
+- Scan existing wiki pages for unlinked mentions of new page topics
+- Add `[[wikilinks]]` where relevant
+- Ensure the new pages link back to related existing pages
+
+Or invoke `/superspecs:cross-linker` to automate this step.
+
+---
+
+### 7. Append to log.md
+
+Append to `superspec/wiki/log.md` (create if missing):
+
+```markdown
+## [<YYYY-MM-DD>] ingest | <slug>: <feature title>
+
+- **Created:** <domain>/<page>.md, <domain>/<page2>.md
+- **Updated:** <domain>/<existing>.md
+- **Domains touched:** <domain1>, <domain2>
+- **Spec:** [[../specs/<slug>/spec.md]]
 ```
 
-### 5. Update the manifest
+---
+
+### 8. Update the manifest
 
 Update `superspec/wiki/_manifest.json`:
 
@@ -136,26 +269,23 @@ Update `superspec/wiki/_manifest.json`:
 }
 ```
 
-### 6. Cross-link
-
-After writing all pages:
-- Scan existing wiki pages for unlinked mentions of new page topics
-- Add `[[wikilinks]]` where relevant
-- Ensure the new pages link back to related existing pages
+---
 
-### 7. Update spec status
+### 9. Update spec status
 
 Update `superspec/specs/<slug>/status.md`:
 
 ```markdown
 ## Wiki Pages
-- [[superspec/wiki/<domain>/<page>]] — <what it covers>
+- [[<domain>/<page>]] — <what it covers>
 
 ## Phase
 3.2 — Verify › Wiki Import ✅
 ```
 
-### 8. Handoff
+---
+
+### 10. Handoff
 
 ```
 Wiki import complete: <slug>
@@ -165,16 +295,25 @@ Pages updated: Y
 
 superspec/wiki/
 ├── <domain>/
-│   ├── <page1>.md  (new)
-│   └── <page2>.md  (updated)
-└── _index.md (updated)
+│   ├── Home.md      (domain index)
+│   ├── <page1>.md   (new)
+│   └── <page2>.md   (updated)
+├── Home.md          (updated)
+└── log.md           (appended)
+
+Run /cross-linker to auto-weave [[wikilinks]] across the vault.
+Open superspec/wiki/ in Obsidian to browse the vault.
 
-Next: /ship <slug>
+Next: /superspecs:ship <slug>
 ```
 
+---
+
 ## Output
 
 - New/updated pages in `superspec/wiki/<domain>/`
-- Updated `superspec/wiki/_index.md`
+- Domain `Home.md` index (create if domain is new)
+- Updated `superspec/wiki/Home.md`
+- Appended `superspec/wiki/log.md`
 - Updated `superspec/wiki/_manifest.json`
 - Updated `superspec/specs/<slug>/status.md`

package/.skills/wiki-capture/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: wiki-capture
+description: Save findings from the current session directly to the wiki. Bugs fixed, decisions made, patterns discovered, gotchas hit. Quick mode stages a draft to raw/ for later ingest. Full mode distills directly to wiki pages. Triggers on /wiki-capture, "save to wiki", "capture this session", "note this for the wiki".
+slash_command: wiki-capture
+phase: "3.2 — Verify › Wiki Capture"
+---
+
+# Skill: wiki-capture
+
+You are capturing knowledge from the current session before it disappears.
+
+The context window is ephemeral. This skill saves what's worth keeping — decisions made, bugs fixed, patterns discovered, gotchas hit — directly to the wiki or to `raw/` for later ingest.
+
+Use this mid-session when something important happened that shouldn't be lost.
+
+---
+
+## Modes
+
+### `--quick` (default)
+Stage a structured draft to `superspec/wiki/raw/capture-<YYYY-MM-DD-HH-MM>.md`.  
+Fast: no subagent, no manifest update, no cross-linking.  
+The next `/wiki` or `/wiki-ingest` run will promote the raw file to proper pages.
+
+### `--full`
+Distill directly to proper wiki pages. Follows the full ingest process from `verify-wiki`.  
+Use when the session produced significant, self-contained knowledge worth filing immediately.
+
+---
+
+## Steps
+
+### 1. Scan the current session
+
+Review what happened in this session. Extract the following (drop noise):
+
+**Worth capturing:**
+- Decisions made (what was chosen, why, what was traded away)
+- Bugs found and fixed (what the bug was, root cause, fix)
+- Patterns established or discovered
+- Gotchas — things that took longer than expected
+- Interface or contract changes
+- Open questions that arose but weren't resolved
+
+**Drop:**
+- Step-by-step implementation details already in code
+- Routine task execution
+- Anything that's obvious from reading the code
+
+---
+
+### 2. Quick mode — stage to raw/
+
+Create `superspec/wiki/raw/capture-<YYYY-MM-DD-HH-MM>.md`:
+
+```markdown
+---
+capture_date: <YYYY-MM-DD HH:MM>
+session_context: <brief description of what this session was about>
+promote: true
+---
+
+# Session Capture: <YYYY-MM-DD>
+
+## Decisions
+
+### <Decision>
+**Chose:** <X>
+**Over:** <Y>
+**Because:** <reason>
+
+## Bugs Fixed
+
+### <Bug title>
+**Symptom:** <what it looked like>
+**Root cause:** <why it happened>
+**Fix:** <what resolved it>
+**Gotcha:** <anything surprising>
+
+## Patterns
+
+### <Pattern name>
+<What the pattern is and when to use it>
+
+## Open Questions
+
+- [ ] <Question that came up but wasn't resolved>
+
+## Files touched
+- `<path/to/file>` — <what changed and why>
+```
+
+Print:
+```
+Captured to superspec/wiki/raw/capture-<timestamp>.md
+
+Run /wiki to promote to proper wiki pages.
+Or the next /wiki <slug> run will pick it up automatically.
+```
+
+---
+
+### 3. Full mode — distill to wiki pages
+
+Follow the full ingest process from `verify-wiki`:
+
+1. Determine which domain(s) the captured knowledge belongs to
+2. Check existing pages — update rather than duplicate
+3. Write/update pages with full frontmatter including `summary:`, `provenance:`
+4. Mark inferred content `^[inferred]`
+5. Update domain `Home.md` and vault `Home.md`
+6. Append to `log.md`: `## [YYYY-MM-DD] capture | <topic>`
+7. Suggest running `/cross-linker` to weave new pages in
+
+---
+
+### 4. Always suggest
+
+After either mode:
+```
+Consider also running:
+  /cross-linker    Auto-weave [[wikilinks]] across the vault
+  /wiki-status     See what's now in the wiki
+```
+
+---
+
+## Output
+
+**Quick mode:**
+- `superspec/wiki/raw/capture-<timestamp>.md`
+
+**Full mode:**
+- New/updated wiki pages
+- Updated `Home.md` files
+- Appended `log.md`

package/.skills/wiki-lint/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: wiki-lint
+description: Health check the compiled wiki vault. Finds orphaned pages, missing cross-links, contradictions between pages, and stale file references. Triggers on /wiki-lint, "lint the wiki", "check wiki health". Run periodically or before starting a new cycle.
+slash_command: wiki-lint
+phase: "3.2 — Verify › Wiki Health"
+---
+
+# Skill: wiki-lint
+
+You are the wiki custodian. You run a structural and semantic health check on the compiled wiki at `superspec/wiki/`.
+
+The wiki is a compiled knowledge base. Like code, it accrues entropy: orphaned pages, broken links, contradictory claims, and stale file references. This skill finds those problems and produces an actionable report.
+
+**Read-only by default.** Only write if the user confirms fixes.
+
+---
+
+## The 3-Layer Context
+
+```
+superspec/wiki/raw/     ← source material (agent reads, never modifies)
+superspec/wiki/         ← compiled wiki (agent writes on ingest/query/lint-fix)
+.skills/wiki-lint/      ← schema: these instructions
+```
+
+Lint operates on the `wiki/` layer only. Never touch `raw/`.
+
+---
+
+## Steps
+
+### 1. Index all wiki pages
+
+Build a complete map of the vault:
+
+```
+for each .md file in superspec/wiki/ (excluding raw/, .obsidian/):
+  - record: path, title, tags, created, updated dates
+  - extract: all [[wikilinks]] referenced outward
+  - extract: all `file path` references (backtick spans)
+  - note: whether it appears in any other page as a [[wikilink]]
+```
+
+### 2. Run lint checks
+
+#### 2a. Orphaned pages
+A page is an orphan if no other wiki page links to it via `[[wikilink]]`.
+
+Exception: `Home.md`, domain `Home.md` indexes, and `log.md` are not orphans by design.
+
+#### 2b. Broken wikilinks
+A `[[wikilink]]` that does not resolve to any `.md` file in the vault.
+
+#### 2c. Missing cross-links
+Page A mentions a topic that has its own wiki page B, but doesn't link to B.
+
+Detection: for each page, check if its prose contains the exact title or common aliases of other wiki pages without a `[[wikilink]]`.
+
+#### 2d. Contradictions
+Two pages make conflicting factual claims about the same topic.
+
+Detection: look for pages with overlapping tags or domains that assert opposite things about the same decision, pattern, or interface. Flag for human review — don't auto-resolve.
+
+#### 2e. Stale file references
+Backtick file paths (`` `src/auth/jwt.ts` ``) that no longer exist in the project filesystem.
+
+Walk the actual project root and check each referenced path.
+
+#### 2f. Outdated pages
+Pages whose `updated:` date in frontmatter predates a related spec that was re-opened or re-shipped.
+
+Cross-reference `superspec/wiki/_manifest.json` ingestion timestamps.
+
+#### 2g. Missing frontmatter
+Pages missing required YAML fields: `title`, `tags`, `created`, `updated`.
+
+#### 2h. Undocumented domains
+A domain folder exists in `wiki/` but has no `Home.md` index.
+
+#### 2i. Domain drift
+A domain folder exists in `wiki/` but is not listed in `_meta/taxonomy.md`.
+
+1. Read `_meta/taxonomy.md` → build canonical domain set from `## Domains` table and "Project Domains" section
+2. Compare against actual subdirectory names in `superspec/wiki/` (excluding `raw/`, `_meta/`, `_archives/`, `.obsidian/`)
+3. Flag any folder that is not in the taxonomy as drift
+
+Drift is usually one of: a typo (`authenication/`), a duplicate (`auth-flow/` when `auth/` exists), or a new domain that was created but never registered. Each case needs a different fix — flag separately.
+
+---
+
+### 3. Write the lint report
+
+Write `superspec/wiki/_lint-report.md` (overwrite on each run):
+
+```markdown
+---
+title: Wiki Lint Report
+generated: <YYYY-MM-DD HH:MM>
+tags: [lint, health]
+---
+
+# Wiki Lint Report
+
+Generated: <YYYY-MM-DD HH:MM>
+Pages scanned: <N>
+
+## Summary
+
+| Check | Issues |
+|-------|--------|
+| Orphaned pages | N |
+| Broken wikilinks | N |
+| Missing cross-links | N |
+| Contradictions | N |
+| Stale file refs | N |
+| Outdated pages | N |
+| Missing frontmatter | N |
+| Undocumented domains | N |
+| Domain drift | N |
+
+**Total issues: N** (<critical> critical, <warning> warnings)
+
+---
+
+## Orphaned Pages
+
+> Pages with no inbound [[wikilinks]] from other wiki pages.
+
+- [ ] `<domain>/<page>.md` — no inbound links _(fix: link from `<domain>/Home.md` or a related page)_
+
+---
+
+## Broken Wikilinks
+
+> [[wikilinks]] that point to non-existent pages.
+
+- [ ] `<page>.md` line 42: `[[<missing-page>]]` — target not found _(fix: create the page or correct the link)_
+
+---
+
+## Missing Cross-Links
+
+> Page mentions a topic that has a wiki page but doesn't link to it.
+
+- [ ] `<page-a>.md` mentions "<topic>" — should link to [[<domain>/<page-b>]]
+
+---
+
+## Contradictions
+
+> Pages with conflicting claims. Requires human review.
+
+- [ ] `<page-a>.md` says: "<claim A>"
+      `<page-b>.md` says: "<claim B>"
+      _(topic: <shared tag or topic>)_
+
+---
+
+## Stale File References
+
+> Backtick file paths that no longer exist in the project.
+
+- [ ] `<wiki-page>.md`: `` `<missing/file.ts>` `` — file not found
+
+---
+
+## Outdated Pages
+
+> Pages whose `updated:` date predates a related re-ingested spec.
+
+- [ ] `<domain>/<page>.md` — last updated <date>, but spec `<slug>` was re-ingested <later-date>
+
+---
+
+## Missing Frontmatter
+
+> Pages missing required YAML fields.
+
+- [ ] `<domain>/<page>.md` — missing: `title`, `updated`
+
+---
+
+## Undocumented Domains
+
+> Domain folders without a Home.md index.
+
+- [ ] `<domain>/` — no Home.md _(fix: create domain index)_
+
+---
+
+## Domain Drift
+
+> Domain folders not listed in `_meta/taxonomy.md`. Possible typo, duplicate, or unregistered new domain.
+
+- [ ] `<domain>/` — not in taxonomy _(likely: typo / duplicate of `<canonical-domain>/` / new domain needing taxonomy entry)_
+
+---
+
+## Passed Checks
+
+- ✓ <N> pages with complete frontmatter
+- ✓ <N> wikilinks resolved correctly
+- ✓ <N> file references verified
+```
+
+---
+
+### 4. Append to log.md
+
+```markdown
+## [<YYYY-MM-DD>] lint | <N> issues found
+
+- Pages scanned: <N>
+- Critical: <N> | Warnings: <N>
+- Report: [[_lint-report]]
+```
+
+---
+
+### 5. Offer to fix
+
+After producing the report, ask the user:
+
+```
+Wiki lint complete: N issues found (X critical, Y warnings).
+
+Report: superspec/wiki/_lint-report.md
+
+Would you like me to fix:
+  [A] All auto-fixable issues (missing frontmatter, broken links with clear targets)
+  [B] Specific issues (list which)
+  [N] No — review manually in Obsidian
+
+Contradictions always require your decision before I change anything.
+```
+
+If the user confirms fixes, apply them and append a `## [date] lint-fix` entry to `log.md`.
+
+---
+
+## Output
+
+- `superspec/wiki/_lint-report.md` (overwritten)
+- Appended `superspec/wiki/log.md`
+- Optionally: fixed pages (with user confirmation)