Workspace Knowledge Doc Contracts

Workspace Knowledge Doc Contracts

Support Files

• references/public-graph-artifact-validation.md — public-safe graph artifact validator hardening: source-corpus freshness checks, URL userinfo rejection, RED tests, and closeout gates for llm-wiki graph manifests.

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.

Data Layer / LLM-wiki Source-Class Promotion Model

When planning data/report/execution architecture for workspace-hub, do not treat “domain corpus” as inherently private. Classify by source class and promotion safety:

• D-L1 raw data: raw files, PDFs, datasets, exports, workbooks. Never public by default.
• D-L2 readable/extracted staging: OCR text, parsed tables, chunks, source cards. Local/private staging by default; not repo-tracked unless explicitly approved.
• D-L3 curated knowledge:
  • Public llm-wiki: public-safe domain knowledge, public data-source guides, cited concepts, and metadata-only restricted references.
  • Private corpus: client/project-specific knowledge, restricted derivative summaries, sensitive assumptions, non-public source extractions.
• D-L4 outputs/products: raw outputs, reports, dashboards, PDFs, client-facing HTML, chatbots.

Promotion rule: domain knowledge defaults to public llm-wiki only when the source class is public-safe. Domain knowledge defaults to private when derived from client, project, licensed, restricted, or commercially sensitive material. Do not route private/client raw or readable data directly into public llm-wiki; sanitized derivatives require explicit promotion gates and source-class/citation separation.

Recommended D-L2 storage pattern: use a hybrid local staging layout — shared local roots for public/domain staging, and separate local roots per client/project to prevent cross-client mixing and simplify backup, deletion, audit, and access-control.

Public llm-wiki eligible examples: public BSEE/SODIR/NPD/NOAA/NDBC data, public academic-paper summaries with citations, public engineering concept pages, public tool/data-source guides, and standards metadata that does not copy licensed text.

Private or metadata-only examples: client reports/data/decks/workbooks, project assumptions, non-public vendor docs, licensed standards text/clause extraction, screenshots/figures from restricted sources, and anything derived from confidential files even when rewritten generically.

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-claude-md-from-harness-line-limit-hook

• Former skill demoted to references/exclude-wiki-claude-md-from-harness-line-limit-hook.md.
• Preserved insight: Fix false-positive pre-commit failures where workspace-hub's CLAUDE.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 ↔ Claude memory bridge writes .claude/memory outputs but the internal git commit/push path fails because of dirty, stale, or broken submodule state.