kingmadoc 0.3.0.dev9__tar.gz → 0.3.0.dev10__tar.gz

{kingmadoc-0.3.0.dev9 → kingmadoc-0.3.0.dev10}/.featuredoc.yml

@@ -51,24 +51,27 @@ diagram_format: mermaid
 # `models` selects the design models (sections) of a document; default: all of them.
 extra_designs:
   functional_design:
-    # <slug>-functional-design.md: user flows, edge cases, business rules,
-    # permissions and roles.
+    # <slug>-functional-design.md, for stakeholders: user stories, use case diagram, per
+    # story a use case, screen design (screenshot or wireframe) and evil user stories;
+    # user flows.
     enabled: false
     template: functional_design.md.j2
-    models: []
+    models: [user_stories, use_case_diagram, use_cases, screen_designs, evil_user_stories, user_flows]
   technical_design:
-    # <slug>-technical-design.md: database schema, API contracts, error handling,
-    # performance and security considerations.
+    # <slug>-technical-design.md, for developers: database schema, API contracts,
+    # business rules, permissions, edge cases, error handling, performance and security,
+    # threat model (Microsoft Threat Modeling Tool style), dependency graph.
     enabled: false
     template: technical_design.md.j2
-    models: [dependency_graph]
+    models: [business_rules, permissions, edge_cases, threat_model, dependency_graph]
   domain_design:
     # <slug>-domain-design.md: domain model and event storming.
     enabled: false
     template: domain_design.md.j2
     models: [domain_model, event_storming]
   security_design:
-    # <slug>-security-design.md: threat model (STRIDE) and who may do what.
+    # <slug>-security-design.md: threat model (Threat Modeling Tool style) and who may
+    # do what.
     enabled: false
     template: security_design.md.j2
     models: [threat_model, permissions]
@@ -80,5 +83,11 @@ adr:
 
 # Explainers written by the explaining-code agent skill ("explain this project").
 # format: arc42 (the 12 arc42 sections, default) or c4 (compact zoom-in).
+# documents: single (one explainer, default), split (functional + technical, "FO/TO"),
+# functional (only the FO) or technical (only the TO). The request overrides it.
+# models: what the agent may draw (default: all; each only when the code has it). The
+# request can narrow it too ("without screens", "only the threat model").
 explain:
   format: arc42
+  documents: single
+  models: [c4_context, c4_container, c4_component, c4_code, c4_deployment, c4_dynamic, sequence, state_machine, er_diagram, domain_model, class_diagram, package_diagram, activity, user_journey, use_case, event_flow, context_map, data_flow, algorithm, user_stories, screens, evil_user_stories, threat_model]

{kingmadoc-0.3.0.dev9 → kingmadoc-0.3.0.dev10}/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- Explainers can no longer end up without pictures. `kingmadoc render` links the SVG of
+  a diagram whose PNG conversion fails (a missing `resvg-py` wheel, a Rust panic in
+  resvg) instead of failing the whole document, and `resvg-py` is loaded only when a
+  PNG is made, so a platform without its wheel keeps every other command. The
+  `explaining-code` skill (6.0) delivers first and asks afterwards: it never stops on a
+  question before the document is written and rendered (screenshots are offered at
+  hand-over, wireframes come first), and it must pass the new
+  `kingmadoc explain check <folder>` (no placeholders, no unrendered D2, no missing
+  images, no figure without a picture) before it hands over. The eval scenarios run
+  the same check.
+
 ### Changed
 
 - `kingmadoc render` links a PNG for each diagram, so the pictures show in every
