workspace-knowledge-doc-contracts

# Workspace Knowledge Doc Contracts

## When to Use
Use when building/repairing LLM-wiki knowledge, aligning repo mission contracts, auditing stale documentation references, extracting learnings into issues, or turning domain gaps into issue roadmaps.

## Class-Level Workflow
1. Inventory knowledge sources and distinguish canonical docs from generated/session artifacts.
2. Repair metadata/frontmatter before indexing or downstream issue creation.
3. Keep repo mission/contract documents aligned with live repository purpose.
4. Convert real gaps into deduplicated issues only after source-grounded evidence exists.
5. Maintain semantic taxonomy terms consistently across reports and docs.

## Metadata-only LLM-wiki execution for large/sensitive corpora

Use this sub-pattern when an approved plan promotes a large or sensitive corpus (external-drive archives, standards libraries, training decks, client/project files) into LLM-wiki pages without copying raw data:

1. **Gate first**: confirm explicit plan approval (`status:plan-approved` or a local approval marker) before writing wiki pages.
2. **RED test first**: add focused tests that initially fail for expected page existence and boundary fields: `extraction_policy`, `raw_copy_allowed: false`, `ocr_allowed: false` where applicable, source-of-record absolute paths, and index/log updates.
3. **Create pointer/shell pages, not extraction dumps**:
   - standards/spec libraries use `extraction_policy: metadata-only`; no clauses, copied standards text, or detailed licensed titles.
   - training/client corpora use `extraction_policy: metadata-first`; curated summaries only; no full deck text, speaker notes, OCR output, screenshots, figures, or raw bytes.
   - standards resolver stubs use public metadata only (`code_id`, `publisher`, `revision` or explicit unverified/deferred marker, `revision_source`, `verified_on`, `public_url`).
4. **Update discoverability surfaces**: update `wiki/index.md`, `wiki/log.md`, and parent source-catalog cross-links so new pages are not orphaned.
5. **Verify broadly**: run targeted pytest, `scripts/knowledge/tests/test_llm_wiki.py`, `llm_wiki.py lint/status` for affected domains, and a raw-data guard such as `git show --name-only --format='' HEAD | grep -E 'knowledge/wikis/.*/raw/|\.(pdf|pptx|ppt|xlsx|xls|docx|doc|png|jpg|jpeg|dwf|db)$' || true`.
6. **Force-add intentionally ignored wiki files**: workspace-hub may ignore `knowledge/wikis/*`; use `git add -f` only for intended wiki pages/tests/reports and check targeted `git status` to avoid unrelated provider/report churn.
7. **Treat fetch/rev-list as push truth**: if `git push` reports a transient remote lock/rejected ref but the remote already points at the new commit, verify with `git fetch origin main` and `git rev-list --left-right --count HEAD...origin/main`; `0 0` is the sync ground truth.
8. **Close issues with evidence**: include commit hash, test/lint results, raw-data guard result, and preserved boundaries in GitHub comments.

## Consolidated Session Learnings

The `references/` directory contains archived narrow skills absorbed during the 2026-04-29 umbrella consolidation pass. Use the subsections below as the class-level index, then open the named reference when a case-specific recipe is needed.
## Absorbed Narrow Skills (2026-04-29)

### `docs-stale-reference-guardrails`

- Former skill demoted to `references/docs-stale-reference-guardrails.md`.
- Preserved insight: Prevent deleted workflow/path references from creeping back into live docs by combining strict scans, legacy allowlists, and shared regex helpers.

### `extract-learnings-to-issues`

- Former skill demoted to `references/extract-learnings-to-issues.md`.
- Preserved insight: Extract unstructured user reflections and learnings, distill core themes, route insights to existing GitHub issues as contextual comments rather than creating duplicates.

### `knowledge-source-recon`

- Former skill demoted to `references/knowledge-source-recon.md`.
- Preserved insight: Reconnaissance pattern to inventory all knowledge sources across the workspace-hub ecosystem's existing intelligence infrastructure. Maps raw sources for LLM Wiki ingestion planning. Leverages pre-built registries and indexes rather than re-scanning directories.

### `llm-wiki-ecosystem-gap-to-issues`

- Former skill demoted to `references/llm-wiki-ecosystem-gap-to-issues.md`.
- Preserved insight: Review the workspace-hub LLM-wiki/document-intelligence ecosystem, identify high-leverage gaps, and create grounded GitHub feature issues without duplicating existing work.

### `llm-wiki-pattern`

- Former skill demoted to `references/llm-wiki-pattern.md`.
- Preserved insight: Build and maintain persistent, compounding knowledge bases using the LLM Wiki pattern (Karpathy). Unlike RAG (retrieve chunks at query time), the wiki is a persistent artifact that gets compiled and maintained by the LLM.

### `llm-wiki-roadmap-integration`

- Former skill demoted to `references/llm-wiki-roadmap-integration.md`.
- Preserved insight: Integrate repo-ecosystem work into an existing llm-wiki / knowledge-roadmap issue without creating duplicate GitHub issues.

### `parallel-llm-wiki-gap-to-issues`

- Former skill demoted to `references/parallel-llm-wiki-gap-to-issues.md`.
- Preserved insight: Use parallel subagents to mine remaining LLM-wiki/document-intelligence gaps, de-duplicate against existing GitHub issues, then create only the strongest bounded follow-on issues.

### `repair-legacy-llm-wiki-frontmatter-dates`

- Former skill demoted to `references/repair-legacy-llm-wiki-frontmatter-dates.md`.
- Preserved insight: Diagnose and repair legacy llm-wiki source pages that have ingested timestamps but are missing required added/last_updated frontmatter dates.

### `repo-mission-portfolio-audit`

- Former skill demoted to `references/repo-mission-portfolio-audit.md`.
- Preserved insight: Audit the workspace-hub repo portfolio to extract each repo's mission, identify documentation gaps, and prioritize a plan/approval sequence with explicit LLM-wiki weighting for future issue triage.

### `semantic-taxonomy-reporting-consistency`

- Former skill demoted to `references/semantic-taxonomy-reporting-consistency.md`.
- Preserved insight: Keep semantic-diff taxonomy summaries consistent with evidence tables when adding richer categories to legacy comparison/reporting pipelines.

### `workspace-hub-mission-contract-first-packet`

- Former skill demoted to `references/workspace-hub-mission-contract-first-packet.md`.
- Preserved insight: Plan the first repo-mission canonicalization packet for the workspace ecosystem by reusing the existing control-plane issue, locking Wave-1 scope, and making review criteria deterministic.

### `tier1-indexing-scorecard-and-freshness-audit`

- Former skill demoted to `references/tier1-indexing-scorecard-and-freshness-audit.md`.
- Preserved insight: Audit tier-1 repos for code-placement/retrieval readiness, write a scorecard report, create follow-up GitHub issues, and add a daily freshness cron while avoiding legacy product-doc reference patterns.

### `exclude-wiki-Codex-md-from-harness-line-limit-hook`

- Former skill demoted to `references/exclude-wiki-Codex-md-from-harness-line-limit-hook.md`.
- Preserved insight: Fix false-positive pre-commit failures where workspace-hub's AGENTS.md line-limit hook blocks edits to auto-generated wiki schema files under knowledge/wikis/.

### `memory-bridge-commit-fallbacks`

- Former skill demoted to `references/memory-bridge-commit-fallbacks.md`.
- Preserved insight: Fallback procedures when the Hermes ↔ Codex memory bridge writes .Codex/memory outputs but the internal git commit/push path fails because of dirty, stale, or broken submodule state.