docs: sync to the harness (post WS1-5) + live architecture diagrams + DeepSeek default - #220
Merged
Conversation
…odel to DeepSeek Cross-referenced all ~45 doc pages against the code (fan-out audit) and fixed the drift: ARCHITECTURE (the big one) - Rewrite big-picture.mdx around the real shape: a general stack-agnostic core + adapters behind seams (IStackAdapter / IConventionProvider / IPlanSchema / IGate / external-plugins), with the mechanical import boundary. Replace the stale static board image with two live Mermaid diagrams — a layers/seam diagram and a request-flow diagram (prompt → plan → drive-to- green loop → gate → panel → done). Retire the static board from quickstart too (kept for the OG social card only). MODEL (align to reality) - Flip the shipped default from qwen3.6-27b → deepseek-v4-flash (PROVIDER_DEFAULTS; the reasoning dialect auto-detects from the model name, so no behavioural flip). Rename the QWEN_LOCAL default entry/key → local. Update the default-assertion tests. Illustrative model names across the docs → deepseek-v4-flash. WRONG FACTS - validation.mdx: turn caps 250/40/400 → the unified 1000 crash-guard (+ no-progress guards). - greenfield.mdx: evaluator "gate → Playwright browser → judge" → gate (differential / reachability / testid) → judge; no headless browser is run. - write-diagnostics.mdx: error cap 5 → 200; output-format example fixed to the real write-check shape. - eval docs: wrong path seeds/ → evals/corpus/; phantom `money` seed → `math` (real seed). MISSING - rule-packs.mdx: fix the generic-ts self-contradiction (it's a detection label, not a rule pack); add a "Bring your own rules" section (tsforge.config.json plugins). stack-detection.mdx: add the plugins row. interactive.mdx: add the /scaffold slash command. Docs build green (47 pages, Mermaid renders); `bun run validate` green. NOTE: a live smoke of the deepseek default on the Spark boxes is the final confirmation of the model flip — the change itself is a fallback-only string + dialect auto-detect, structurally validated.
…g pass) De-em-dash pass over all 38 prose doc pages (rules-catalog.md excluded — generated): 239 prose em dashes replaced with contextually-correct punctuation (period / colon / parentheses / comma). Pure punctuation edits — a perfect 1:1 line swap (264/264), with every command, flag, path, number, code block, and mermaid diagram left byte-identical. Remaining dashes are legitimate: table N/A placeholders and bash-comment separators inside code fences. Also quote a frontmatter description whose new colon broke YAML. Docs build green.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Cross-referenced the Astro docs (~45 pages) against the current harness after the WS1–WS5 refactor, and fixed the drift. Docs build green (47 pages, Mermaid renders);
bun run validategreen.Architecture (the headline)
big-picture.mdxrewritten around the real shape — a general, stack-agnostic core plus adapters behind seams (IStackAdapter/IConventionProvider/IPlanSchema/IGate/external-plugins) and the mechanical import boundary.quickstart(kept only for the OG social card).Model — aligned to reality
qwen3.6-27b→deepseek-v4-flash(PROVIDER_DEFAULTS; reasoning dialect auto-detects from the name, so no behavioural change). Rename theQWEN_LOCALdefault entry/key →local; update the default-assertion tests. All illustrative model names in docs →deepseek-v4-flash.Wrong facts corrected
validation.mdx— turn caps250/40/400→ the unified 1000 crash-guard (+ no-progress guards).greenfield.mdx— evaluator "gate → Playwright browser → judge" → gate (differential / reachability / testid) → judge; no headless browser is run.write-diagnostics.mdx— error cap5→ 200; output-format example fixed to the realwrite-checkshape.seeds/→evals/corpus/; phantommoneyseed →math.Missing capability documented
rule-packs.mdx— fix thegeneric-tsself-contradiction (detection label, not a rule pack); add a "Bring your own rules" section (tsforge.config.jsonplugins).stack-detection.mdx— add thepluginstuning row.interactive.mdx— add/scaffold.Verified accurate (left as-is)
gate-floor, scout, spec-runner, edit-engine, fix-to-green, delegation, model-agent, models-json, scaffold-CLI, TTSR, hashline, repair-ladder, memory, MCP, web-tools, LSP, policy, tests, meta-rules.