| name | workspace-knowledge-doc-contracts |
| version | 1.0.0 |
| category | workspace-hub |
| description | Class-level workspace knowledge, LLM-wiki, repo mission contracts, stale doc references, semantic taxonomy, and knowledge-source reconnaissance. |
| tags | ["knowledge","documentation","llm-wiki","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
- Inventory knowledge sources and distinguish canonical docs from generated/session artifacts.
- Repair metadata/frontmatter before indexing or downstream issue creation.
- Keep repo mission/contract documents aligned with live repository purpose.
- Convert real gaps into deduplicated issues only after source-grounded evidence exists.
- 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:
- Gate first: confirm explicit plan approval (
status:plan-approved or a local approval marker) before writing wiki pages.
- 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.
- 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).
- Update discoverability surfaces: update
wiki/index.md, wiki/log.md, and parent source-catalog cross-links so new pages are not orphaned.
- 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.
- 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.
- 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.
- 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.
