issue_86: Record the skill decomposition boundary

[dieterbaier]

Closes #86.

What this adds

ADR-008-skill-decomposition-boundary — Skill Decomposition and Agent Role
Boundary, status: accepted, reviewed: true.

Canonical skills are cut by lifecycle capability and verifiable outcome, never
by agent persona. Role-based agents may exist as an orchestration layer above
the toolkit and consume the same canonical skills; they do not own a copy of the
lifecycle. This decides the cut, not how many agents execute a change, and not
where the role-to-skill binding lives.

The Context separates three questions that are usually asked as one:

Question	What it decides	Decided here
Cut	capability or persona	yes
Allocation	which skills an executing agent receives	no — belongs to the orchestration layer
Agent decomposition	how many agents, with which context and permissions	no — stays free

A platform that decomposes its agents by role does not thereby cut its
skills by role. Only the second conflicts with this decision, so a role-based
agent platform whose skills stay capability-shaped sits inside Option 1 rather
than opposite it.

R-007-gate-results-lack-independence — likelihood high, impact medium,
priority medium, status: proposed.

A capability cut cannot express who executes a gate, so the implementing context
can produce its own authoritative Convergence Check result. Per owner review that
is an exposure a cross-functional team accepts and watches, not a reason to
separate roles. R-007 refines R-001 — narrowing it from artifacts in general to
gate results, where the mitigation is execution independence rather than a
lifecycle status marker — and affects QS-004. ADR-008 introduces_risk to it.

Its evidence is on this branch: see the Convergence Check note below.

The rating is deliberately not lowered yet for the intention to run the gate from
a fresh context, and R-007 now names #87 as the control that would move it — in
the assessment, which says the rating is expected to be revisited when that issue
closes, and on the mitigation that depends on it. Fresh execution is exactly the control that would move the
likelihood — it prevents the event rather than softening it — but nothing
requires it today: no skill declares an execution context and there is no
execution layer that could enforce one. The assessment now says so, and the
mitigation options are split by the dimension each one moves.

Owner review outcome

The accountable owner reviewed and accepted the decision. The body status is
Accepted (derived) — the contract reserves that wording for a decision whose
rationale was AI-drafted and whose acceptance is human, and both hold here.

Two consequences of accepting, both deliberate:

• The summary said "Proposed decision to cut …", which the ADR index renders
  next to the status. It now says "Accepted decision …".
• All four relations move to status: accepted / reviewed: true. The owner
  accepted the impact claims together with the decision. The review note records
  what that means: the claim holds, not that the artifact it points at has been
  accepted — QS-005, R-006 and R-007 stay proposed in their own right.

All open questions from the first draft are settled and recorded in #86:

• refines ADR-005 confirmed — the review note asking whether it should be a
  sibling relation is removed.
• The independence consequence becomes R-007 — a scope change relative to
  Record an ADR: skills are cut by capability, not by role #86, which had scoped the work to one ADR.
• No maintained example — the illustration stays an illustration; the
  decision holds without one. Reusing it outside the architecture documentation
  is now Present the skill decomposition position outside the architecture documentation #91.
• The binding stays outside the toolkit — ADR-008 now shows a short
  illustration marked explicitly as not a toolkit format. It allocates an entry
  skill per role rather than a list of skills, so everything that skill
  mandatorily delegates to comes with it and the allocation is closed under
  delegation by construction. That also settles whether the toolkit should
  publish a machine-readable closure: it should not. The obligation recorded
  under Negative now applies only to a platform that chooses to enumerate a
  fixed list instead.

The Pugh matrix is unchanged. Final sums: capability cut 2, per-role copies
1, persona cut 0. The commentary attributes each criterion the persona cut
wins to the axis it comes from — organisational mappability follows from the
cut, independence of verification from agent decomposition.

Also updated: DOC-09000 and DOC-11000 register the new artifacts, following
the pattern used for ADR-001 … ADR-007 and R-001 … R-006.

