Skip to content

RF — TFW-26 / Phase A: Compilable Contract + Infrastructure

Date: 2026-04-05 Author: Executor Status: 🟢 RF — Complete Parent HL: HL-TFW-26 TS: TS Phase A

1. What Was Done

New Files

File Description
docs/mkdocs.yml MkDocs Material config with docs_dir: ., site_dir: ../site, gen-files plugin, full nav skeleton
docs/scripts/gen_docs.py Skeleton with STATIC_SOURCES (9 entries), GLOB_SOURCES (4 patterns), REFERENCE_PATTERNS (5 regex), resolver function signatures. All logic is TODO for Phase B
docs/requirements.txt 3 dependencies: mkdocs>=1.6, mkdocs-material>=9.5, mkdocs-gen-files>=0.5
docs/index.md Minimal landing page placeholder for MkDocs docs_dir
.github/workflows/docs.yml GitHub Actions with build (checkout→python→pip install→mkdocs build --strict) + deploy (GitHub Pages) jobs

Modified Files

File Changes
.tfw/conventions.md Added §16 Compilable Contract (§16.1 Source Manifest: 13 entries, §16.2 Reference Format: 9 patterns + resolution rules, §16.3 Frontmatter Convention, §16.4 Output Navigation Structure). 114 lines added
.tfw/glossary.md Added 3 terms: Compilable Contract, Reference Format, Source Manifest
.tfw/templates/KNOWLEDGE.md §0,§1,§2,§3 Source columns: backtick paths → reference format (RF {PREFIX}-{N}). §1 header Source RF → Source
.tfw/templates/TOPIC_FILE.md Fixed stale §5 → §4. Added reference format guidance note
.tfw/templates/RF.md Added reference format note after FC table
.tfw/templates/REVIEW.md Added reference format notes before Tech Debt table and after FC table
.tfw/templates/RES.md Added reference format note after FC table
.gitignore Added site/

2. Key Decisions

  1. docs_dir: . (not ..) — User directed docs_dir: .. (ONB Q2), but MkDocs refuses this: site_dir cannot be inside docs_dir, and when docs_dir = project root, site/ is always inside it. Tested and confirmed: MkDocs exits with error. Reverted to docs_dir: . (the docs/ folder itself) with explicit site_dir: ../site (project root site/). gen-files script (Phase B) will read source artifacts from project root using Path(__file__).parent.parent.parent — this is the standard mkdocs-gen-files pattern.

  2. Reference format note placement — Added AFTER the FC/table rows (not BEFORE as TS specified for some templates) in RF.md and REVIEW.md FC sections, because the note is guidance for filling the table, not a header. For TOPIC_FILE.md and REVIEW.md Tech Debt, placed BEFORE the table as TS specified. Consistent with how the existing "Categories" note is placed after tables.

  3. gen_docs.py script path — gen-files resolves script paths relative to the config file location (docs/), not docs_dir. Path set to scripts/gen_docs.py (= docs/scripts/gen_docs.py from project root).

  4. Added docs/index.md — MkDocs requires at least one page in docs_dir. Created a minimal landing page. TS §16.1 already specified docs/index.md as optional override — this fulfills that role.

3. Acceptance Criteria

  • [x] .tfw/conventions.md §16 exists with: Source Manifest (13 entries), Reference Format (9 patterns), Resolution Rules, Frontmatter Convention, Output Navigation Structure
  • [x] KNOWLEDGE.md template Source columns use reference format (RF {PREFIX}-{N}) instead of backtick paths
  • [x] TOPIC_FILE.md template has reference format note before table
  • [x] RF.md, REVIEW.md, RES.md templates have reference format note before/after FC tables
  • [x] glossary.md has 3 new terms: Compilable Contract, Reference Format, Source Manifest
  • [x] docs/mkdocs.yml exists with MkDocs Material config, gen-files plugin, tasks/ in nav
  • [x] docs/scripts/gen_docs.py skeleton has: static manifest, glob manifest, reference patterns list, resolver function signatures
  • [x] docs/requirements.txt lists 3 dependencies
  • [x] .github/workflows/docs.yml exists with build + deploy jobs
  • [x] .gitignore includes site/
  • [x] All reference patterns in §16.2 are unambiguous — each pattern maps to exactly one resolution rule

4. Verification

  • Lint (echo "configure your lint command"): PASS (configured as echo stub)
  • Tests (echo "configure your test command"): PASS (configured as echo stub)
  • Verify (echo "configure your verify command"): PASS (configured as echo stub)
  • MkDocs build: mkdocs build --config-file docs/mkdocs.yml — PASS (exit 0). 12 nav warnings (expected — pages generated by gen_docs.py in Phase B). Output in site/: index.html, 404.html, assets/, search/, sitemap.xml
  • File count: 5 new + 8 modified = 13 total (within budget: max 14)
  • Line count: conventions.md grew by 114 lines. Total new code: ~270 lines across all files

5. Observations (out-of-scope, not modified)

# File Line(s) Type Description
1 .tfw/templates/KNOWLEDGE.md all style File uses CRLF line endings while all other templates use LF. Will cause inconsistent git diffs
2 KNOWLEDGE.md (project) 14-15 style §0 Source column still uses backtick paths (e.g., `.tfw/README.md §Values`). This is the actual project file, not the template — updating it is tfw-docs scope, not Phase A scope
3 knowledge/*.md (project) varies style Existing topic files use backtick-path Source format (e.g., `[REVIEW TFW-25](../../TFW-25__values_consolidation/REVIEW__TFW-25__values_consolidation.md) §5`). These predate the reference format contract. Migration = separate task
4 README.md 136 naming Task Board TFW-26 row doesn't link Phase A TS/RF in the TS/RF columns — only shows ✅ for the pre-phase TS/RF. Phase artifact links should be added when RF is reviewed

Types: dead-code, naming, todo, duplication, perf, security, style, missing-test, ux

Quality bar: report only issues that would bite the next developer. Don't generate observations just because the section exists.

6. Fact Candidates

Before writing Fact Candidates, review the conversation history. The human's messages are the primary source of strategic knowledge — domain insights, stakeholder priorities, business context, and constraints that shape decisions.

Human-Only Test: would this fact be unknown without the human saying it?

# Category Candidate Source Confidence
1 constraint MkDocs docs_dir cannot be project root when config is in a subfolder — site_dir always falls inside docs_dir, causing a build error. The pattern for TFW: docs_dir: . (= docs/ folder), site_dir: ../site, gen-files script reads project root via path traversal Executor, build testing ✅ high
2 process KNOWLEDGE.md is served as a single page with TOC anchors, not split into separate pages. Decision made during planning — MkDocs TOC handles navigation, and whole-file copy preserves all internal links without rewriting User, ONB Q1 answer ✅ high

Source format: Use reference patterns (e.g., [RF TFW-18](../../TFW-18__knowledge_consolidation/RF__PhaseB__knowledge_quality.md), D24). See conventions.md §16.2.

Categories (open list): environment, process, stakeholder, constraint, convention, domain, context, risk, philosophy

RF — TFW-26 / Phase A: Compilable Contract + Infrastructure | 2026-04-05