title: "Challenge — "What do we NOT expect?"" source: "tasks/TFW-26__documentation_site/research/challenge.md"

Challenge — "What do we NOT expect?"¶

Parent: HL-TFW-26 Goal: Compile TFW project artifacts into a publishable documentation site — deterministic, scriptable, no agent involvement.

Findings¶

C1: MkDocs Ecosystem Risk — Maintenance Mode¶

Counter-evidence against MkDocs: - Material for MkDocs has entered maintenance mode as of late 2025 - Core MkDocs 2.0 rewrite is in progress — incompatible with 1.x plugin system - Zensical (successor) is new, early-stage, may not be production-ready - ProperDocs exists as a community fork maintaining 1.x compatibility

Assessment: This is a real risk but manageable for TFW-26: 1. MkDocs 1.x + Material still works and is widely deployed. "Maintenance mode" ≠ "broken" 2. TFW's scale is tiny (~10-15 pages) — MkDocs performance issues are irrelevant 3. The gen-files script is independent of MkDocs internals — if we switch to Zensical or another tool, only mkdocs.yml config changes, the script stays 4. The compilable contract (Extract E2) is tool-agnostic — it describes artifact structure, not MkDocs features

Decision: Accept MkDocs risk. If MkDocs dies, migrate config to Zensical (reads same mkdocs.yml) or rewrite to custom script (~100 LOC, as proven by Extract E4). Low switching cost because the compilable contract isolates the tool choice.

C2: Challenge H3 — Is <100 LOC Realistic?¶

The Extract stage estimated 80-120 LOC. Let me stress-test this:

What the script MUST do: 1. Read 10 source files → trivial (10 open() calls) 2. Add YAML frontmatter → trivial (string concatenation) 3. Split KNOWLEDGE.md by ## headings → ~15 lines of regex/split 4. Extract README.md non-Task-Board sections → ~10 lines 5. Write output files via mkdocs_gen_files.open() → trivial 6. Generate nav structure → depends on approach