Reconciled with the acceptance — three documents asserted something the
repository no longer supports once ADR-008 became accepted:

• doc-11002-technical-debt.adoc — TD-002 said the decisions chapter holds ADRs
  "not yet human-reviewed or accepted". Scoped to the remainder rather than
  deleted; the debt for ADR-001 … ADR-007 is unchanged.
• doc-005-questions-and-answers.adoc — Q-ARCH-006 read as entirely undecided
  while ADR-008 states it answers one instance of it. The original answer is
  untouched; a second paragraph records the settled instance and the general
  question stays open.
• doc-09000-architecture-decisions.adoc — the documents rationale for ADR-008
  called it a "proposed ADR detail page". Now status-neutral. The string reaches
  the generated impact fragment but not the rendered documentation, because that
  fragment is included nowhere; an earlier revision of this body overstated its
  reach.

Evidence made checkable — R-007 cited a converged result from an earlier
revision of this body. Pull request bodies are rewritten on every re-run and
their earlier revisions cannot be retrieved, so a risk about untrustworthy check
results was resting on a check result nobody could verify. It now cites two
permanent comment links instead, and says why its evidence sits outside the
repository: there is no record here of how a check was executed, which is the
limitation the risk describes.

None of these is collateral tidying: each is a document the accepted decision
points at.

Verification

Check	Result
./build.sh validate	Passed — 0 errors, 38 warnings, unchanged from main and all pre-existing bidirectional-relation warnings (#79). No ADR-008 or R-007 warning.
./build.sh build	Rendered. Both artifacts appear in their chapters, R-007 in the risk register as High / Medium / Medium; impact, traceability and attributes fragments generate; derived_from renders.
./build.sh test	39/39 pass.
./build.sh check-adapters	Generated agent adapters are current (no skill changed).
xrefs	q-arch-006, adr-005-engine-independent-skills and r-007-gate-results-lack-independence all resolve; R-007 and ADR-007 keep distinct anchors.

Generated fragments are not committed, per ADR-002.

Convergence Check

Authoritative result: converged, on head 6f5824a, from a context that did
not author the change. No findings, no blockers. Three candidates were weighed
and reported as observations instead, because a reader of the delivery record
gets nothing wrong from them.

The run-by-run record lives in
https://github.com/docs-as-code-toolkit/architecture-knowledge-toolkit/pull/88#issuecomment-5541512602[a comment on this pull request],
not here, and it is the single place that counts them. This body is rewritten on
every re-run, so a tally kept in both drifts — and a tally of runs that are still
happening falsifies itself, which is the defect 6f5824a removed from R-007
and this section had kept.

The asymmetry, which no further run changes: every check run from the context
that wrote the artifacts reported converged. Runs from a context that had not
authored the change repeatedly reported not converged, and every finding they
raised survived inspection. The first defect of all was found by neither — a
human reading the ADR.

What the independent runs caught, in order: the ADR's lifecycle flip and the
closure of its last open question recorded only in the diff; TD-002 and
Q-ARCH-006 contradicting the acceptance; the fixes for those going unrecorded in
turn; DOC-09000 calling the accepted ADR "proposed"; R-007 asserting a count
of independent runs that its own cited evidence refuted; and this section doing
the same. Every artifact finding is fixed in f1f8c03, 26edc6d and 6f5824a
and recorded in #86. The record findings needed no commit.

Questions 1 through 6 are established on the branch. Behaviour is not
applicable — nothing under skills/, scripts/, features/, test/,
metamodel/, templates/ or adapters/ is in the diff, so no scenario could
contradict this change. Architecture impact, decisions and traceability passed;
implementation and verification passed deterministically.

Because origin/main advanced four commits (#89) after the merge base, the
figures below are from a simulated post-rebase tree, not the branch alone:
the diff applies clean, 79 artifacts / 0 errors / 38 warnings against a same-tool
main baseline of 77 / 0 / 38 with a byte-identical warning set, 41/41 JS
tests plus Ruby 29 runs / 144 assertions and CLI 4 runs / 13 assertions with no
failures, adapters current, 438 unique link targets over 720 occurrences with
none broken, and the derived-view delta confined to the artifacts the new
relations touch. Pugh sums re-added by hand: 2 / 0 / 1.

Two pre-existing defects surfaced along the way are filed rather than carried:
#94 (derived_from_description leaks into artifacts that declare no
provenance — the same blocks leak on this branch and on main, in equal number,
so this change does not enlarge it; the exact figure is recorded in #94 rather
than counted here) and #95 (the risk register is ID-ordered while
chapter 11 promises priority ordering).

