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..459840e --- /dev/null +++ b/src/docs/arc42/09-architecture-decisions/adr-008-skill-decomposition-boundary.adoc @@ -0,0 +1,274 @@ +--- +id: ADR-008-skill-decomposition-boundary +type: ADR +title: Skill Decomposition and Agent Role Boundary +status: accepted +owner: architecture +created: '2026-09-04' +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. + 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: 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: 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: true +- type: introduces_risk + target: R-007-gate-results-lack-independence + 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: true +- type: mitigates + target: R-006-unclear-adapter-boundaries + 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: true +metadata_version: '1.0' +--- +[[adr-008-skill-decomposition-boundary]] +== ADR-008: Skill Decomposition and Agent Role Boundary + +=== Status + +Accepted (derived). + +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 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. + +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 + +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. + +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. + +| 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 +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: 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: 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. + +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. + +=== 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, 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 + +==== 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. 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 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 + +* 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. +* 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 + +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 + +* 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 + +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. + +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. 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/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..35f8ff8 --- /dev/null +++ b/src/docs/arc42/11-risks-and-technical-debt/r-007-gate-results-lack-independence.adoc @@ -0,0 +1,147 @@ +--- +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. + +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. 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[]. 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. + +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 + +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. 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. + +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. + +=== 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-09000-architecture-decisions.adoc b/src/docs/arc42/doc-09000-architecture-decisions.adoc index 5e90cd4..772a0cd 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 ADR detail page. + evidence: src/docs/arc42/doc-09000-architecture-decisions.adoc + reviewed: false metadata_version: '1.0' --- = [[architecture-decisions]]Architecture Decisions 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 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