What the script does NOT need to do: - Parse markdown (we split on ##, not parse AST) - Rewrite links (accepted limitation from Extract E4) - Handle templates/themes (MkDocs does this) - Generate search index (MkDocs does this)

Verdict: 80-120 LOC is realistic. H3 is confirmed with a caveat: "100 LOC" counts only the gen-files script, not mkdocs.yml config (~30 lines) or CI/CD workflow (~20 lines). Total project addition: ~150 lines across 3-4 files.

C3: Challenge the Two-Layer Split — Should Utility Also Validate?¶

HL §7 P5 says Layer 2 is "dumb" — walks strict list, expects strict format. But what if the format is wrong?

Scenario: Agent writes KNOWLEDGE.md but misnames a section (## 1 Architecture instead of ## 1. Architecture Map). The gen-files script can't find the section → silent failure, missing page.

Three positions: 1. Strict dumb utility (HL position) — fails silently. Problems found when someone looks at the site. 2. Utility with warnings — prints warnings for missing expected sections. Still produces output. 3. Utility with validation — fails the build if contract violations are detected.

My recommendation: Position 2 (warnings). Reasons: - Position 1 is too fragile — silent failures are the worst failure mode - Position 3 blocks deployment over formatting issues — too strict for a docs site - Position 2 gives visibility without blocking. CI/CD logs show "WARNING: KNOWLEDGE.md §1 heading not found"

This doesn't violate the "dumb utility" principle. Validation is still deterministic — the utility checks string matches, not semantic quality. It's a linter, not an interpreter.

C4: Challenge `docs/` at Project Root (H5)¶

HL assumes docs/ at project root. Gather research showed we should NOT check compiled output into git. But do we need ANYTHING at project root?

What lives at project root for docs: - mkdocs.yml — yes, must be at root (MkDocs convention) - scripts/gen_docs.py — yes, referenced by mkdocs.yml - requirements-docs.txt — yes, for CI/CD - docs/ folder — for what?

Does MkDocs need a docs/ folder? With mkdocs-gen-files, NO. The plugin generates all virtual files. There's no physical docs/ directory needed.

BUT: MkDocs still requires docs_dir to exist (even if empty). Default is docs/. We can set docs_dir: docs and create an empty docs/ with a .gitkeep. Or set docs_dir to some other value.

Cleaner alternative: Create a minimal docs/ with only special pages that need manual curation: - docs/index.md — optional curated landing page (or generated) - docs/faq.md — optional FAQ (manually maintained)

This way docs/ contains only human-curated content. All artifact-derived pages are generated by the script. Best of both worlds.

Decision: docs/ contains curated-only pages + .gitkeep. Generated pages are all virtual. H5 is partially confirmed — docs/ exists but contains curation, not compilation output.

C5: Challenge the "No Agent in Compilation" Boundary¶

The HL insists Layer 2 is deterministic, no agent involvement. But user's answer #2 revealed a desire for AI-queryable outputs (MCP, chat-over-docs). This creates a tension:

Scenario 1 (pure deterministic): MkDocs builds static HTML. No AI involvement at any point. → Works for web docs. Doesn't serve MCP use case.

Scenario 2 (deterministic compilation + AI serving): MkDocs builds docs. Separately, an MCP server reads the same artifacts or the compiled output. → Clean separation. Compilation is deterministic. AI query layer is a separate service.

Scenario 3 (AI in compilation): An agent runs during build to enhance docs (generate summaries, write introductions, etc.). → Violates determinism. Same input → different output across builds. User explicitly rejected this in HL §7 P5.

Verdict: Scenario 2 is correct. The compilable contract serves both consumers independently: - MkDocs reads artifacts → static docs - MCP server reads artifacts → AI context Neither needs the other. Both need the compilable contract.

This means TFW-26 stays focused on: (1) compilable contract, (2) MkDocs integration, (3) CI/CD. The MCP server is a separate, future task.

C6: Counter-Evidence — Why NOT MkDocs? Custom Script Alternative¶

The "no framework" position:

A simple Python script (~60 LOC) using just markdown library can convert .md to .html with a template. No mkdocs.yml, no plugins, no dependencies beyond pip install markdown.

Pros vs MkDocs: - Zero dependency risk (no framework to go into maintenance mode) - Full control over output - Smaller footprint

Cons vs MkDocs: - No search (critical for docs) - No theme (have to design from scratch) - No navigation generation - No responsive design - No syntax highlighting - Need to maintain CSS, HTML templates, JavaScript

Verdict: Custom script fails the "don't invent, find and configure" principle (HL §7 P4). MkDocs provides search, nav, themes, responsive design for free. A custom script would require 500+ LOC to match MkDocs Material features. The risk of MkDocs dying is lower than the risk of maintaining a custom solution.

However: The compilable contract is designed so that switching FROM MkDocs TO a custom script is cheap. The contract defines what the compiler expects from artifacts — the compiler implementation is swappable.

Checkpoint¶

Found	Remaining
MkDocs maintenance risk is real but manageable — low switching cost due to compilable contract	No remaining gaps
H3 (<100 LOC) confirmed — ~80-120 LOC for gen-files script	Validated
Utility should warn on contract violations (not fail silently, not block builds)	New recommendation for HL
`docs/` folder = curated-only pages, generated pages are virtual	Clarification for HL
MCP server is a separate future task — compilable contract serves both outputs	Scope confirmed
Custom script alternative loses to MkDocs on features — but contract enables switching	Risk mitigation validated

Sufficiency: - [x] External source used? (3 web searches for counter-evidence, MkDocs criticism, custom alternatives) - [x] Briefing gap closed? (All hypotheses addressed, counter-evidence sought for main recommendation)

Deep mode: - [x] Hypothesis tested? (H2: MkDocs with gen-files = yes. H3: 80-120 LOC confirmed. H5: docs/ = curation, not output) - [x] Counter-evidence sought? (MkDocs maintenance mode, custom script alternative, silent failure risk)

Metacognitive check: The biggest new insight from Challenge is C3 (validation in the utility). The HL's "dumb compiler" framing missed the silent failure problem. Warning-level validation is needed and doesn't violate the determinism principle. The second insight is that the compilable contract IS the main deliverable — more important than the tool choice. If the contract is well-defined, any tool can consume it.

Stage complete: YES → User decision: ___