Execution provenance. The asymmetry above is the failure mode R-007
records, observed on the change that introduces it. It is why the risk keeps
Likelihood: High, and why #87 proposes to make independence a declared
property rather than an arrangement.

Not in this change

No operational rule from this decision was added to AGENTS.md or to any skill.
If one falls out of the accepted decision, it belongs in
general-semantic-contracts.md once, with the ADR linking to it.

ADR-008 and its four relations are accepted. R-007 stays status: proposed /
reviewed: false: its rating is still under analysis, and an accepted decision
may introduce a risk that is not yet accepted.

Two findings from this work are filed rather than folded in: #91 presents the
position outside the architecture documentation, and #92 fixes a contradiction
between risk-writing-guide.md and relation-rules.md that would walk an author
into a forbidden reciprocal relation.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UfBhsTXm166jSfiUdTDSv3

[dieterbaier]

Convergence Check runs on this branch — record

Posted as a comment rather than in the pull request body, because the body is
rewritten on every re-run and earlier revisions are not retrievable. R-007
cites this comment as evidence, so it needs to stay readable after the body
changes again.

#	Run	Head	Result	What it caught
1	authoring context	d061619	converged	—
2	authoring context	63fc000	converged	—
3	authoring context	d72edac	converged	—
4	fresh context	d72edac	not converged	the ADR's lifecycle flip to accepted and the closure of its last open question were recorded only in the diff and this body, against an explicit acceptance criterion in #86; TD-002 and Q-ARCH-006 contradicted the acceptance
5	fresh context	f1f8c03	not converged	the fixes for run 4's findings were themselves unrecorded in #86 and in this body; DOC-09000's relation rationale called the accepted ADR "proposed"
6	fresh context, authoritative	3b9205a	not converged	the delivery record did not cover the head commit; plus two pre-existing defects it surfaced, now #94 and #95
7	fresh context, authoritative	3b9205a	not converged	R-007 claimed "two" independent runs while this record already showed three — the artifact contradicted its own cited evidence
8	fresh context, authoritative	6f5824a	not converged	the pull request body still carried the tally defect that 6f5824a had just removed from R-007 — "Six runs" over an eight-row table, and "three" independent runs where this record showed four
9	fresh context, authoritative	6f5824a	not converged	the body counted the pre-existing #94 leak as ten rendered blocks; it is eleven
10	fresh context, authoritative	6f5824a	converged	no findings; integration may proceed

Runs 1–3 were produced by the context that wrote the artifacts. Runs 4 onward
were produced by a context that had not seen the change and was given the
branch, the issue and the canonical skill, with no summary of the work and no
knowledge of the earlier runs.

Every finding from runs 4 and 5 is fixed in f1f8c03 and 26edc6d and recorded
in #86. No finding from any independent run was disputed on inspection.

What run 6 added

Run 6 was the authoritative pre-integration run. Its one blocker was pending
and specific to this change: commit 3b9205a — which replaced R-007's
unretrievable evidence with the two permanent comment links it now cites — was
itself recorded nowhere. This comment and the pull request body now cover it.

