open-harness/tasks/karpathy-llm-wiki/prd.json

{
    "schemaVersion": 1,
    "project": "Open Harness",
    "branchName": "feat/350-karpathy-llm-wiki",
    "description": "Karpathy LLM Wiki integration — adopt the three-layer (raw / wiki / schema) pattern with three skills (/wiki-ingest, /wiki-query, /wiki-lint) plus context/rules/wiki.md as the schema doc. Locked by /interview, audited by pm-agent ultrathink, gated by 2 critics; all HIGH findings mitigated in prd.md ACs.",
    "userStories": [
        {
            "id": "US-001",
            "title": "Scaffold wiki/ + context/rules/wiki.md schema rule + wiki/README.md template",
            "description": "As the orchestrator, I want a tracked wiki/ directory with a complete schema rule and an empty index template so subsequent skills have a known surface to write into.",
            "acceptanceCriteria": [
                "wiki/ exists at repo root, tracked, with wiki/README.md per context/rules/directory-readme.md (one-line intent + subfolder enumeration + pointer to context/rules/wiki.md)",
                "wiki/raw/ exists with wiki/raw/README.md (one-line intent describing immutable WebFetch snapshots and sources: provenance)",
                ".gitignore appended with EXACTLY two lines at end-of-file: `wiki/raw/*` then `!wiki/raw/README.md` — verified via `git check-ignore -v wiki/raw/README.md` (exit 1) and `git check-ignore -v wiki/raw/2026-05-24-test.md` (exit 0)",
                "context/rules/wiki.md ships COMPLETE with all 7 required sections (each non-empty): (1) Boundary table — verbatim 7-row table from plan; (2) Entry schema with full frontmatter spec + H1 + ## Summary + ## Detail + ## See Also + ≤600-word cap + sub-article split; (3) Slug derivation rule: URL path's last non-UUID segment, lowercased kebab-case, charset [a-z0-9-]+; --slug override for UUID URLs; (4) Cross-link convention `[[slug]]` with grep pattern `grep -roE '\\[\\[[a-z0-9-]+\\]\\]' wiki/`; (5) Confidence lifecycle: provisional set by /wiki-ingest, confirmed/deprecated set MANUALLY by orchestrator only; /wiki-lint REPORTS deprecated but never AUTONOMOUSLY SETS; (6) Frontmatter extraction canonical command: `awk '/^---$/{f=!f; next} f{print}' wiki/<slug>.md` — locked for both /wiki-query and /wiki-lint; (7) Body-merge strategy for /wiki-ingest updates: replace ## Summary + ## Detail in-place, append to sources: + See Also, update updated:, never touch created:",
                "Schema example in context/rules/wiki.md either drops memory/MEMORY.md#<anchor> from sources: OR annotates as aspirational (MEMORY.md has no stable anchors)",
                "wiki/README.md ships with empty entries-table header only: exact header line `| Slug | Title | Tags | Updated |` + alignment row `| --- | --- | --- | --- |`; sorted by updated: descending; empty corpus = header lines only (not an error)",
                "CHANGELOG.md [Unreleased] ### Added entry in same commit: 'wiki/ directory + context/rules/wiki.md schema for Karpathy LLM Wiki pattern'",
                "git status shows only the expected new files (no leakage into memory/MEMORY.md or other surfaces)",
                "Typecheck passes (satisfied by clean git status on this AC scope)"
            ],
            "priority": 1,
            "passes": true,
            "notes": "Completed 2026-05-24 via /delegate Wave 1; commit e7b410e. context/rules/wiki.md ships 201 lines / 1567 words across all 7 required sections (boundary table, entry schema, slug derivation, cross-link, confidence lifecycle, canonical extraction awk command, body-merge strategy). .gitignore + wiki/README.md + wiki/raw/README.md as specified. Sonnet."
        },
        {
            "id": "US-002",
            "title": "Implement /wiki-ingest skill (URL + path + --from-draft + update-existing)",
            "description": "As the orchestrator, I want a skill that reads a source URL/path/draft, snapshots it to wiki/raw/, and writes or updates entity pages in wiki/.",
            "acceptanceCriteria": [
                ".claude/skills/wiki-ingest/SKILL.md exists with valid frontmatter: name: wiki-ingest, description, argument-hint: '<url|path> [--slug <override>] | --from-draft <slug> [--allow-stale]'",
                "Argument interface locked: /wiki-ingest <url|path> [--slug <override>] for source ingest; /wiki-ingest --from-draft <slug> [--allow-stale] for draft promotion; no other invocation forms",
                "Skill `mkdir -p wiki/raw/` before writing any snapshot (directory is gitignored; may not exist on fresh clone)",
                "Slug derivation follows context/rules/wiki.md § Slug derivation rule (US-001); for UUID/hash URLs, --slug <override> required and skill errors if absent",
                "URL ingest: WebFetch the URL, write snapshot to wiki/raw/<yyyy-mm-dd>-<slug>.md with header `# Source: <url>` then fetched body; date = `date -u +%Y-%m-%d`",
                "Path ingest: read file, write copy to wiki/raw/<yyyy-mm-dd>-<basename>.md; same UTC date convention",
                "--from-draft resolution: glob `memory/*/wiki-drafts/<slug>.md`, sort by ISO date in parent directory name (lexicographic max), exclude `.skip` files; if most-recent directory date > 7 days older than today UTC, exit STALE unless --allow-stale; do NOT use filesystem mtime",
                "Write/update wiki/<slug>.md with valid frontmatter per context/rules/wiki.md schema: title, slug, tags, created (only on create), updated (always), sources (appending new snapshot path), related (optional), confidence: provisional (on create)",
                "Update path IN SCOPE: when wiki/<slug>.md exists, follow context/rules/wiki.md § Body-merge strategy (replace ## Summary + ## Detail in-place, append to sources: + See Also, update updated:, never touch created:); do NOT concatenate bodies",
                "Daily log entry per context/rules/memory.md MIP: `## /wiki-ingest -- HH:MM UTC` with fields Source, Slug-Created, Slugs-Updated, Snapshot-Path, Result, Observation",
                "CHANGELOG.md [Unreleased] ### Added entry in same commit: '/wiki-ingest skill for capturing WebFetch snapshots and authoring wiki entries'",
                "Manual QA smoke test (NOT automated; CI uses local fixture if testing): `/wiki-ingest https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f --slug karpathy-llm-wiki` creates wiki/raw/<today>-karpathy-llm-wiki.md AND wiki/karpathy-llm-wiki.md with valid frontmatter and confidence: provisional; this smoke MUST commit BEFORE US-003 smoke runs",
                "Typecheck passes (no project type-check; satisfied by clean git diff + SKILL.md frontmatter parses as valid YAML)"
            ],
            "priority": 2,
            "passes": true,
            "notes": "Completed 2026-05-24 via /delegate Wave 2 (parallel with US-003); commit 92c8797. SKILL.md = 295 lines; argument-hint set; defers to context/rules/wiki.md §§ 3, 7, 2 for slug/body-merge/schema. Sonnet."
        },
        {
            "id": "US-003",
            "title": "Implement /wiki-query skill (frontmatter grep + top-3 read cap)",
            "description": "As the orchestrator, I want a skill that searches the wiki by topic and reads the top match(es) into context.",
            "acceptanceCriteria": [
                ".claude/skills/wiki-query/SKILL.md exists with valid frontmatter: name: wiki-query, description, argument-hint: '<topic>'; SKILL.md body documents multi-word semantics: split on whitespace into space-separated OR terms, union of per-term matches deduplicated",
                "Greps only the frontmatter of each wiki/*.md entry using the canonical extraction command from context/rules/wiki.md § Frontmatter extraction canonical command: `awk '/^---$/{f=!f; next} f{print}' wiki/<slug>.md` — same command used by /wiki-lint (US-004)",
                "Matches against frontmatter title, slug, and tags only (NOT body text)",
                "Returns list of all matching wiki/*.md file paths to stdout",
                "Empty-result behavior: Match-Count = 0 prints `No wiki entries matched <topic>` and exits status 0 (NOT an error)",
                "Sub-cap behavior: 0 < Match-Count < 3 reads ALL matches into context; Match-Count >= 3 reads top 3 only; cap hardcoded to 3 in v1 (raising requires SKILL.md edit)",
                "Tie-breaking order: updated: descending (most recently updated first)",
                "Reads individual wiki/*.md files directly (does NOT route via wiki/README.md index)",
                "Daily log entry: `## /wiki-query -- HH:MM UTC` with fields Query, Match-Count, Read-Slugs (or — if zero), Result, Observation",
                "CHANGELOG.md [Unreleased] ### Added entry in same commit: '/wiki-query skill for grep-based wiki search with top-3 read cap'",
                "Manual QA smoke test (after US-002 smoke commits): `/wiki-query karpathy` returns wiki/karpathy-llm-wiki.md path and reads it into context; `/wiki-query nonexistent-topic-xyz` prints empty-result message and exits 0",
                "Typecheck passes (satisfied by clean git diff + SKILL.md frontmatter parses as valid YAML)"
            ],
            "priority": 2,
            "passes": true,
            "notes": "Completed 2026-05-24 via /delegate Wave 2 (parallel with US-002); commit 92c8797. SKILL.md = 299 lines; argument-hint set; uses canonical awk extraction from context/rules/wiki.md § 6 (byte-identical to /wiki-lint). Sonnet."
        },
        {
            "id": "US-004",
            "title": "Implement /wiki-lint skill (stale + orphan + broken-link + atomic README regen)",
            "description": "As the orchestrator, I want a manual health-check skill that surfaces stale/orphaned/broken entries and regenerates the wiki/README.md index.",
            "acceptanceCriteria": [
                ".claude/skills/wiki-lint/SKILL.md exists with valid frontmatter: name: wiki-lint, description, argument-hint: '[--dry-run]'",
                "Default invocation regenerates wiki/README.md entries table; --dry-run prints what would change without writing",
                "Atomic regeneration: write to wiki/README.md.tmp; validate non-empty AND contains exact header `| Slug | Title | Tags | Updated |`; atomically rename on success; on failure exit non-zero, leave original intact, print failure reason",
                "Stale check (a): enumerate entries with frontmatter updated: > 90 days older than today UTC; reported as separate finding type with 'consider review' recommendation",
                "Stale check (b): enumerate entries with frontmatter confidence: deprecated; reported as separate finding type with 'consider archive or delete' recommendation; (a) and (b) NEVER conflated; /wiki-lint REPORTS deprecated entries but NEVER SETS the flag autonomously",
                "Orphan check: two-pass; pass 1 enumerates all slugs from wiki/*.md frontmatter using same canonical extraction as US-003; pass 2 greps all entry bodies for `[[slug]]` (pattern `\\[\\[[a-z0-9-]+\\]\\]`); entries with zero inbound refs are orphans; single-entry corpus orphan is TRUE POSITIVE (not false positive)",
                "Broken-outbound-link check: grep entry bodies for `[[slug]]` where slug does not match any existing entry slug; reported separately from orphans",
                "Contradiction detection: descoped for v1; stub function prints `contradiction detection: not yet implemented — see wiki-lint follow-up tracking` (no #N placeholder; follow-up tracking issue may be filed post-merge but is NOT a hard blocker)",
                "README regeneration format: entries table `| Slug | Title | Tags | Updated |` (literal header in that order), alignment row `| --- | --- | --- | --- |`, sorted by updated: descending; empty corpus = header lines only (NOT an error)",
                "Daily log entry: `## /wiki-lint -- HH:MM UTC` with fields Entries-Scanned, Stale-90d, Deprecated, Orphaned, Broken-Links, Mode (op/dry-run), Result, Observation",
                "CHANGELOG.md [Unreleased] ### Added entry in same commit: '/wiki-lint skill for manual wiki health checks + index regeneration'",
                "Manual QA smoke test (one-entry corpus post US-002): `/wiki-lint --dry-run` reports zero stale-90d AND zero deprecated findings (single-entry orphan is a TRUE POSITIVE — smoke test 'zero false positives' refers only to stale + deprecated + broken-link on the fresh entry); set entry confidence: deprecated and rerun, deprecated check surfaces it; without --dry-run regenerates wiki/README.md to include the entry under header lines",
                "Typecheck passes (satisfied by clean git diff + SKILL.md frontmatter parses as valid YAML)"
            ],
            "priority": 3,
            "passes": true,
            "notes": "Completed 2026-05-24 via /delegate Wave 3; commit 1e6ab78. SKILL.md = 525 lines; argument-hint set; atomic README regen (tmp + validate + rename); contradiction detection shipped as stub with literal text 'contradiction detection: not yet implemented — see wiki-lint follow-up tracking'. Sonnet."
        },
        {
            "id": "US-005",
            "title": "Register /wiki-ingest, /wiki-query, /wiki-lint in AGENTS.md skills table",
            "description": "As the orchestrator, I want the three new wiki skills registered in the AGENTS.md skills table so they appear in the auto-loaded orchestrator context.",
            "acceptanceCriteria": [
                "DEPENDENCY GATE: DO NOT execute until US-002, US-003, US-004 commits are landed (their skill names and descriptions must exist before this story can author authoritative AGENTS.md rows)",
                "Symlink integrity check (CRITICAL): `ls -li CLAUDE.md AGENTS.md` shows the same inode BEFORE editing; edit ONLY AGENTS.md (Edit tool refuses to write through CLAUDE.md symlink); after editing rerun `ls -li CLAUDE.md AGENTS.md` and verify inode still matches",
                "AGENTS.md skills table receives 3 new rows appended at the bottom of the existing table — NO new category header (table convention is flat)",
                "Each row format matches adjacent rows: `| /wiki-ingest | When capturing a source (URL, path) or promoting a sub-agent draft to a wiki entry |` (one-line 'When' guidance; references the locked argument interfaces from US-002/3/4)",
                "CHANGELOG.md [Unreleased] receives one additional ### Changed line in same commit: 'Register /wiki-ingest, /wiki-query, /wiki-lint in AGENTS.md skills table'",
                "No duplicate CHANGELOG entries: verify with `grep -c 'wiki-ingest' CHANGELOG.md` returning the expected count (1 for US-002's Added entry + 1 for US-005's Changed entry = 2) before commit",
                "Typecheck passes (satisfied by clean git diff)"
            ],
            "priority": 4,
            "passes": true,
            "notes": "Completed 2026-05-24 via /delegate Wave 4 (serial); commit dc64711. 3 rows appended to AGENTS.md skills table (no new category header). CLAUDE.md symlink integrity verified intact (inode 3408085 unchanged before/after edit). CHANGELOG Changed entry added. Haiku."
        }
    ]
}