ek9_query_requirement

Answers status (ok | not-found) and requirementId first, then the node(s): each carries authored{title, body, retired, meta} and derived{developed, anchoringTests, parentChain, children} so a computed rollup is never mistaken for a person's assertion; list and outstanding return requirementCount + requirements[], footprint the anchoringTests and reachedSymbols.

Category: Enquiry · Compare: Requirement navigator tree + detail pane (planned)

When to use it

'What does requirement X say, and what is under it?' is one call: {mode:'detail', requirementId:'REQ:fraud-screening'}; mode 'outstanding' with no id is the backlog.

When not to use it

Mutating a requirement (title/body/retired) — use ek9_update_requirement (writes are bottom-up; you never set derived children/rollups).
Creating new requirements — use ek9_create_requirement.
Blast radius (which requirements reach a given SYMBOL) — starts from a symbol, so use ek9_query_construct_neighbourhood, whose requirements[] axis answers exactly that.
Checking that requirement references resolve at compile time — that is ek9_check_requirements.

Details

Modes: detail (one node), hierarchy (subtree, optional depth), list (filter by developed/retired/prefix/assignee/titleLike), outstanding (live, not yet developed — the backlog), footprint (call-graph reach of the requirementId's anchoring tests - over-inclusive by construction, reachResolved:false when the call graph is unavailable). 'developed' is always derived and read-only - anchored by a @Test directly or via children, NOT that it is correct or adequately tested. Every response opens with status: 'ok', or 'not-found' from detail/hierarchy for an unknown requirementId; footprint just reports empty anchoringTests.

Arguments

Argument	Type	Required	What it is
`assignee`	string		For list: match nodes whose meta.assignee equals this.
`depth`	integer		For hierarchy: how far down to walk. Omit for the whole subtree; 1 gives the node and its direct children.
`developed`	boolean		For list: match only developed (true) or only outstanding (false). Omit to match either.
`mode`	string: detail \| hierarchy \| list \| outstanding \| footprint	yes	Which read to perform.
`prefix`	string: REQ \| CTRL \| CAP \| CON		For list: match one node kind.
`requirementId`	string		Required for detail, hierarchy and footprint, e.g. REQ:fraud-screening.
`retired`	boolean		For list: match only retired (true) or only live (false). Omit to match either.
`titleLike`	string		For list: case-insensitive substring of the title or body.

Recorded calls

Real calls, recorded against small projects and checked on every build - a changed answer fails it. 3 of the 6 recorded are shown.

Query requirement not found

Request

{
  "mode" : "detail",
  "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"
}

Query requirement footprint

Request

{
  "mode" : "footprint",
  "requirementId" : "REQ:fraud"
}

Response

{
  "anchoringTests" : [ "introduction::FraudTest" ],
  "meta" : {
    "serverMs" : "<timing>"
  },
  "note" : "reachedSymbols is what these tests CAN REACH, not what implements the requirement — over-inclusive by construction",
  "reachResolved" : true,
  "reachedSymbols" : [ "org.ek9.lang::Stdout.Stdout()" ],
  "requirementId" : "REQ:fraud",
  "status" : "ok"
}

Query requirement detail

Request

{
  "mode" : "detail",
  "requirementId" : "REQ:fraud"
}

Response

{
  "authored" : {
    "body" : "# Intent\n\nWhy this exists.",
    "meta" : { },
    "retired" : false,
    "ruleAnchors" : [ ],
    "title" : "Screen inbound payments",
    "version" : "0.1.0"
  },
  "derived" : {
    "anchoringTests" : [ "introduction::FraudTest" ],
    "children" : [ ],
    "depth" : 0,
    "developed" : true,
    "isLeaf" : true,
    "liveChildCount" : 0,
    "parentChain" : [ ],
    "ruleAnchored" : false,
    "viaChildren" : false
  },
  "meta" : {
    "serverMs" : "<timing>"
  },
  "requirementId" : "REQ:fraud",
...

Cut short here: 2 more lines. The whole recorded call.