ek9_render_specification

Answers status (ok | not-found), requirementId and markdown - the specification document generated from the requirement graph with every section marked authored or derived - plus anchorsResolved saying whether a compile backed the derived sections.

Category: Enquiry · Compare: Requirement navigator → Render Specification… preview (planned)

When to use it

'Write me the specification for X' is one call: {requirementId:'CAP:payments'} renders the subtree as markdown from the graph - a root for the exec summary, a leaf for acceptance criteria.

When not to use it

You want the requirement graph structure / traceability, not a rendered doc — use ek9_query_requirement.
Checking that requirement references resolve — use ek9_check_requirements.
Authoring or confirming intent (the 'why' bodies this render displays) — use ek9_update_requirement (its confirm-intent mode stamps the 'last confirmed' date).
PDF / Word / slides — this emits markdown only; pipe the output through pandoc / the docx/pptx/pdf conversion downstream.

Details

A view, never a stored source: the requirement nodes are the truth, the markdown is disposable and must not be persisted as source. Every render visibly separates derived (what the code provably does, always fresh) from authored (recorded intent) — that separation is the anti-staleness guarantee. Top-level anchorsResolved is true only when a compiled program was available; when false, derived sections are absent (not wrong) so 'nothing anchors this' is distinguishable from 'nothing compiled'.

Arguments

Argument	Type	Required	What it is
`depth`	integer		How far down to disclose. Omit for the whole subtree; 1 gives the node and its direct children.
`profile`	string: technical \| summary		technical names the anchoring tests; summary gives intent and status only.
`requirementId`	string	yes	Where to cut the tree, e.g. CAP:payments. Render from a root for the whole picture.

Recorded calls

Real calls, recorded against small projects and checked on every build - a changed answer fails it.

Render specification not found

Request

{
  "requirementId" : "REQ:never-created"
}

Response

{
  "detail" : "no requirement with this id exists in .ek9-ai/requirements/",
  "meta" : {
    "serverMs" : "<timing>"
  },
  "nextStep" : "ek9_query_requirement {mode:'list'} to see the ids that do exist",
  "requirementId" : "REQ:never-created",
  "status" : "not-found"
}

Render specification summary

Request

{
  "profile" : "summary",
  "requirementId" : "REQ:fraud"
}

Response

{
  "anchorsResolved" : true,
  "markdown" : "\n# Screen inbound payments\n\n> *derived* · `REQ:fraud` · **developed** · anchored by 1 test · *intent unconfirmed*\n\nProse.\n\n---\n\n> **This document is generated from the requirement graph.** Do not edit it — edit the requirements and render again.\n>\n> **How to read it:** under each heading, the marked block comes first and is entirely *derived* — computed on every render from the graph and the tests the compiler can see. Everything after that block, up to the next heading, is *authored* prose written by a person, and is the only editable content.\n>\n> That position is the guarantee, not the markers themselves. Authored prose is rendered exactly as written, so it may contain text resembling a derived fact; anything below the block under a heading is prose, whatever it looks like.\n>\n> **\"Developed\" means something claims responsibility for the requirement — a test names it, or a rule binds to it. It does NOT mean correct, adequately tested, or bug-free:** an anchoring test may be failing, or may be asserting something unrelated, and nothing can detect that. Whether the code works is reported by the test run and the quality report, not here.\n>\n> 1 of 1 requirements in this document are developed; 1 have intent that nobody has confirmed against the current code.\n",
  "meta" : {
    "serverMs" : "<timing>"
  },
  "profile" : "summary",
  "requirementId" : "REQ:fraud",
  "status" : "ok"
}

Render specification technical

Request

{
  "requirementId" : "REQ:payments"
}

Response

{
  "anchorsResolved" : true,
  "markdown" : "\n# Payments\n\n> *derived* · `REQ:payments` · **developed** · because everything below it is · *intent unconfirmed*\n\nEverything about moving customer money.\n\n## Screen inbound payments\n\n> *derived* · `REQ:fraud` · **developed** · anchored by 1 test · *intent unconfirmed*\n\n> *derived* · definition of success:\n>   - `introduction::FraudTest`\n\n#### Intent\n\nEvery payment is screened before settlement.\n\n---\n\n> **This document is generated from the requirement graph.** Do not edit it — edit the requirements and render again.\n>\n> **How to read it:** under each heading, the marked block comes first and is entirely *derived* — computed on every render from the graph and the tests the compiler can see. Everything after that block, up to the next heading, is *authored* prose written by a person, and is the only editable content.\n>\n> That position is the guarantee, not the markers themselves. Authored prose is rendered exactly as written, so it may contain text resembling a derived fact; anything below the block under a heading is prose, whatever it looks like.\n>\n> **\"Developed\" means something claims responsibility for the requirement — a test names it, or a rule binds to it. It does NOT mean correct, adequately tested, or bug-free:** an anchoring test may be failing, or may be asserting something unrelated, and nothing can detect that. Whether the code works is reported by the test run and the quality report, not here.\n>\n> 2 of 2 requirements in this document are developed; 2 have intent that nobody has confirmed against the current code.\n",
  "meta" : {
    "serverMs" : "<timing>"
  },
  "profile" : "technical",
  "requirementId" : "REQ:payments",
  "status" : "ok"
}