It also established the validator baseline the way runs 1–3 had only asserted
it: git archive origin/main into a scratch tree, then
ruby scripts/validate-metamodel.rb → 77 artifacts, 0 errors, 38 warnings,
against 79 artifacts, 0 errors, 38 warnings on the branch. Same warning set, two
more artifacts. It also counted 438 internal links in the rendered HTML with
none broken.

And it surfaced two defects that predate this branch, both now filed rather than
carried:

• derived_from_description leaks into artifacts that declare no provenance #94 — derived_from_description is set by a generated attributes fragment
  and never unset, so artifacts with no provenance of their own render someone
  else's. Confirmed in the rendered output on both this branch and main.
• Risk register is ID-ordered while chapter 11 promises priority ordering #95 — chapter 11 says risks are ordered by derived qualitative priority;
  the generated register is ID-ordered, and a Low sits above two Medium.

Run 6 also corrected one claim made in this pull request: the stale "proposed
ADR detail page" rationale fixed in 26edc6d reached the generated fragment but
not the rendered documentation, because that fragment is included nowhere. The
fix stands; its stated reach was larger than the evidence supports.

What run 7 added

Run 7 found R-007 asserting a count of independent runs that this very comment
already contradicted — three recorded against "two" claimed — on the commit whose
stated purpose was to make that evidence checkable. A tally is the wrong form for
evidence that is still accumulating: every further run falsified it again. Fixed
in 6f5824a, which states the asymmetry instead of counting it.

Run 7 also verified the change against a simulated post-rebase tree rather than
only the branch: origin/main plus the branch diff applies clean, 79 artifacts,
0 errors, 38 warnings, Ruby and JS suites green, adapters current. And it
diffed a freshly generated origin/main tree against the branch to confirm the
derived-view delta is confined to the artifacts the new relations touch.

What run 8 added

Run 8 confirmed every artifact question on the head commit and failed only on the
delivery record: the fix committed as 6f5824a had been applied to R-007 and
not to the pull request body, which went on counting runs that were still
happening. The body no longer counts them; this comment is now the only place
that does, which is the point of keeping the record here.

Run 8 also re-established question 6 against a simulated post-rebase tree,
because origin/main had advanced four commits (#89) since the merge base: the
diff applies clean and the post-rebase suite is 41/41 JS tests rather than the
39/39 the branch alone reports.

What run 9 added

Run 9 passed every artifact question and failed on one number: this pull
request's body said "ten wrongly rendered blocks" for the pre-existing leak
filed as #94. It is eleven — QS-001…QS-005 and R-001…R-006 — and the
run derived that from the rendered output. Every other figure in the body had
been derived; that one had not.

The body no longer carries the number at all. The exact figure now lives in #94,
where the defect does, rather than in delivery prose that goes stale. Run 9 also
confirmed deterministically that the count is equal on both trees, which is the
load-bearing claim: this change does not enlarge the defect.

Three runs in a row have now failed on a count kept in prose — R-007's "two"
independent runs, the body's "Six runs", and this. Each was fixed by removing
the number rather than correcting it.

Run 10 — the authoritative result

Converged, on head 6f5824a. No findings, no blockers of either kind.

Three candidates were weighed and reported as observations rather than findings,
because a reader of this record gets nothing wrong from them: a loose "questions
1 through 6" range in the pull request body that the next sentence corrects,
#86's acceptance-criteria checkboxes left unchecked where the convention is to
record outcomes in comments, and R-007's - in the register's Mitigation column,
which R-003 shows too.

Run 10 established question 6 on both the branch and a simulated post-rebase
tree, and confirmed every checkable number in this pull request against the
repository — including the #94 leak equality it had corrected one run earlier:
11 leaked blocks on the post-rebase tree and 11 on main, so the change does not
enlarge the defect.

Nothing it checked contradicted the repository.

Earlier still

The first defect on this branch was found by neither kind of run: a human
reading the ADR spotted that its rejected option described a position role-based
agent platforms do not necessarily hold. That correction is recorded at
#86 (comment)
and fixed in 94c1ee2.