From d061619b831d6ab29eafc0c0570e402a3071e985 Mon Sep 17 00:00:00 2001 From: Dieter Baier Date: Fri, 4 Sep 2026 11:58:56 +0200 Subject: [PATCH 1/9] issue_86: Record the skill decomposition boundary The toolkit cuts skills by lifecycle capability and never by agent persona, but that position was embodied everywhere and recorded nowhere. It had to be argued from first principles every time the toolkit met a role-based agent platform. ADR-008 records the decision, compares it against a persona cut and a per-role-copies variant, and keeps the strengths of the rejected options visible: a persona cut genuinely wins on organisational mappability and on independence of verification. Placing roles in an orchestration layer above the toolkit keeps those strengths available without giving a role separate process truth. It also names the cost the decision creates: a capability cut cannot express who executes a skill, so the same agent can implement a change and run its own authoritative gate. That gap is tracked separately. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01UfBhsTXm166jSfiUdTDSv3 --- .../adr-008-skill-decomposition-boundary.adoc | 196 ++++++++++++++++++ .../doc-09000-architecture-decisions.adoc | 6 + 2 files changed, 202 insertions(+) create mode 100644 src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc diff --git a/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc b/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc new file mode 100644 index 0000000..e3b2887 --- /dev/null +++ b/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc @@ -0,0 +1,196 @@ +--- +id: ADR-008-skill-decomposition-boundary +type: ADR +title: Skill Decomposition and Agent Role Boundary +status: proposed +owner: architecture +created: '2026-09-04' +reviewed: false +summary: Proposed decision to cut canonical skills by lifecycle capability rather than by agent persona, and to place role-based agents in an orchestration layer above the toolkit. +derived_from: +- type: conversation + description: Comparison of this toolkit with a role-based software factory agent architecture, which asked whether skills should be cut by role instead of by lifecycle capability. + uri: https://github.com/docs-as-code-toolkit/architecture-knowledge-toolkit/issues/86 +tags: +- decision +- skills +relations: +- type: refines + target: ADR-005-engine-independent-skills + status: proposed + rationale: This decision makes the runtime boundary from ADR-005 more specific by placing the agent persona on the runtime side of it. + evidence: src/docs/arc42/09-architecture-decisions/adr-005-engine-independent-skills.adoc + reviewed: false +- type: addresses + target: QS-005-adapter-boundary + status: proposed + rationale: Keeping personas out of canonical skills is one case of keeping runtime assumptions out of them. + evidence: src/docs/arc42/10-quality-requirements/qs-005-adapter-boundary.adoc + reviewed: false +- type: mitigates + target: R-006-unclear-adapter-boundaries + status: proposed + rationale: Naming the agent persona as a runtime concern removes one concrete case of boundary ambiguity. + evidence: src/docs/arc42/11-risks-and-technical-debt/r-006-unclear-adapter-boundaries.adoc + reviewed: false +metadata_version: '1.0' +--- +[[adr-008-skill-decomposition-boundary]] +== ADR-008: Skill Decomposition and Agent Role Boundary + +=== Status + +Proposed. + +This ADR is AI-assisted and must not be treated as accepted architecture truth +until reviewed and accepted by the accountable owner. + +=== Decision + +We propose to cut canonical skills by lifecycle capability and verifiable +outcome, never by agent persona. Role-based agents such as planner, coder, or +reviewer may exist as an orchestration layer above the toolkit and consume the +same canonical skills. They do not own a copy of the lifecycle. + +=== Context + +The canonical skills are named after work with a checkable result: +`architecture-impact`, `bdd-specification`, `implement-issue-workflow`, +`pr-review`, `convergence-check`. None of them is named after a worker. The +same agent combines whichever of them a task needs, and the delegation between +them is explicit: `implement-issue-workflow` and `pr-review` both reference the +Convergence Check rather than restating it, and `features/skill-wiring.feature` +fails when a delegated rule is copied back into a caller. + +That machinery assumes exactly one canonical owner per rule. A persona cut +multiplies owners: planner, coder and reviewer each need architecture, contract +and lifecycle knowledge, so each acquires a version of it. + +The alternative is widespread. Role-based agent platforms — a planner, a coder, +a reviewer, each with its own skill stack — organise agents along a human +reporting structure. The question of which cut this toolkit uses recurs whenever +it meets such a platform, and the answer has so far been reconstructed each +time rather than recorded. + +xref:q-arch-006[Q-ARCH-006] asks which workflow details belong under +`adapters/` rather than in engine-independent skills. This decision answers one +instance of that question: the agent persona is a runtime concern. + +=== Decision Drivers + +* Keep lifecycle knowledge in exactly one place, so a lifecycle change is one + edit rather than one edit per role. +* Let a single agent combine skills for whatever the task actually needs. +* Keep the toolkit consumable by role-based agent platforms instead of + competing with them. +* Do not encode an organisation chart into reusable architecture guidance. + +=== Considered Options + +==== Option 1: Capability-cut skills, roles as orchestration above + +Skills describe work with a verifiable outcome. Role-based agents are a runtime +choice made above the toolkit; they select and execute canonical skills without +holding process knowledge of their own. + +==== Option 2: Persona-cut skill sets + +One skill stack per role. Each role's guidance is self-contained and maps +directly onto a team, a permission set, and an audit trail. + +==== Option 3: Capability-cut skills with per-role copies of shared rules + +Skills stay capability-shaped, but each role carries its own copy of the process +rules it needs, so a role can run without resolving the toolkit. + +=== Pugh Matrix + +[.pugh-matrix] +[cols="2,1,1,1", options="header"] +|=== +| Criterion | Capability cut | Persona cut | Per-role copies +| Single source of process truth | +1 | -1 | -1 +| Skill reuse across tasks | +1 | -1 | 0 +| Independence of verification | -1 | +1 | +1 +| Organisational mappability | 0 | +1 | +1 +| Context cost per task | +1 | 0 | 0 +s| Sum s| 2 s| 0 s| 1 +|=== + +The persona cut genuinely wins two criteria. It maps onto a team, a permission +set and an audit trail, and a fresh reviewer agent cannot inherit the +implementer's assumptions. Those strengths are real and are the reason this ADR +places roles above the toolkit rather than forbidding them. + +=== Consequences + +==== Positive + +* Lifecycle knowledge lives once. A change to the lifecycle is one edit, not one + edit per role. +* An agent combines skills as the task requires, without an artificial + responsibility boundary between planning, implementing and reviewing. +* Role-based agent platforms can consume the toolkit instead of forking its + process knowledge. +* The existing wiring checks stay meaningful, because each rule keeps exactly + one owner to delegate to. + +==== Negative + +* Independence of verification, which a persona cut provides for free, is not + expressible by a capability cut. Today the same agent can implement a change + and run the authoritative Convergence Check on it. +* Ownership, permissions and audit do not map onto skills. A consuming + organisation has to establish that mapping in its own orchestration layer. +* Skill selection remains a semantic decision at the point of use. Explicit + wiring exists at the gate moments, but the toolkit does not enforce routing. + +==== Neutral or Follow-Up + +* The independence gap is tracked as + https://github.com/docs-as-code-toolkit/architecture-knowledge-toolkit/issues/87[issue 87], + which proposes independence as a declared execution property of gate skills + rather than as a new role. +* Roles remain permitted above the toolkit. Nothing here forbids planner, coder + or reviewer agents; it forbids them owning separate process truth. + +=== Impact + +include::generated/adr-008-skill-decomposition-boundary-impact.adoc[leveloffset=+2] + +=== Traceability + +include::generated/adr-008-skill-decomposition-boundary-attributes.adoc[] + +ifdef::derived_from_description[] +==== Derived from +{derived_from_description} +endif::[] + +include::generated/adr-008-skill-decomposition-boundary-traceability.adoc[leveloffset=+2] + +=== Assumptions + +* Every step the lifecycle needs can be expressed as work with a verifiable + outcome, without naming a worker. +* Role-based platforms are able to consume engine-independent skills rather than + requiring skills shaped for their own personas. +* Independence of verification can be expressed as a declared execution property + rather than as a role. + +=== Open Questions + +* Should the independence gap recorded under `Negative` become a Risk artifact, + or is the follow-up issue a sufficient record? +* Where does an orchestration layer bind roles to skills: in `adapters/`, in the + consuming project, or entirely outside the toolkit? + +=== Review Notes + +Confirm before marking this ADR reviewed or accepted: + +* whether this decision refines xref:adr-005-engine-independent-skills[] or + stands beside it — it is recorded here as a proposed `refines` relation; +* whether the independence consequence warrants its own Risk artifact; +* that no operational rule from this decision has been duplicated into + `AGENTS.md` or into the canonical skills. diff --git a/src/docs/arc42/doc-09000-architecture-decisions.adoc b/src/docs/arc42/doc-09000-architecture-decisions.adoc index 5e90cd4..ffe2953 100644 --- a/src/docs/arc42/doc-09000-architecture-decisions.adoc +++ b/src/docs/arc42/doc-09000-architecture-decisions.adoc @@ -66,6 +66,12 @@ relations: rationale: The chapter links to this proposed ADR detail page. evidence: src/docs/arc42/doc-09000-architecture-decisions.adoc reviewed: false +- type: documents + target: ADR-008-skill-decomposition-boundary + status: proposed + rationale: The chapter links to this proposed ADR detail page. + evidence: src/docs/arc42/doc-09000-architecture-decisions.adoc + reviewed: false metadata_version: '1.0' --- = [[architecture-decisions]]Architecture Decisions From 94c1ee2a38215679384cd1b34bb3963718b5f031 Mon Sep 17 00:00:00 2001 From: Dieter Baier Date: Fri, 4 Sep 2026 12:17:15 +0200 Subject: [PATCH 2/9] issue_86: Separate the cut from the agent decomposition The first draft treated "role-based" as one position. It is three: which axis the process knowledge is cut on, which skills an executing agent is allocated, and how many agents execute a change. A platform that decomposes its agents by role does not thereby cut its skills by role, and the draft's rejected option described only the second. Left as it was, the ADR argued against a position that role-based agent platforms do not necessarily hold, which would have made it easy to dismiss by exactly the readers it has to convince. The decision is unchanged and now says what it does not decide. The Pugh commentary attributes each criterion the persona cut wins to the axis it actually comes from: organisational mappability follows from the cut, independence of verification from the agent decomposition. Separating allocation also surfaces an obligation the decision creates: an orchestration layer that allocates skills per role has to keep each allocation closed under skill-to-skill delegation, or the mandatory gate wiring breaks silently inside a role's context. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01UfBhsTXm166jSfiUdTDSv3 --- .../adr-008-skill-decomposition-boundary.adoc | 78 +++++++++++++++---- 1 file changed, 62 insertions(+), 16 deletions(-) diff --git a/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc b/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc index e3b2887..c4ac3c2 100644 --- a/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc +++ b/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc @@ -52,6 +52,8 @@ outcome, never by agent persona. Role-based agents such as planner, coder, or reviewer 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. It does not decide how many agents execute a change. + === Context The canonical skills are named after work with a checkable result: @@ -62,15 +64,40 @@ them is explicit: `implement-issue-workflow` and `pr-review` both reference the Convergence Check rather than restating it, and `features/skill-wiring.feature` fails when a delegated rule is copied back into a caller. -That machinery assumes exactly one canonical owner per rule. A persona cut -multiplies owners: planner, coder and reviewer each need architecture, contract -and lifecycle knowledge, so each acquires a version of it. +Role-based agent platforms are the widespread alternative, and comparing them +with this toolkit is easy to get wrong, because three separate questions are +usually asked as one: + +[cols="1,3", options="header"] +|=== +| Question | What it decides + +| Cut +| On which axis process knowledge is decomposed into units: capability or persona. + +| Allocation +| Which units an executing agent receives: whatever the task needs, or a fixed role-specific subset. -The alternative is widespread. Role-based agent platforms — a planner, a coder, -a reviewer, each with its own skill stack — organise agents along a human -reporting structure. The question of which cut this toolkit uses recurs whenever -it meets such a platform, and the answer has so far been reconstructed each -time rather than recorded. +| Agent decomposition +| How many agents execute one change, with which context and which permissions. +|=== + +Only the first is decided here. Agent decomposition stays free: running a +planner, a coder and a reviewer as separate agents is a legitimate runtime +choice, and this decision neither requires nor forbids it. Allocation belongs to +whatever orchestrates those agents, subject to one constraint recorded under +`Consequences`. + +The separation matters because a platform that decomposes its *agents* by role +does not thereby cut its *skills* by role. Both are called role-based, and only +the second conflicts with this decision. The question of which cut this toolkit +uses recurs whenever it meets such a platform, and the answer has so far been +reconstructed each time rather than recorded. + +The cut is what the existing machinery depends on: it assumes exactly one +canonical owner per rule. A persona cut multiplies owners, because planner, +coder and reviewer each need architecture, contract and lifecycle knowledge, so +each acquires a version of it. xref:q-arch-006[Q-ARCH-006] asks which workflow details belong under `adapters/` rather than in engine-independent skills. This decision answers one @@ -87,18 +114,22 @@ instance of that question: the agent persona is a runtime concern. === Considered Options -==== Option 1: Capability-cut skills, roles as orchestration above +==== Option 1: Skills cut by capability, roles as orchestration above Skills describe work with a verifiable outcome. Role-based agents are a runtime choice made above the toolkit; they select and execute canonical skills without holding process knowledge of their own. -==== Option 2: Persona-cut skill sets +==== Option 2: Skills cut by persona One skill stack per role. Each role's guidance is self-contained and maps directly onto a team, a permission set, and an audit trail. -==== Option 3: Capability-cut skills with per-role copies of shared rules +This is a position on the cut, not on agent decomposition. A platform can run +role-based agents without cutting its skills this way; such a platform sits +inside Option 1 and is not the alternative rejected here. + +==== Option 3: Skills cut by capability, with per-role copies of shared rules Skills stay capability-shaped, but each role carries its own copy of the process rules it needs, so a role can run without resolving the toolkit. @@ -117,10 +148,13 @@ rules it needs, so a role can run without resolving the toolkit. s| Sum s| 2 s| 0 s| 1 |=== -The persona cut genuinely wins two criteria. It maps onto a team, a permission -set and an audit trail, and a fresh reviewer agent cannot inherit the -implementer's assumptions. Those strengths are real and are the reason this ADR -places roles above the toolkit rather than forbidding them. +The persona cut genuinely wins two criteria, and it wins them for different +reasons. Organisational mappability follows from the cut itself: a +persona-shaped skill set maps onto a team, a permission set and an audit trail. +Independence of verification does not — it follows from agent decomposition, +which a persona cut merely tends to arrive with. A capability cut can have it +too, but only by declaring it. Both strengths are real, and they are why this +ADR places roles above the toolkit rather than forbidding them. === Consequences @@ -144,6 +178,10 @@ places roles above the toolkit rather than forbidding them. organisation has to establish that mapping in its own orchestration layer. * Skill selection remains a semantic decision at the point of use. Explicit wiring exists at the gate moments, but the toolkit does not enforce routing. +* An orchestration layer that allocates skills per role has to keep each + allocation closed under skill-to-skill delegation. A role holding + `implement-issue-workflow` also needs everything that skill mandatorily + references, or the gate wiring breaks silently inside that role's context. ==== Neutral or Follow-Up @@ -153,6 +191,10 @@ places roles above the toolkit rather than forbidding them. rather than as a new role. * Roles remain permitted above the toolkit. Nothing here forbids planner, coder or reviewer agents; it forbids them owning separate process truth. +* Whether the toolkit should verify allocation closure is undecided. + `features/skill-wiring.feature` already resolves the skill-to-skill reference + graph, so the data exists; nothing reads it from an allocation's point of + view. === Impact @@ -184,6 +226,8 @@ include::generated/adr-008-skill-decomposition-boundary-traceability.adoc[levelo or is the follow-up issue a sufficient record? * Where does an orchestration layer bind roles to skills: in `adapters/`, in the consuming project, or entirely outside the toolkit? +* Should the toolkit publish each skill's delegation closure so an orchestration + layer can allocate against it, rather than only stating the requirement? === Review Notes @@ -193,4 +237,6 @@ Confirm before marking this ADR reviewed or accepted: stands beside it — it is recorded here as a proposed `refines` relation; * whether the independence consequence warrants its own Risk artifact; * that no operational rule from this decision has been duplicated into - `AGENTS.md` or into the canonical skills. + `AGENTS.md` or into the canonical skills; +* that the separation under `Context` between cut, allocation and agent + decomposition matches how role-based agent platforms describe themselves. From 63fc000dbc5bae07903b3faf6fc663feb3b6a583 Mon Sep 17 00:00:00 2001 From: Dieter Baier Date: Fri, 4 Sep 2026 13:18:44 +0200 Subject: [PATCH 3/9] issue_86: Record the independence gap as a risk Owner review of ADR-008 settled its three open questions. The missing independence of gate verification is a risk to manage, not a reason to separate roles: in a cross-functional team it is exactly the exposure a team accepts and watches. R-007 records it, refines R-001 for the case of gate results, and carries the evidence already on this branch, where the provisional check reported converged and a human reader found the defect. The binding between roles and skills stays outside this repository. The ADR now shows what such a binding can look like and marks it as not a toolkit format. The illustration allocates an entry skill rather than a list of skills, so the allocation is closed under delegation by construction. That also settles whether the toolkit should publish a machine-readable closure: it does not need to. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01UfBhsTXm166jSfiUdTDSv3 --- .../adr-008-skill-decomposition-boundary.adoc | 64 +++++++--- .../r-007-gate-results-lack-independence.adoc | 114 ++++++++++++++++++ .../doc-11000-risks-and-technical-debt.adoc | 6 + 3 files changed, 165 insertions(+), 19 deletions(-) create mode 100644 src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc diff --git a/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc b/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc index c4ac3c2..4ba5321 100644 --- a/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc +++ b/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc @@ -27,6 +27,12 @@ relations: rationale: Keeping personas out of canonical skills is one case of keeping runtime assumptions out of them. evidence: src/docs/arc42/10-quality-requirements/qs-005-adapter-boundary.adoc reviewed: false +- type: introduces_risk + target: R-007-gate-results-lack-independence + status: proposed + rationale: A capability cut cannot express who executes a gate, so the implementing context can produce its own authoritative result. + evidence: src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc + reviewed: false - type: mitigates target: R-006-unclear-adapter-boundaries status: proposed @@ -52,7 +58,28 @@ outcome, never by agent persona. Role-based agents such as planner, coder, or reviewer 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. It does not decide how many agents execute a change. +This decides the cut. It does not decide how many agents execute a change, and +the binding between roles and skills stays outside this repository. A consuming +platform owns it, in whatever form fits its runtime. + +The illustration below is what such a binding can look like. It is not a toolkit +format, and nothing here reads it: + +[source,yaml] +---- +# Owned by the orchestration platform, not by this toolkit. +roles: + implementer: + entry: implement-issue-workflow + reviewer: + entry: pr-review + execution: fresh # started without the implementation context +---- + +A role is given an *entry* skill rather than a list of skills. Everything that +skill mandatorily delegates to comes with it, so the allocation is closed by +construction and cannot fall behind a change to the delegation. Role names, +their number, and the mechanism that enforces `execution` are the platform's. === Context @@ -173,15 +200,17 @@ ADR places roles above the toolkit rather than forbidding them. * Independence of verification, which a persona cut provides for free, is not expressible by a capability cut. Today the same agent can implement a change - and run the authoritative Convergence Check on it. + and run the authoritative Convergence Check on it. This is tracked as + xref:r-007-gate-results-lack-independence[]. * Ownership, permissions and audit do not map onto skills. A consuming organisation has to establish that mapping in its own orchestration layer. * Skill selection remains a semantic decision at the point of use. Explicit wiring exists at the gate moments, but the toolkit does not enforce routing. -* An orchestration layer that allocates skills per role has to keep each - allocation closed under skill-to-skill delegation. A role holding - `implement-issue-workflow` also needs everything that skill mandatorily - references, or the gate wiring breaks silently inside that role's context. +* An orchestration layer that allocates a fixed *list* of skills per role has to + maintain closure under skill-to-skill delegation itself, and a list that falls + behind a delegation change breaks the gate wiring silently inside that role's + context. Allocating an entry skill avoids the obligation; enumerating one + accepts it. ==== Neutral or Follow-Up @@ -191,10 +220,11 @@ ADR places roles above the toolkit rather than forbidding them. rather than as a new role. * Roles remain permitted above the toolkit. Nothing here forbids planner, coder or reviewer agents; it forbids them owning separate process truth. -* Whether the toolkit should verify allocation closure is undecided. - `features/skill-wiring.feature` already resolves the skill-to-skill reference - graph, so the data exists; nothing reads it from an allocation's point of - view. +* The toolkit publishes no binding mechanism and no machine-readable delegation + closure. Stating the requirement is enough, because an allocation by entry + skill inherits the closure anyway. `features/skill-wiring.feature` still + resolves that reference graph for the toolkit's own consistency, not for + consumers to allocate against. === Impact @@ -222,20 +252,16 @@ include::generated/adr-008-skill-decomposition-boundary-traceability.adoc[levelo === Open Questions -* Should the independence gap recorded under `Negative` become a Risk artifact, - or is the follow-up issue a sufficient record? -* Where does an orchestration layer bind roles to skills: in `adapters/`, in the - consuming project, or entirely outside the toolkit? -* Should the toolkit publish each skill's delegation closure so an orchestration - layer can allocate against it, rather than only stating the requirement? +* Should the illustration under `Decision` grow into a maintained example, or + does an orchestration layer need nothing further from this repository than the + skill names it already reads? === Review Notes Confirm before marking this ADR reviewed or accepted: -* whether this decision refines xref:adr-005-engine-independent-skills[] or - stands beside it — it is recorded here as a proposed `refines` relation; -* whether the independence consequence warrants its own Risk artifact; +* the assessment recorded in xref:r-007-gate-results-lack-independence[], which + this decision introduces; * that no operational rule from this decision has been duplicated into `AGENTS.md` or into the canonical skills; * that the separation under `Context` between cut, allocation and agent diff --git a/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc b/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc new file mode 100644 index 0000000..d4e9303 --- /dev/null +++ b/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc @@ -0,0 +1,114 @@ +--- +id: R-007-gate-results-lack-independence +type: Risk +title: Gate Results Lack Independent Verification +status: proposed +owner: architecture +created: '2026-09-04' +reviewed: false +summary: Proposed risk that a Convergence Check result produced by the context that made the change reads as independent verification without being one. +derived_from: +- type: conversation + description: Owner review of ADR-008, which decided to record the missing independence of gate verification as a risk to be managed rather than to resolve it by separating roles. + uri: https://github.com/docs-as-code-toolkit/architecture-knowledge-toolkit/pull/88 +tags: +- risk +- verification +relations: +- type: refines + target: R-001-ai-suggestions-as-truth + status: proposed + rationale: This risk narrows the general concern to gate results, where the mitigation is execution independence rather than a lifecycle status marker. + evidence: src/docs/arc42/11-risks-and-technical-debt/r-001-ai-suggestions-as-truth.adoc + reviewed: false +- type: affects + target: QS-004-ai-suggestion-reviewability + status: proposed + rationale: A self-produced gate result is AI-suggested content that a reviewer cannot distinguish from independent verification. + evidence: src/docs/arc42/10-quality-requirements/qs-004-ai-suggestion-reviewability.adoc + reviewed: false +metadata_version: '1.0' +--- +[[r-007-gate-results-lack-independence]] +== R-007: Gate Results Lack Independent Verification + +=== Status + +Proposed. + +This risk is AI-assisted. It identifies a concern for review and does not +decide risk acceptance. + +=== Risk Statement + +Because a cross-functional agent implements a change and then runs the +Convergence Check on it from the same context, a gate result may be produced by +the assumptions it is supposed to test, leading to a *converged* result that +reads as verification while no independent check took place. + +=== Assessment + +[cols="1,3", options="header"] +|=== +| Field | Value +| Likelihood | High. +| Impact | Medium. +| Priority | Medium. +| Timeframe | Near-term. +| Confidence | Medium. +|=== + +Likelihood is high because it is the default arrangement, not an exception: a +single agent that carries a change through the workflow ends at the gate with +the whole implementation dialog still in context. Impact is medium rather than +high because the result is not usually wrong, it is weaker than it reads, and +human review at the pull request still stands behind it. The rating assumes that +compensating control keeps working. + +This has already been observed. On the branch that introduced +xref:adr-008-skill-decomposition-boundary[], the provisional check reported +*converged*, and the framing defect corrected in the following commit was found +by a human reading the ADR rather than by the gate. + +=== Mitigation Options + +* Declare independence as an execution property of the gate skills, so a run + states which context produced it. +* Report execution provenance with every result, so a self-produced result is + visible as one instead of silently equivalent to an independent run. +* Run the authoritative gate from a fresh context wherever the runtime allows + it, without requiring a role-based team structure to obtain it. +* Keep human review at the pull request as the compensating control for as long + as no execution layer can enforce independence. + +=== Decision or Acceptance + +The risk remains under analysis until the accountable owner confirms the +assessment and mitigation path. + +=== Impact + +include::generated/r-007-gate-results-lack-independence-impact.adoc[leveloffset=+2] + +=== Traceability + +include::generated/r-007-gate-results-lack-independence-attributes.adoc[] + +ifdef::derived_from_description[] +==== Derived from +{derived_from_description} +endif::[] + +include::generated/r-007-gate-results-lack-independence-traceability.adoc[leveloffset=+2] + +=== Open Questions + +* What evidences that a gate run was independent, given that this repository has + no execution layer for prose contracts and can require the claim but not + verify it? + +=== Review Notes + +Confirm the likelihood and impact rating, and whether reporting execution +provenance is a sufficient control while independence cannot be enforced, +before marking this risk reviewed. diff --git a/src/docs/arc42/doc-11000-risks-and-technical-debt.adoc b/src/docs/arc42/doc-11000-risks-and-technical-debt.adoc index 49664ea..9168d03 100644 --- a/src/docs/arc42/doc-11000-risks-and-technical-debt.adoc +++ b/src/docs/arc42/doc-11000-risks-and-technical-debt.adoc @@ -66,6 +66,12 @@ relations: rationale: The chapter links to this proposed risk detail page. evidence: src/docs/arc42/doc-11000-risks-and-technical-debt.adoc reviewed: false +- type: documents + target: R-007-gate-results-lack-independence + status: proposed + rationale: The chapter links to this proposed risk detail page. + evidence: src/docs/arc42/doc-11000-risks-and-technical-debt.adoc + reviewed: false metadata_version: '1.0' --- = [[risks-and-technical-debt]]Risks And Technical Debt From 73f1972692aa3229a3902f0ebc4a4d7237c0a12b Mon Sep 17 00:00:00 2001 From: Dieter Baier Date: Fri, 4 Sep 2026 13:34:10 +0200 Subject: [PATCH 4/9] issue_86: Accept ADR-008 and split R-007 mitigations The accountable owner reviewed the decision and accepted it. 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 are true here. The summary said "Proposed decision", which would have contradicted the lifecycle state in the ADR index. Only the refines relation to ADR-005 was confirmed by name, so only it moves to reviewed. The other three stay proposed: their targets are proposed artifacts, and the review accepted the decision rather than those impact claims. The illustration stays an illustration. A maintained example is not needed for the decision to hold, which closes the last open question. R-007 keeps likelihood high and now says why the rating is not lowered yet: fresh execution is the control that would move it, but nothing requires it today, so lowering it now would record an intention where a control belongs. The mitigation options are split by the dimension they move -- fresh execution prevents the event, execution provenance keeps a self-produced run from reading as an independent one. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01UfBhsTXm166jSfiUdTDSv3 --- .../adr-008-skill-decomposition-boundary.adoc | 46 ++++++++++--------- .../r-007-gate-results-lack-independence.adoc | 22 +++++++-- 2 files changed, 44 insertions(+), 24 deletions(-) diff --git a/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc b/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc index 4ba5321..3bc2047 100644 --- a/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc +++ b/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc @@ -2,11 +2,11 @@ id: ADR-008-skill-decomposition-boundary type: ADR title: Skill Decomposition and Agent Role Boundary -status: proposed +status: accepted owner: architecture created: '2026-09-04' -reviewed: false -summary: Proposed decision to cut canonical skills by lifecycle capability rather than by agent persona, and to place role-based agents in an orchestration layer above the toolkit. +reviewed: true +summary: Accepted decision to cut canonical skills by lifecycle capability rather than by agent persona, and to place role-based agents in an orchestration layer above the toolkit. derived_from: - type: conversation description: Comparison of this toolkit with a role-based software factory agent architecture, which asked whether skills should be cut by role instead of by lifecycle capability. @@ -17,10 +17,10 @@ tags: relations: - type: refines target: ADR-005-engine-independent-skills - status: proposed + status: reviewed rationale: This decision makes the runtime boundary from ADR-005 more specific by placing the agent persona on the runtime side of it. evidence: src/docs/arc42/09-architecture-decisions/adr-005-engine-independent-skills.adoc - reviewed: false + reviewed: true - type: addresses target: QS-005-adapter-boundary status: proposed @@ -46,15 +46,16 @@ metadata_version: '1.0' === Status -Proposed. +Accepted (derived). -This ADR is AI-assisted and must not be treated as accepted architecture truth -until reviewed and accepted by the accountable owner. +The rationale was AI-drafted and then reviewed and accepted by the accountable +owner. The derived marker records that the drafting was AI-assisted; the +acceptance is human. === Decision -We propose to cut canonical skills by lifecycle capability and verifiable -outcome, never by agent persona. Role-based agents such as planner, coder, or +We cut canonical skills by lifecycle capability and verifiable outcome, never by +agent persona. Role-based agents such as planner, coder, or reviewer may exist as an orchestration layer above the toolkit and consume the same canonical skills. They do not own a copy of the lifecycle. @@ -252,17 +253,20 @@ include::generated/adr-008-skill-decomposition-boundary-traceability.adoc[levelo === Open Questions -* Should the illustration under `Decision` grow into a maintained example, or - does an orchestration layer need nothing further from this repository than the - skill names it already reads? +* None. The illustration under `Decision` stays an illustration: the decision + holds without a maintained example, and an orchestration layer needs nothing + from this repository beyond the skill names it already reads. === Review Notes -Confirm before marking this ADR reviewed or accepted: - -* the assessment recorded in xref:r-007-gate-results-lack-independence[], which - this decision introduces; -* that no operational rule from this decision has been duplicated into - `AGENTS.md` or into the canonical skills; -* that the separation under `Context` between cut, allocation and agent - decomposition matches how role-based agent platforms describe themselves. +Accepted after review of the three questions this decision opened. The `refines` +relation to xref:adr-005-engine-independent-skills[] was confirmed, the +independence consequence was recorded as +xref:r-007-gate-results-lack-independence[], and the role-to-skill binding was +placed outside this repository. + +One assessment remains open elsewhere: the rating in +xref:r-007-gate-results-lack-independence[], which this decision introduces and +which stays under analysis. Its three remaining relations stay `proposed`, +because their targets are proposed artifacts and the review confirmed the +decision rather than those claims. diff --git a/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc b/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc index d4e9303..dd13716 100644 --- a/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc +++ b/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc @@ -65,6 +65,16 @@ high because the result is not usually wrong, it is weaker than it reads, and human review at the pull request still stands behind it. The rating assumes that compensating control keeps working. +Fresh execution of the gate is what would move this rating, and it moves the +likelihood rather than the impact: it prevents the event instead of softening +it. The likelihood is high today because nothing requires it. No skill declares +an execution context, and this repository has no execution layer that could +enforce one, so the default arrangement is the only arrangement. Once a gate +skill declares the requirement and a runtime honours it, the likelihood falls to +the frequency of lapses rather than the frequency of the default. Recording that +reduction before the requirement exists would put an intention where a control +belongs. + This has already been observed. On the branch that introduced xref:adr-008-skill-decomposition-boundary[], the provisional check reported *converged*, and the framing defect corrected in the following commit was found @@ -72,12 +82,18 @@ by a human reading the ADR rather than by the gate. === Mitigation Options +Reducing likelihood, by preventing the self-produced run: + * Declare independence as an execution property of the gate skills, so a run - states which context produced it. -* Report execution provenance with every result, so a self-produced result is - visible as one instead of silently equivalent to an independent run. + states which context it requires. * Run the authoritative gate from a fresh context wherever the runtime allows it, without requiring a role-based team structure to obtain it. + +Reducing impact, by keeping a self-produced run from reading as an independent +one: + +* Report execution provenance with every result, so a self-produced result is + visible as one instead of silently equivalent to an independent run. * Keep human review at the pull request as the compensating control for as long as no execution layer can enforce independence. From d72edac8fa626115cfb4ff1af459628ae5b09747 Mon Sep 17 00:00:00 2001 From: Dieter Baier Date: Fri, 4 Sep 2026 13:43:47 +0200 Subject: [PATCH 5/9] issue_86: Accept the impact relations and link R-007 to #87 The owner accepted the impact claims together with the decision, so all four relations move to accepted. The review note now says what an accepted relation 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. R-007 names the control that would move its likelihood. Issue 87 is where the execution-context declaration is tracked, so the assessment says the rating is expected to be revisited when it closes, and the mitigation that depends on it links there instead of describing work with no home. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01UfBhsTXm166jSfiUdTDSv3 --- .../adr-008-skill-decomposition-boundary.adoc | 22 ++++++++++--------- .../r-007-gate-results-lack-independence.adoc | 16 +++++++++----- 2 files changed, 22 insertions(+), 16 deletions(-) diff --git a/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc b/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc index 3bc2047..459840e 100644 --- a/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc +++ b/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc @@ -17,28 +17,28 @@ tags: relations: - type: refines target: ADR-005-engine-independent-skills - status: reviewed + status: accepted rationale: This decision makes the runtime boundary from ADR-005 more specific by placing the agent persona on the runtime side of it. evidence: src/docs/arc42/09-architecture-decisions/adr-005-engine-independent-skills.adoc reviewed: true - type: addresses target: QS-005-adapter-boundary - status: proposed + status: accepted rationale: Keeping personas out of canonical skills is one case of keeping runtime assumptions out of them. evidence: src/docs/arc42/10-quality-requirements/qs-005-adapter-boundary.adoc - reviewed: false + reviewed: true - type: introduces_risk target: R-007-gate-results-lack-independence - status: proposed + status: accepted rationale: A capability cut cannot express who executes a gate, so the implementing context can produce its own authoritative result. evidence: src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc - reviewed: false + reviewed: true - type: mitigates target: R-006-unclear-adapter-boundaries - status: proposed + status: accepted rationale: Naming the agent persona as a runtime concern removes one concrete case of boundary ambiguity. evidence: src/docs/arc42/11-risks-and-technical-debt/r-006-unclear-adapter-boundaries.adoc - reviewed: false + reviewed: true metadata_version: '1.0' --- [[adr-008-skill-decomposition-boundary]] @@ -265,8 +265,10 @@ independence consequence was recorded as xref:r-007-gate-results-lack-independence[], and the role-to-skill binding was placed outside this repository. +The impact claims recorded as relations were accepted with the decision. Their +targets remain proposed artifacts in their own right; an accepted relation states +that the claim holds, not that the artifact it points at has been accepted. + One assessment remains open elsewhere: the rating in xref:r-007-gate-results-lack-independence[], which this decision introduces and -which stays under analysis. Its three remaining relations stay `proposed`, -because their targets are proposed artifacts and the review confirmed the -decision rather than those claims. +which stays under analysis. diff --git a/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc b/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc index dd13716..25801fb 100644 --- a/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc +++ b/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc @@ -69,11 +69,14 @@ Fresh execution of the gate is what would move this rating, and it moves the likelihood rather than the impact: it prevents the event instead of softening it. The likelihood is high today because nothing requires it. No skill declares an execution context, and this repository has no execution layer that could -enforce one, so the default arrangement is the only arrangement. Once a gate -skill declares the requirement and a runtime honours it, the likelihood falls to -the frequency of lapses rather than the frequency of the default. Recording that -reduction before the requirement exists would put an intention where a control -belongs. +enforce one, so the default arrangement is the only arrangement. The declaration +that would change this is tracked as +https://github.com/docs-as-code-toolkit/architecture-knowledge-toolkit/issues/87[issue 87]; +once a gate skill declares the requirement and a runtime honours it, the +likelihood falls to the frequency of lapses rather than the frequency of the +default. Recording that reduction before the requirement exists would put an +intention where a control belongs, so this rating is expected to be revisited +when that issue closes. This has already been observed. On the branch that introduced xref:adr-008-skill-decomposition-boundary[], the provisional check reported @@ -85,7 +88,8 @@ by a human reading the ADR rather than by the gate. Reducing likelihood, by preventing the self-produced run: * Declare independence as an execution property of the gate skills, so a run - states which context it requires. + states which context it requires. Tracked as + https://github.com/docs-as-code-toolkit/architecture-knowledge-toolkit/issues/87[issue 87]. * Run the authoritative gate from a fresh context wherever the runtime allows it, without requiring a role-based team structure to obtain it. From f1f8c0345596998e5124503f5bac119258ba9b67 Mon Sep 17 00:00:00 2001 From: Dieter Baier Date: Fri, 4 Sep 2026 14:44:34 +0200 Subject: [PATCH 6/9] issue_86: Reconcile TD-002 and Q-ARCH-006 with the acceptance An independent Convergence Check found both documents contradicting the accepted state of ADR-008. TD-002 said the decisions chapter holds proposed ADRs that are not yet reviewed or accepted. One now is, so the sentence had become false while the debt behind it is unchanged. It is scoped to the remainder rather than deleted. Q-ARCH-006 still read as entirely undecided, while ADR-008 states it answers one instance of it. A reader arriving from the decision met a contradiction. The answer now records the instance that is settled and leaves the general question open, which is what is true. Neither is collateral tidying: both are documents the accepted decision points at, and both said something the repository no longer supports. Co-Authored-By: Claude Opus 5 (1M context) --- .../doc-11002-technical-debt.adoc | 8 +++++--- src/docs/doc-005-questions-and-answers.adoc | 5 +++++ 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/src/docs/arc42/11-risks-and-technical-debt/doc-11002-technical-debt.adoc b/src/docs/arc42/11-risks-and-technical-debt/doc-11002-technical-debt.adoc index 078d684..474411f 100644 --- a/src/docs/arc42/11-risks-and-technical-debt/doc-11002-technical-debt.adoc +++ b/src/docs/arc42/11-risks-and-technical-debt/doc-11002-technical-debt.adoc @@ -34,10 +34,12 @@ repository. wants to keep the full template guidance in source. | TD-002 -| xref:architecture-decisions[] now contains proposed ADR files, but those ADRs -are not yet human-reviewed or accepted. +| Most ADR files in xref:architecture-decisions[] are still proposed and not yet +human-reviewed or accepted. ADR-008 has been reviewed and accepted; the debt is +the remainder. | Source documentation; templates -| Review the proposed ADRs, resolve open questions, and accept or reject them. +| Review the remaining proposed ADRs, resolve open questions, and accept or +reject them. | TD-003 | Quality scenarios contain assumed target measures where implementation diff --git a/src/docs/doc-005-questions-and-answers.adoc b/src/docs/doc-005-questions-and-answers.adoc index 87c735b..22d96ff 100644 --- a/src/docs/doc-005-questions-and-answers.adoc +++ b/src/docs/doc-005-questions-and-answers.adoc @@ -166,6 +166,11 @@ details must move to adapter-specific files under `adapters/`? Answer: As for now, this is not really clear as the knowledge about differences between the AI engines is too low yet. As the knowledge evolves, we will decide. +One instance is decided. xref:adr-008-skill-decomposition-boundary[] places the +agent persona on the runtime side of the boundary: canonical skills are cut by +lifecycle capability, and role-based agents belong to an orchestration layer +above the toolkit. The general question stays open. + [[q-arch-007]] === Q-ARCH-007: Source fragment location From 26edc6db84d10bad3c6dfde15b4ec9b0ad45486a Mon Sep 17 00:00:00 2001 From: Dieter Baier Date: Fri, 4 Sep 2026 14:52:23 +0200 Subject: [PATCH 7/9] issue_86: Drop the stale lifecycle word from a relation rationale The chapter's documents relation for ADR-008 was copied from the ADR-001..ADR-007 pattern and calls the target a "proposed ADR detail page". ADR-008 is accepted, and the generator renders that rationale verbatim into the chapter's impact matrix, so a reader met the wrong lifecycle state in a derived view. The wording is now status-neutral. The other seven keep theirs, which is still accurate for them; the pattern will need the same treatment whenever one of them is accepted. Co-Authored-By: Claude Opus 5 (1M context) --- src/docs/arc42/doc-09000-architecture-decisions.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/arc42/doc-09000-architecture-decisions.adoc b/src/docs/arc42/doc-09000-architecture-decisions.adoc index ffe2953..772a0cd 100644 --- a/src/docs/arc42/doc-09000-architecture-decisions.adoc +++ b/src/docs/arc42/doc-09000-architecture-decisions.adoc @@ -69,7 +69,7 @@ relations: - type: documents target: ADR-008-skill-decomposition-boundary status: proposed - rationale: The chapter links to this proposed ADR detail page. + rationale: The chapter links to this ADR detail page. evidence: src/docs/arc42/doc-09000-architecture-decisions.adoc reviewed: false metadata_version: '1.0' From 3b9205af5234244c968a8b5f18b6daeb2a5f2ef0 Mon Sep 17 00:00:00 2001 From: Dieter Baier Date: Fri, 4 Sep 2026 15:59:41 +0200 Subject: [PATCH 8/9] issue_86: Cite evidence R-007 can actually be checked against An independent review flagged that R-007 cited a converged result from an earlier pull request body as observed evidence. Pull request bodies are rewritten on every re-run and their earlier revisions cannot be retrieved, so nothing established that claim -- a risk about check results that cannot be trusted was resting on a check result nobody could verify. The evidence is now two permanent comment links: the human-found framing defect on the issue, and the run-by-run outcomes on the pull request. Both say more than the original claim did, because three authoring-context runs and two independent ones are now on the record rather than one provisional result. The paragraph also says why the evidence sits outside the repository: there is no record here of how a check was executed, which is the limitation the risk describes. --- .../r-007-gate-results-lack-independence.adoc | 21 +++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc b/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc index 25801fb..931e47d 100644 --- a/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc +++ b/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc @@ -78,10 +78,23 @@ default. Recording that reduction before the requirement exists would put an intention where a control belongs, so this rating is expected to be revisited when that issue closes. -This has already been observed. On the branch that introduced -xref:adr-008-skill-decomposition-boundary[], the provisional check reported -*converged*, and the framing defect corrected in the following commit was found -by a human reading the ADR rather than by the gate. +This has already been observed, on the branch that introduced +xref:adr-008-skill-decomposition-boundary[]. Every check run from the context +that wrote the artifacts reported *converged*. Two runs from a context that had +not authored the change reported *not converged*, and every finding they raised +survived inspection. The first defect of all was found by neither: a human +reading the ADR. + +Both records are outside this repository, because the repository holds no +evidence of how a check was executed — the limitation this risk is about: + +* the human-found defect, at + https://github.com/docs-as-code-toolkit/architecture-knowledge-toolkit/issues/86#issuecomment-5539042867[issue 86, comment]; +* the run-by-run outcomes, at + https://github.com/docs-as-code-toolkit/architecture-knowledge-toolkit/pull/88#issuecomment-5541512602[pull request 88, comment]. + +A pull request body is not cited for either: it is rewritten on every re-run and +its earlier revisions cannot be retrieved, so it cannot carry evidence. === Mitigation Options From 6f5824a7af177a4357053e5fcf147fddc0032764 Mon Sep 17 00:00:00 2001 From: Dieter Baier Date: Fri, 4 Sep 2026 16:29:33 +0200 Subject: [PATCH 9/9] issue_86: State R-007's evidence as a pattern, not a tally R-007 said "Two runs from a context that had not authored the change reported not converged". The comment it cites as evidence recorded three by then, and each further independent run invalidated the number again. A risk about check results that cannot be trusted was making a claim its own evidence refuted. A count is the wrong form for evidence that is still accumulating. The sentence now describes the asymmetry -- authoring-context runs converged, independent runs repeatedly did not -- which is what the record shows and what no further run can falsify. Found by an independent Convergence Check, on the commit whose stated purpose was to make this evidence checkable. Checking it failed. --- .../r-007-gate-results-lack-independence.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc b/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc index 931e47d..35f8ff8 100644 --- a/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc +++ b/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc @@ -80,9 +80,9 @@ when that issue closes. This has already been observed, on the branch that introduced xref:adr-008-skill-decomposition-boundary[]. Every check run from the context -that wrote the artifacts reported *converged*. Two runs from a context that had -not authored the change reported *not converged*, and every finding they raised -survived inspection. The first defect of all was found by neither: a human +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. Both records are outside this repository, because the repository holds no