T-7N05-containment-pass-over-corpus

State: closed/done · Impact: medium · Complexity: medium

Goal

Blocked: this task cannot start until the owner-approved proposal exists as a repo file (see Dependencies). It stays at planning/draft until then. Every acceptance criterion below quantifies over “the approved proposal” and means only the pairs that file lists.

Give the capability graph more depth where it is true. Of the 127 capabilities, 54 have no parent_key today; 51 of them are not kind: system (the figure in M-YX34). This task applies a reviewed containment pass: each capability whose definition places it inside another gets that parent, and the rest stay as they are.

Today

Containment is parent_key on the inner capability: a wikilink to another capability, or null (solutions/ontological/lib/model/entities/capability/schema.ts, the parent_key field).
TM-0036-containment: nesting is authored on capabilities, is a modelling aid, a capability sits under another only when its own definition makes it part of that one, several roots are normal, and nothing enforces a parent.
TM-0038-unnested-capability: a capability with no parent that is not a root, where nothing in its definition makes it part of another. It is not an error and no check reports it.
Count: bun run solutions/ontological/cli/sdlc.ts capability graph prints one tab-separated row per capability (id, parent, kind, audience, state, title; parent is - when absent) and a footer. On 2026-10-03 it printed 127 rows and warnings=0. Counting rows whose second column is - gave 54. Three of those are kind: system roots (C-0050, C-8FKM, C-HRNS), which leaves 51 unnested non-system capabilities, the milestone’s figure. C-HRNS is closed/retired.
Model (C-0052) is a subsystem under Control plane C-0050. Deepening it means placing inner capabilities under it where their definitions say they are part of it.
The write path is sdlc capability update <capability> --set '<json>' (solutions/ontological/lib/model/entities/capability/ops/update.ts), schema-validated before any write.

Proposed

Every capability in the approved proposal has the parent_key the proposal names. Every capability not in the proposal is byte-for-byte unchanged. The proposal includes a second part: deepen the large subtrees, starting with Model (C-0052), only where definitions support it.

Approach

Obtain the owner-approved proposal as a committed file (for example a note under docs/planning/notes/) holding a list of <capability file> -> <parent id> pairs, plus a list of capabilities deliberately left unnested with a one-line reason each. Cite that file in the PR. This is an input, not work this task does.
Record the starting state outside the repo: bun run solutions/ontological/cli/sdlc.ts capability graph > before.txt, count rows with - in column 2, and save the audit baseline with bun run solutions/ontological/cli/sdlc.ts entities audit --strict > audit-before.txt.
For each pair, run bun run solutions/ontological/cli/sdlc.ts capability update <file> --set '{"parent_key":"C-XXXX"}'. Do not add a parent that is not in the proposal.
Run capability graph again and compare with before.txt. Only the proposal’s rows may change.
Run the validation commands under Verification.
Put the left-unnested list, one line of reason each, in the PR body.

Areas

Area	Note
`docs/planning/capabilities/`	`parent_key` frontmatter of the listed capabilities only
`solutions/ontological/lib/model/entities/capability/ops/update.ts`	The write op; not edited

Acceptance criteria

AC-1: git diff --name-only lists only files named in the approved proposal, and each diff changes only the parent_key line.
AC-2: For every pair in the approved proposal file, and only those pairs, capability graph shows that parent in column 2.
AC-3: capability graph ends with warnings=0, and no new kind of warning appears (compare with before.txt).
AC-4: sdlc entities validate docs/planning/capabilities/*.md exits 0.
AC-5: bun run solutions/ontological/cli/sdlc.ts entities audit --strict output matches audit-before.txt for capabilities (no new findings), and entities validate (AC-4) passes.
AC-6: The PR body lists the left-unnested set named in the approved proposal file, with a one-line reason per entry.
AC-7: The parentless count after the pass equals the starting count minus the number of proposal pairs whose capability had no parent before. Pairs that re-parent an already parented capability (the second part, deepening subtrees such as Model) do not change that count; the proposal file marks which pairs are which.

Verification

bun run solutions/ontological/cli/sdlc.ts capability graph | tail -1
bun run solutions/ontological/cli/sdlc.ts capability graph | awk -F'\t' '$2=="-"' | wc -l
bun run solutions/ontological/cli/sdlc.ts entities validate docs/planning/capabilities/*.md
git diff -U0 -- docs/planning/capabilities | rg '^[+-][^+-]' | rg -v 'parent_key' returns nothing.

Out of scope

Forcing a parent on any capability the definitions do not place inside another.
Writing the proposal itself, or changing capability kind, state, locations or body text.
Changing the capability graph output (see T-4RB7-capability-graph-tree-output).
Any rule or check that requires a parent.

Dependencies

The owner-approved proposal does not exist yet and this task is blocked on it. It is being prepared separately and must land as a repo file (a note under docs/planning/notes/ or an appendix to this task) before this task leaves planning/draft. Giving the proposal its own task is an option for the owner.
T-4RB7-capability-graph-tree-output (tree output) would make the review easier but is not required.

← Back to Tasks