@@ -42,6 +55,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- The functional design follows one red thread: user stories (one per `REQ-n`), a use
+  case diagram, and per story `US-n` a use case `UC-n`, a screen design `S-n` (a
+  screenshot when the screen exists, else a text wireframe) and evil user stories
+  `EUS-n.m`, each pointing at a security measure `SM-n`. The technical design gets the
+  threat model with those measures. Skill 1.2.0 writes the same.
+- Threat models follow the Microsoft Threat Modeling Tool (template SDL TM Knowledge
+  Base): its stencils (External Interactor, Process, Data Store, trust boundaries such
+  as Internet Boundary), and its report: per interaction the tool's STRIDE threats, each
+  with a state (Not Started, Not Applicable, Needs Investigation, Mitigation
+  Implemented), a priority and a justification, plus the state summary. `threat_model`
+  is now also a model of `technical_design` (default: on). The threats come from
+  Microsoft's own knowledge base (the tool's default template, *SDL TM Knowledge Base
+  (Core)* 4.1.0.11, MIT, bundled from microsoft/threat-modeling-templates):
+  `kingmadoc threats <file>.yml` evaluates its generation rules for every data flow as
+  the tool does and prints the data flow diagram (D2, Mermaid or PlantUML) and the
+  report; `--types` lists the stencils. `explaining-code` uses it, or its generated
+  `reference/threats.md` without the CLI.
+- Every model is on by default and can be chosen: the functional design's parts are
+  models now (`user_stories`, `use_case_diagram`, `use_cases`, `screen_designs`,
+  `evil_user_stories`, `user_flows`, `edge_cases`, `business_rules`, `permissions`);
+  `kingmadoc plan --models a,b` keeps only those (and switches on the documents that
+  have them); `explain.models` lists what the explaining-code agent may draw, and the
+  request can narrow it ("without screens").
+- The functional design (FO) is for stakeholders: what the feature does and for whom,
+  in plain words. Business rules, permissions and edge cases moved to the technical
+  design (TO), which is for developers only: they are models of `technical_design` now
+  (with where each is enforced and its test). The explainer's `functional.md` and
+  `technical.md` split the same way; the threat model has its own reference,
+  `reference/threat-model.md`.
+- `kingmadoc explain scaffold "<subject>"` writes the empty explainer (arc42 or c4;
+  one document, FO + TO, only an FO or only a TO; the chosen models) straight from the
+  skill's reference formats, with the key facts, headings, tables and figure numbers
+  filled in, so the agent no longer reads the output formats. `kingmadoc screenshots
+  <url> /route=name …` captures screens of a running app (one browser with the optional
+  `kingmadoc[screenshots]` extra, else `npx playwright`). The skill is shorter
+  (SKILL.md about 3,400 instead of 4,900 tokens); user stories, screens and evil user
+  stories have their own reference, `reference/stories.md`.
+- `kingmadoc plan --documents split|functional|technical`: by default only the plan is
+  written; "make an FO and TO" (or "functional and technical design", "split") adds
+  both designs, "only an FO" / "only a TO" just that one. The plan skill (1.2.0) maps
+  the request the same way.
+- Explainers pick their documents from the request, without asking back: arc42 by
+  default, "as an FO/TO" writes both, "only an FO" or "only a TO" writes just that one
+  (`explain.documents: functional` / `technical` sets it per project).
+- The arc42 explainer reads like a software architecture document: section 1 lists
+  documented stakeholders and links the requirements (`REQ-n` plan docs); section 3
+  splits into a Business context for stakeholders (actors, use case diagram, user
+  stories with use case, screen and evil user stories) and a Technical context for
+  developers; section 8 adds testability and the repository's stated conventions
+  (code, branches, commits); section 10 lists the quality scenarios the tests cover
+  (context, goal, how it is tested).
+- `explaining-code` 5.9: "document an FO/TO" (functioneel/technisch ontwerp) writes the
+  split explainer with the same red thread: user stories, per story a use case, a
+  screenshot of the running app (the agent asks first; a D2 wireframe from the view code
+  when it cannot run) and evil user stories; `technical.md` gets a threat model in
+  Threat Modeling Tool style (data flow diagram in its notation, its threats per
+  interaction, the security measures the code takes, sensitive data), which a single arc42 or c4 explainer also gets when the code has logins,
+  tokens, personal data or uploads. "Document an arc42" picks the arc42 format.
 - `kingmadoc explain facts` lists private modules from the dominator tree of the module
   graph (Python and JavaScript/TypeScript): what only one module leads to belongs to
   it, which shows the real component boundaries. A single entry point is left out.

{kingmadoc-0.3.0.dev9 → kingmadoc-0.3.0.dev10}/CLAUDE.md

@@ -35,13 +35,35 @@ Flow for `plan "<description>"` (`cli.py`): `config.load_config` → `plan.analy
 - `adr.py` (`kingmadoc adr "<title>"`, gated by the top-level `adr.enabled`; `adr.template` selects the template): `adr_path` → `next_number` (max existing + 1, never reused) + `adr_filename` → `render_adr` (`templates/adr.md.j2`, bundled) → `docs/adr/<NNNN>-<slug>.md`. Not a mode; shares `naming.slugify` and `templating.load_template` with plan.
 - `render.py` (`kingmadoc render <doc>`): renders each ```` ```d2 ```` block with ELK to `img/<doc>-<n>.svg` (dark theme; D2 via `d2_binary.ensure_d2`) and, by default, `img/<doc>-<n>.png` via `raster.svg_to_png` (resvg; D2's embedded WOFF fonts unpacked to TTF and the `d2-N-font-*` CSS names mapped to family + weight, else text is missing), moves its source to `img/<doc>-<n>.d2`, and leaves only `<!-- kingmadoc:diagram img/<doc>-<n>.d2 -->` + the PNG (`--format svg`: the SVG) in the document; `diagram_warnings` = dark-mode styles (only reported for `--format svg`) + crowding (> 12 arrows, doubled pairs) (the comment is invisible in previews; re-rendering reads the `.d2` files, so edit those). Converts the older `<details>` format. Renders everything to a temp dir first, so a failing diagram changes nothing.
 - `d2_binary.py`: `ensure_d2` finds D2 (`KINGMADOC_D2`, PATH, cache) or downloads the pinned release once into the user cache; the SHA-256 per platform is pinned in `D2_ASSETS` (update version + all hashes together, cross-checked with the release's SHA256SUMS). `skills.py` + `kingmadoc skills install`: the skills in `skill/` ship as package data (hatch force-include) and are copied into the agent's skills dir; a `.kingmadoc-skill.json` manifest per skill folder records the installed hashes, so a reinstall updates unchanged files and only blocks local edits (`PREVIOUS_RELEASES` is the frozen hash list for installs from before the manifest).
-- `skill/explaining-code/`: second product skill; explains existing code (feature, branch, project, part) with D2 pictures, one folder per subject `docs/explain/<NNNN>-<slug>/README.md` (`explain.py` + `kingmadoc explain new`: next ID, never reused, same subject reuses its folder; regenerates the index `docs/explain/README.md`, also after `render` of such a file; `explain status` → `freshness`: `git diff --relative --name-only <Based on commit>` over the paths the explainer names in code spans (else the whole project), excluding `docs/explain`; `render` names a README's images `figure-<n>`). `SKILL.md` = workflow and D2 examples; the formats are `reference/arc42.md` (default) and `reference/c4.md`, chosen by `explain.format`; `reference/split.md` for `explain.documents: split` (cover + `functional.md` + `technical.md`); `reference/c4-model.md` (Simon Brown's C4: abstractions, 7 diagrams, notation, D2 style block, checklist) and `reference/models.md` (decision table + rules + one example per other model). `tests/test_skill_explaining_code.py` checks its format and compiles every D2 example with the real `d2` when available (`D2_BIN`); `tests/test_skill_models.py` checks every example obeys its model's rules. D2 pitfalls: quote labels with `[`/`:`; `source-arrowhead` only works on `<->`.
+- `skill/explaining-code/`: second product skill; explains existing code (feature, branch, project, part) with D2 pictures, one folder per subject `docs/explain/<NNNN>-<slug>/README.md` (`explain.py` + `kingmadoc explain new`: next ID, never reused, same subject reuses its folder; regenerates the index `docs/explain/README.md`, also after `render` of such a file; `explain status` → `freshness`: `git diff --relative --name-only <Based on commit>` over the paths the explainer names in code spans (else the whole project), excluding `docs/explain`; `render` names a README's images `figure-<n>`). `SKILL.md` = workflow and D2 examples; the formats are `reference/arc42.md` (default) and `reference/c4.md`, chosen by `explain.format`; `reference/split.md` for `explain.documents: split` (cover + `functional.md` for stakeholders + `technical.md` for developers: rules, permissions, edge cases); `reference/threat-model.md` (Threat Modeling Tool format, via `kingmadoc threats`) and the generated `reference/threats.md`; `reference/c4-model.md` (Simon Brown's C4: abstractions, 7 diagrams, notation, D2 style block, checklist) and `reference/models.md` (decision table + rules + one example per other model). `tests/test_skill_explaining_code.py` checks its format and compiles every D2 example with the real `d2` when available (`D2_BIN`); `tests/test_skill_models.py` checks every example obeys its model's rules. D2 pitfalls: quote labels with `[`/`:`; `source-arrowhead` only works on `<->`.
 - `facts/` (`kingmadoc explain facts`): pure parsers `projects.project_references` (.csproj) and `data_model.data_model` (EF Core via `DbSet<T>`, Prisma, Django, SQLAlchemy, TypeORM; regex, test files skipped) → frozen `Entity`/`Field`/`Relation`; `routes.routes` (ASP.NET controllers + minimal APIs, Next.js app/pages, Django urls + decorators, FastAPI, Flask, Express; `access` = what the code states), `services.services` (.NET DI), `js_modules.js_dependencies` (relative + tsconfig `paths` imports, `plan.dependencies.collapse` above 25 modules, `max_nodes=None` for the raw graph), `dominators.private_modules` (Cooper–Harvey–Kennedy on the raw Python + JS graphs; virtual root above the modules nothing imports; a single entry point is left out); `branch.branch_changes` (git I/O via `git.run_git`, merge base → working tree); `collect.collect_facts` reads files from the `CodebaseReport` and renders Markdown/JSON.
 - `plandoc.py` (not a mode; pure): the plan frontmatter (B2) and `REQ-n` requirements (B1): `check_plan` (every problem as a message), `parse_plan` → `PlanMeta`, `set_status` (frontmatter + header table). `kingmadoc check <slug>` / `approve <slug>` in `cli.py` use `verify.locate.find_plan`. The template renders the frontmatter from `PlanContext.slug/requirements/files_expected` (`generator.requirements_from_answers`: acceptance answer split on `;`/newlines; `files_from_answers`: existing paths only).
 - `verify/` (`kingmadoc verify <slug> [--run-checks]`): `locate.find_plan` (bad slug / missing plan → `VerificationError`) → `changes.detect_changes` (git; base = parent of the commit that added the plan, else last commit before **Generated** + 59 s; working tree incl. untracked; the plan's folder ignored) → `deviations.find_deviations` (pure: draft plan with code = process, `files_expected` untouched / changes outside, `REQ-n` not mentioned in tests or commit messages, containers vs `planned_containers` from the plan text; the CLI passes `infer_containers` names since verify may not import plan) → `commands.detect_commands` (config `verify:` > Makefile > npm > cargo > go > dotnet > pytest/ruff) and `run_check` (no shell; only with `--run-checks`, never enabled by the repo's config) → `report.render_verify` + `verify_status`; the plan's status becomes `implemented`/`partial` unless draft or not verified (written together, `write_documents`). Modes may not import each other (E5, auto-checked), so shared I/O lives in `documents.py`.
+- `scaffold.py` (`kingmadoc explain scaffold`; pure): cuts the ```` ```markdown ```` output blocks out of the explaining-code reference files (`arc42.md`, `c4.md`, `split.md`, `threat-model.md`: the one source of every format), assembles them per format/documents/models (`MODEL_SECTIONS` drops a switched-off model's sections; the TO is the format minus its functional parts plus rules and threat model), fills the key facts and numbers the figures. Change a format in the reference file; `tests/test_scaffold.py` checks the result. `explain.check_explainer` (`kingmadoc explain check`) is the finish gate. `screenshots.py` (`kingmadoc screenshots`): optional Playwright, else `npx playwright screenshot`; http(s) only.
+- `threats/` (`kingmadoc threats <file>.yml`; not a mode, E5): Microsoft Threat Modeling Tool style. `knowledge_base.load_knowledge_base` reads `sdl_knowledge_base.json` (Microsoft's "SDL TM Knowledge Base (Core)", MIT, imported by `scripts/import_tmt_knowledge_base.py`; never edit by hand) → `model.parse_threat_model` (elements/boundaries/flows by the tool's type names) → `model.generate_threats` evaluates each threat type's include/exclude filter per flow with `filters.matches` (types match their parents; `flow crosses`; property defaults = first allowed value) → `report.render_report` (elements, state summary, one table per interaction) + `render_diagram` (d2/mermaid/plantuml). `plan.models._threat_model` feeds it an inferred DFD; `scripts/build_threat_reference.py` writes the skill's `reference/threats.md` (a test fails when stale).
 - `diagrams/`: backend pattern, selected by `diagram_format` (`mermaid` default, `plantuml`, `d2`) via `diagrams.get_backend`. `base.py` has the `DiagramBackend` Protocol (`render_context/container/component/sequence/class`) and the shared pure model: `build_*` validate input, assign unique aliases and resolve relationships into frozen `Diagram`/`Node`/`Edge`. Backend modules (`mermaid.py`, `plantuml.py`, `d2.py`) only format that model and return a fenced block (templates must not add fences). Escaping differs per backend and is verified against the real tools: Mermaid `"`→`#quot;` (C4 titles drop `#`/`;`), PlantUML `"`→`<U+0022>`, D2 escapes `\`, `"`, `$`. Adding a backend: a module, an entry in `diagrams.BACKENDS` and `config.DIAGRAM_FORMATS`, snapshots via `KINGMADOC_UPDATE_SNAPSHOTS=1 pytest tests/test_diagram_backends.py`. Extra-doc templates pick their ER/flowchart placeholder by `diagram_format`. No knowledge of analysis: `generator.build_plan_context` maps analysis → C4 elements.
 - Templates live in `src/kingmadoc/templates/` (shipped as package data). Security: `templating.load_template` loads bundled templates only from that package dir and never searches the analyzed project's root; a project template is used only when a `template:` setting gives an explicit path (`ConfigError` if missing or not a file). Every template renders in Jinja's `SandboxedEnvironment` (repos may be untrusted; see `tests/test_templating_security.py`). Jinja uses `StrictUndefined`, so every template variable must be passed.
 
+## Never again: explainers without pictures
+
+An explainer must **always** end written, rendered and with every picture shown; an empty
+or picture-less `docs/explain/…` is the worst failure this product can have (it happened
+once: a blocking question before writing, and a PNG step that could take the whole render
+down). Guarded by, and never to be weakened:
+
+- `render_file` falls back to the SVG per diagram when PNG conversion fails, and
+  `raster.py` imports `resvg_py` lazily, so a missing wheel or a Rust panic costs PNG,
+  never the pictures or other commands (`tests/test_render.py`: `…falls_back_to_svg`,
+  `…starts_without_resvg`, and `…real_d2_produces_pictures` with `D2_BIN` set).
+- `kingmadoc explain check <folder>` (`explain.check_explainer`) fails on unfilled
+  placeholders, unrendered D2, missing images and captions without pictures; the skill's
+  Step 6 must pass it, and every explain eval scenario runs it (`explain_check`).
+- The skill's first rule is "Always deliver the pictures": no question before the
+  document exists (screenshots are offered at hand-over, wireframes first)
+  (`tests/test_skill_explaining_code.py::test_the_skill_always_delivers_rendered_pictures`).
+- A test that fails with the real `d2` binary (`D2_BIN=…/d2 pytest`) is a bug, never
+  "pre-existing": run the suite with `D2_BIN` before any render or skill change.
+
 ## Conventions
 
 All docs are indexed in `docs/index.md` (English only; add new `.md` files there). Rules: the **Rule summary** table at the top of `docs/conventions.md` (ID, status, auto/manual); open a rule's section only when needed. Key rules:

{kingmadoc-0.3.0.dev9 → kingmadoc-0.3.0.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: kingmadoc
-Version: 0.3.0.dev9
+Version: 0.3.0.dev10
 Summary: Feature docs for AI coding agents: a plan with C4 diagrams before the code, a verification doc after.
 Project-URL: Homepage, https://github.com/ATkingma/KingmaDoc
 Project-URL: Issues, https://github.com/ATkingma/KingmaDoc/issues
@@ -51,6 +51,8 @@ Requires-Dist: pytest-cov>=6.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.16; extra == 'dev'
 Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: screenshots
+Requires-Dist: playwright>=1.40; extra == 'screenshots'
 Description-Content-Type: text/markdown
 
 # KingmaDoc
@@ -149,7 +151,8 @@ change), a whole project, or a part of one. Each subject gets its own folder wit
 unique ID, `docs/explain/<NNNN>-<name>/` (the explainer `README.md` plus its `img/`),
 listed in `docs/explain/README.md`; explaining it again updates that folder. The
 explainer is one document, or on request (or with `explain: {documents: split}`) a
-functional and a technical document next to a cover page. It is by default an **arc42** architecture document (the twelve arc42
+functional and a technical document next to a cover page (FO/TO: user stories with
+use cases, screenshots and evil user stories; a threat model in the technical side). It is by default an **arc42** architecture document (the twelve arc42
 sections, with C4 diagrams per level, runtime flows and deployment), or a compact C4
 zoom-in with `explain: {format: c4}` in `.featuredoc.yml`. Every figure is numbered,
 rendered as an image and decoded by a small table. The C4 diagrams follow Simon Brown's
@@ -196,6 +199,11 @@ More commands:
 
 ```bash
 kingmadoc plan "…" --no-input --stdout   # no questions, print instead of writing
+kingmadoc plan "…" --models user_stories,screen_designs,threat_model   # only these models
+kingmadoc threats threat-model.yml       # Microsoft Threat Modeling Tool threats for a DFD
+kingmadoc explain scaffold "Checkout" --documents split   # empty FO + TO to fill in
+kingmadoc explain check docs/explain/0001-checkout        # fails until every picture shows
+kingmadoc screenshots http://localhost:8000 /cart=screen-us-1 -o docs/explain/0001-checkout/img
 kingmadoc check add-login                # validate a plan's frontmatter and REQ IDs
 kingmadoc approve add-login              # draft -> approved: the gate before code
 kingmadoc explain new "Checkout"         # folder for a subject: docs/explain/0001-checkout/
@@ -224,15 +232,28 @@ file with all defaults and comments; [this repository's
 | `analyzer.exclude_dirs`                   | `.git`, `.venv`, `node_modules`, … | Directory names/globs to skip                                                                                  |
 | `diagrams`                                | `[c4_context, c4_container]`       | Which C4 diagrams the plan contains                                                                            |
 | `diagram_format`                          | `mermaid`                          | `mermaid`, `plantuml` (C4-PlantUML) or `d2`                                                                    |
-| `extra_designs.functional_design.enabled` | `false`                            | Also write `<slug>-functional-design.md`: user flows, edge cases, business rules, permissions                  |
-| `extra_designs.technical_design.enabled`  | `false`                            | Also write `<slug>-technical-design.md`: database schema, API contracts, error handling, performance, security, and a module dependency graph derived from the code |
+| `extra_designs.functional_design.enabled` | `false`                            | Also write `<slug>-functional-design.md`, for stakeholders (plain words, no technical terms): user stories, use case diagram, per story a use case, screen design and evil user stories, user flows |
+| `extra_designs.technical_design.enabled`  | `false`                            | Also write `<slug>-technical-design.md`, for developers: database schema, API contracts, business rules, permissions, edge cases, error handling, performance, security, a threat model in Microsoft Threat Modeling Tool style with security measures, and a module dependency graph derived from the code |
 | `extra_designs.domain_design.enabled` | `false` | Also write `<slug>-domain-design.md`: domain model, event storming |
-| `extra_designs.security_design.enabled` | `false` | Also write `<slug>-security-design.md`: STRIDE threat model (with the inferred elements), who may do what |
-| `extra_designs.<name>.models` | all models of that document | Which design models (sections) the document contains, e.g. `[threat_model]` |
+| `extra_designs.security_design.enabled` | `false` | Also write `<slug>-security-design.md`: threat model (with the inferred elements), who may do what |
+| `extra_designs.<name>.models` | all models of that document | Which design models (sections) the document contains, e.g. `[threat_model]`; `plan --models` picks them per run |
+| `explain.format` / `.documents` | `arc42` / `single` | Explainer format (`arc42`, `c4`); documents: one (arc42), `split` (FO + TO), or only `functional` (FO) or `technical` (TO). The request overrides both ("describe this branch with an FO and a TO", "only a TO") |
+| `explain.models` | all models | What the explaining-code agent may draw (C4, UML, ER, user stories, screens, evil user stories, threat model …); the request can narrow it |
 | `extra_designs.<name>.template`          | bundled template                   | Template for that document: bundled name or explicit path (runs sandboxed)                                     |
 | `adr.enabled`                             | `false`                            | Enable `kingmadoc adr "<title>"`, which writes numbered Architecture Decision Records to `docs/adr/`           |
 | `adr.template`                            | `adr.md.j2`                        | ADR template: bundled name or explicit path (runs sandboxed)                                                   |
 
+### Threat models
+
+Threat models follow the [Microsoft Threat Modeling
+Tool](https://learn.microsoft.com/en-us/azure/security/develop/threat-modeling-tool):
+its data flow notation, and its report (per interaction the threats, with state,
+priority and justification). The threats themselves come from Microsoft's own
+knowledge base, the tool's default template *SDL TM Knowledge Base (Core)*, bundled
+from [microsoft/threat-modeling-templates](https://github.com/microsoft/threat-modeling-templates)
+(MIT license, Copyright (c) Microsoft Corporation); `kingmadoc threats` evaluates its
+generation rules for every data flow the way the tool does.
+
 ## Comparison
 
 How KingmaDoc relates to tools with overlapping goals, based on each project's own

{kingmadoc-0.3.0.dev9 → kingmadoc-0.3.0.dev10}/README.md

@@ -94,7 +94,8 @@ change), a whole project, or a part of one. Each subject gets its own folder wit
 unique ID, `docs/explain/<NNNN>-<name>/` (the explainer `README.md` plus its `img/`),
 listed in `docs/explain/README.md`; explaining it again updates that folder. The
 explainer is one document, or on request (or with `explain: {documents: split}`) a
-functional and a technical document next to a cover page. It is by default an **arc42** architecture document (the twelve arc42
+functional and a technical document next to a cover page (FO/TO: user stories with
+use cases, screenshots and evil user stories; a threat model in the technical side). It is by default an **arc42** architecture document (the twelve arc42
 sections, with C4 diagrams per level, runtime flows and deployment), or a compact C4
 zoom-in with `explain: {format: c4}` in `.featuredoc.yml`. Every figure is numbered,
 rendered as an image and decoded by a small table. The C4 diagrams follow Simon Brown's
@@ -141,6 +142,11 @@ More commands:
 
 ```bash
 kingmadoc plan "…" --no-input --stdout   # no questions, print instead of writing
+kingmadoc plan "…" --models user_stories,screen_designs,threat_model   # only these models
+kingmadoc threats threat-model.yml       # Microsoft Threat Modeling Tool threats for a DFD
+kingmadoc explain scaffold "Checkout" --documents split   # empty FO + TO to fill in
+kingmadoc explain check docs/explain/0001-checkout        # fails until every picture shows
+kingmadoc screenshots http://localhost:8000 /cart=screen-us-1 -o docs/explain/0001-checkout/img
 kingmadoc check add-login                # validate a plan's frontmatter and REQ IDs
 kingmadoc approve add-login              # draft -> approved: the gate before code
 kingmadoc explain new "Checkout"         # folder for a subject: docs/explain/0001-checkout/
@@ -169,15 +175,28 @@ file with all defaults and comments; [this repository's
 | `analyzer.exclude_dirs`                   | `.git`, `.venv`, `node_modules`, … | Directory names/globs to skip                                                                                  |
 | `diagrams`                                | `[c4_context, c4_container]`       | Which C4 diagrams the plan contains                                                                            |
 | `diagram_format`                          | `mermaid`                          | `mermaid`, `plantuml` (C4-PlantUML) or `d2`                                                                    |
-| `extra_designs.functional_design.enabled` | `false`                            | Also write `<slug>-functional-design.md`: user flows, edge cases, business rules, permissions                  |
-| `extra_designs.technical_design.enabled`  | `false`                            | Also write `<slug>-technical-design.md`: database schema, API contracts, error handling, performance, security, and a module dependency graph derived from the code |
+| `extra_designs.functional_design.enabled` | `false`                            | Also write `<slug>-functional-design.md`, for stakeholders (plain words, no technical terms): user stories, use case diagram, per story a use case, screen design and evil user stories, user flows |
+| `extra_designs.technical_design.enabled`  | `false`                            | Also write `<slug>-technical-design.md`, for developers: database schema, API contracts, business rules, permissions, edge cases, error handling, performance, security, a threat model in Microsoft Threat Modeling Tool style with security measures, and a module dependency graph derived from the code |
 | `extra_designs.domain_design.enabled` | `false` | Also write `<slug>-domain-design.md`: domain model, event storming |
-| `extra_designs.security_design.enabled` | `false` | Also write `<slug>-security-design.md`: STRIDE threat model (with the inferred elements), who may do what |
-| `extra_designs.<name>.models` | all models of that document | Which design models (sections) the document contains, e.g. `[threat_model]` |
+| `extra_designs.security_design.enabled` | `false` | Also write `<slug>-security-design.md`: threat model (with the inferred elements), who may do what |
+| `extra_designs.<name>.models` | all models of that document | Which design models (sections) the document contains, e.g. `[threat_model]`; `plan --models` picks them per run |
+| `explain.format` / `.documents` | `arc42` / `single` | Explainer format (`arc42`, `c4`); documents: one (arc42), `split` (FO + TO), or only `functional` (FO) or `technical` (TO). The request overrides both ("describe this branch with an FO and a TO", "only a TO") |
+| `explain.models` | all models | What the explaining-code agent may draw (C4, UML, ER, user stories, screens, evil user stories, threat model …); the request can narrow it |
 | `extra_designs.<name>.template`          | bundled template                   | Template for that document: bundled name or explicit path (runs sandboxed)                                     |
 | `adr.enabled`                             | `false`                            | Enable `kingmadoc adr "<title>"`, which writes numbered Architecture Decision Records to `docs/adr/`           |
 | `adr.template`                            | `adr.md.j2`                        | ADR template: bundled name or explicit path (runs sandboxed)                                                   |
 
+### Threat models
+
+Threat models follow the [Microsoft Threat Modeling
+Tool](https://learn.microsoft.com/en-us/azure/security/develop/threat-modeling-tool):
+its data flow notation, and its report (per interaction the threats, with state,
+priority and justification). The threats themselves come from Microsoft's own
+knowledge base, the tool's default template *SDL TM Knowledge Base (Core)*, bundled
+from [microsoft/threat-modeling-templates](https://github.com/microsoft/threat-modeling-templates)
+(MIT license, Copyright (c) Microsoft Corporation); `kingmadoc threats` evaluates its
+generation rules for every data flow the way the tool does.
+
 ## Comparison
 
 How KingmaDoc relates to tools with overlapping goals, based on each project's own

{kingmadoc-0.3.0.dev9 → kingmadoc-0.3.0.dev10}/docs/index.md

@@ -31,7 +31,10 @@ Feature Verification Doc afterwards.
   [arc42](../skill/explaining-code/reference/arc42.md), [C4](../skill/explaining-code/reference/c4.md);
   models: [C4 model](../skill/explaining-code/reference/c4-model.md),
   [UML, ER, DFD and others](../skill/explaining-code/reference/models.md);
-  [one document or functional and technical apart](../skill/explaining-code/reference/split.md))
+  [one document or functional and technical apart (FO/TO)](../skill/explaining-code/reference/split.md),
+  [user stories, use cases, screens](../skill/explaining-code/reference/stories.md),
+  [threat model](../skill/explaining-code/reference/threat-model.md),
+  [Microsoft threat knowledge base](../skill/explaining-code/reference/threats.md))
   ([README: Markdown-only install](../README.md#markdown-only-no-python))
 - **Seeing what the output looks like** → [Example plan doc](../examples/verify-mode-plan.md)
 - **Contributing code** → [Conventions: Python coding standards](conventions.md#d-python-coding-standards)
@@ -65,6 +68,8 @@ in the package.
 | [`checking-conventions` skill](../.claude/skills/checking-conventions/SKILL.md) | Checks changes against the conventions: automatic checker + manual review workflow |
 | [`.claude/settings.json`](../.claude/settings.json) | Stop hook that runs the convention checker after every agent turn |
 | [`scripts/build_skill_variants.py`](../scripts/build_skill_variants.py) | Generates the Cursor, Codex and Copilot skill variants from `skill/SKILL.md` |
+| [`scripts/import_tmt_knowledge_base.py`](../scripts/import_tmt_knowledge_base.py) | Imports Microsoft's threat knowledge base (`default.tb7`) into `src/kingmadoc/threats/sdl_knowledge_base.json` |
+| [`scripts/build_threat_reference.py`](../scripts/build_threat_reference.py) | Writes the skill's `reference/threats.md` from that knowledge base |
 | [`.github/workflows/ci.yml`](../.github/workflows/ci.yml) | CI: pytest on Python 3.11–3.13, Linux/macOS/Windows, plus a CLI smoke test |
 | [Bug report](../.github/ISSUE_TEMPLATE/bug_report.md), [feature request](../.github/ISSUE_TEMPLATE/feature_request.md) | GitHub issue templates |
 

{kingmadoc-0.3.0.dev9 → kingmadoc-0.3.0.dev10}/evals/README.md

@@ -7,6 +7,7 @@ skills installed (roadmap WP5).
 | Scenario | Skill | Request | Checks |
 | --- | --- | --- | --- |
 | [explain-feature](scenarios/explain-feature.yml) | `explaining-code` | Explain how placing an order works | explainer in `docs/explain/0001-*/`, arc42 headings, pictures only, at most three questions, no code changed |
+| [explain-fo-to](scenarios/explain-fo-to.yml) | `explaining-code` | "Maak een FO en TO over de branch" (Dutch) | cover, `functional.md` (domain model, user stories, evil user stories) and `technical.md` (business rules, threat model, C4 level 2), `kingmadoc explain check`, no code changed |
 | [explain-branch](scenarios/explain-branch.yml) | `explaining-code` | Explain what `feature/discount` changed | "What changed" about the discount, pictures only, no code changed |
 | [plan-feature](scenarios/plan-feature.yml) | `kingmadoc` | Plan cancelling an order, don't build it | plan in `docs/features/`, plan headings, passes `kingmadoc check`, no code changed (the approval gate) |
 
@@ -41,6 +42,16 @@ recorded result shows a real failure.
 | same run, without skill | 2/6 | 2/5 | 1/3 |
 | [2026-09-27 11:26](results/2026-09-27T112600Z.json), with skill, 3 runs | | | 4/4, 4/4, 4/4 |
 
+| [2026-09-28 06:45](results/2026-09-28T064505Z.json), skill 5.9 (before the optimisation) | 7/7, 173 s, $1.15 | 6/6, 100 s, $0.86 | FO/TO: stopped by the spend limit, D2 left unrendered |
+| [2026-09-28 09:26](results/2026-09-28T092643Z.json), skill 6.0 (scaffold, shorter skill) | 7/7, 256 s, $1.54 | 6/6, 99 s, $0.81 | FO/TO: 8/8, 367 s, $2.10 |
+
+Rows from 2026-09-28 are re-checked with the current checks (`explain_check`,
+`__pycache__` ignored, Dutch headings accepted). The 6.0 feature run filled the scaffold
+placeholder by placeholder (41 turns instead of 22); the skill now says to write each
+document in one pass: [2026-09-28 09:30](results/2026-09-28T093046Z.json), explain-feature
+7/7, 192 s, $1.23, 20 turns, with the larger 6.0 content (user stories, rules, threat
+model) at about the cost of the 5.9 run.
+
 After the first run the plan scenario says the user cannot answer now (the skill's
 non-interactive path). The baseline runs of 11:26 hit the account's spend limit and
 did not run; they are not a result.

kingmadoc-0.3.0.dev10/evals/results/2026-09-28T064505Z.json

@@ -0,0 +1,159 @@
+{
+  "agent": "claude -p {request} --output-format json --max-turns 80 --allowedTools 'Read,Write,Edit,Glob,Grep,Skill,Bash(kingmadoc:*),Bash(git log:*),Bash(git diff:*),Bash(git status:*),Bash(git show:*),Bash(git branch:*),Bash(git rev-parse:*),Bash(ls:*)'",
+  "results": [
+    {
+      "scenario": "explain-branch",
+      "variant": "with skill",
+      "agent": {
+        "exit_code": 0,
+        "seconds": 100,
+        "total_cost_usd": 0.8613995499999999,
+        "num_turns": 25,
+        "tokens": {
+          "input_tokens": 30,
+          "cache_creation_input_tokens": 64155,
+          "cache_read_input_tokens": 690090,
+          "output_tokens": 9188
+        },
+        "reply": "ld the discounted amount. No field keeps the original total or the discount amount. The threshold and rate are fixed in the code, and there are no tests for any of this.\n- **Other commit (`7bc5fcf`):** it only adds the KingmaDoc skill files under `.claude/skills/`. The shop never runs them.\n\nThe three diagrams show which parts changed, how placing an order runs with the discount step, and how the discount is calculated, with a table of example inputs checked by running the function.\n\nShould VS Code open explainers directly as a preview, so the pictures show? Otherwise, Ctrl+Shift+V shows them."
+      },
+      "checks": [
+        {
+          "check": "exists docs/explain/0001-*/README.md",
+          "ok": true,
+          "detail": "docs/explain/0001-branch-feature-discount/README.md"
+        },
+        {
+          "check": "contains docs/explain/0001-*/README.md",
+          "ok": true,
+          "detail": "all present"
+        },
+        {
+          "check": "pictures_only docs/explain/0001-*/*.md",
+          "ok": true,
+          "detail": "3 images"
+        },
+        {
+          "check": "max_questions docs/explain/0001-*/README.md",
+          "ok": true,
+          "detail": "0 question(s)"
+        },
+        {
+          "check": "unchanged_outside [docs/, .claude/]",
+          "ok": false,
+          "detail": "shop/__pycache__/__init__.cpython-311.pyc, shop/__pycache__/discounts.cpython-311.pyc"
+        }
+      ],
+      "passed": 4,
+      "total": 5
+    },
+    {
+      "scenario": "explain-feature",
+      "variant": "with skill",
+      "agent": {
+        "exit_code": 0,
+        "seconds": 173,
+        "total_cost_usd": 1.15176445,
+        "num_turns": 22,
+        "tokens": {
+          "input_tokens": 34,
+          "cache_creation_input_tokens": 71975,
+          "cache_read_input_tokens": 890083,
+          "output_tokens": 18567
+        },
+        "reply": "hipped` status.\n- Stock taken by orders that are never paid is never given back.\n- There's no CSRF protection.\n- An unknown product ID, bad JSON, or a missing customer returns a 500 error.\n- There are no tests or migrations.\n\n**Couldn't work out:**\n- How does a customer sign in? `shop/settings.py` has no `MIDDLEWARE` and doesn't install sessions, and there's no login route, so `@login_required` has nothing to check against.\n- Who creates `Customer` rows, and is `shipped` still planned?\n\nShould VS Code open explainers directly as a preview, so the pictures show? If not, Ctrl+Shift+V shows them."
+      },
+      "checks": [
+        {
+          "check": "exists docs/explain/0001-*/README.md",
+          "ok": true,
+          "detail": "docs/explain/0001-placing-an-order/README.md"
+        },
+        {
+          "check": "exists docs/explain/README.md",
+          "ok": true,
+          "detail": "docs/explain/README.md"
+        },
+        {
+          "check": "contains docs/explain/0001-*/README.md",
+          "ok": true,
+          "detail": "all present"
+        },
+        {
+          "check": "pictures_only docs/explain/0001-*/*.md",
+          "ok": true,
+          "detail": "8 images"
+        },
+        {
+          "check": "max_questions docs/explain/0001-*/README.md",
+          "ok": true,
+          "detail": "2 question(s)"
+        },
+        {
+          "check": "unchanged_outside [docs/, .claude/]",
+          "ok": true,
+          "detail": "27 change(s), all allowed"
+        }
+      ],
+      "passed": 6,
+      "total": 6
+    },
+    {
+      "scenario": "explain-fo-to",
+      "variant": "with skill",
+      "agent": {
+        "exit_code": 1,
+        "seconds": 113,
+        "total_cost_usd": 0.8422781499999998,
+        "num_turns": 16,
+        "tokens": {
+          "input_tokens": 20,
+          "cache_creation_input_tokens": 65220,
+          "cache_read_input_tokens": 482569,
+          "output_tokens": 11015
+        },
+        "reply": "You've hit your monthly spend limit \u00b7 raise it at claude.ai/settings/usage?from=cc_cli_limit_message \u00b7 your session limit resets 11am (Europe/Amsterdam)",
+        "error": "You've hit your monthly spend limit \u00b7 raise it at claude.ai/settings/usage?from=cc_cli_limit_message \u00b7 your session limit resets 11am (Europe/Amsterdam)"
+      },
+      "checks": [
+        {
+          "check": "exists docs/explain/0001-*/functional.md",
+          "ok": true,
+          "detail": "docs/explain/0001-branch-feature-discount/functional.md"
+        },
+        {
+          "check": "exists docs/explain/0001-*/technical.md",
+          "ok": false,
+          "detail": "nothing at docs/explain/0001-*/technical.md"
+        },
+        {
+          "check": "contains docs/explain/0001-*/functional.md",
+          "ok": true,
+          "detail": "all present"
+        },
+        {
+          "check": "contains docs/explain/0001-*/technical.md",
+          "ok": false,
+          "detail": "nothing at docs/explain/0001-*/technical.md"
+        },
+        {
+          "check": "pictures_only docs/explain/0001-*/*.md",
+          "ok": false,
+          "detail": "docs/explain/0001-branch-feature-discount/functional.md: D2 source not rendered; no images"
+        },
+        {
+          "check": "max_questions docs/explain/0001-*/*.md",
+          "ok": true,
+          "detail": "0 question(s)"
+        },
+        {
+          "check": "unchanged_outside [docs/, .claude/]",
+          "ok": false,
+          "detail": "shop/__pycache__/__init__.cpython-311.pyc, shop/__pycache__/discounts.cpython-311.pyc"
+        }
+      ],
+      "passed": 3,
+      "total": 7
+    }
+  ]
+}