feat(governance): add agent intent governance (ADR 0014)

[fedeoliv]

This PR introduces additional engineering discipline inspired by The Architecture of Intent to close three structural gaps:

• Framework agents had no explicit behavioral envelope; coordinator agents now declare Behavioral Constraints (rules tools cannot enforce) and Composition (cross-component invariants).
• Consumer specs describing AI capabilities had no canonical fragment for operational cost commitments; the feature template now carries a gated AI Cost Posture block (model tier, latency budget, prompt stability, per-call cost ceiling, cost-incident escalation), opted into via Describes AI capability: yes metadata in the Executive Summary.
• The failure diagnosis surface on the debugging-recovery skill had no taxonomy mapping a failure to the upstream artifact that owns the fix. Now it ships a three-category upstream-artifact principle - failure (spec), failure (validation), failure (agent).

Spec evolution log added to feature and migration spec templates with the three failure trigger values. Docs site gains a new concept page (AI Capability Specs), two new sections in Spec Amendment, and five glossary entries.

ADR 0014 records the decision, options considered, and the AoI constructs deliberately not adopted (custom frontmatter scalars, Reversibility tier, Pattern A/B/C/D/E taxonomy, seven-category failure taxonomy, standalone authoring handbook, signal metrics, phase rename). AoI attribution added to ACKNOWLEDGMENTS under Articles and Blog Posts.

CHANGELOG entry filed under [Unreleased]; manifest versions unchanged (release bump deferred to release commit).

[marcelaldecoa]

PR #26 Review — AoI Selective Adoption into DevSquad Copilot

Reviewer: Marcel Aldecoa (Author, The Architecture of Intent)
PR: #26
Author: @fedeoliv + Copilot
Date: 2026-05-28

---

Summary

This PR selectively adopts three constructs from The Architecture of Intent (AoI) to close structural gaps in DevSquad Copilot's agent instructions, spec templates, and debugging-recovery surface. An ADR (0014) documents both what was adopted and what was deliberately rejected.

---

Verdict: ✅ APPROVE

The adoption is disciplined, structurally sound, and honest about scope. The three additions solve real gaps without over-engineering the framework.

---

What Was Adopted

1. Behavioral Constraints + Composition Declaration (Agent Instructions)

Aspect	Detail
What changed	Coordinator agents now declare ## Behavioral Constraints (rules tools cannot enforce) and ## Composition (cross-component invariants)
AoI source	Part 1 Ch.5 — Composing Archetypes; §4 Composition Declaration sub-block of the canonical spec template
Alignment quality	🟢 Excellent — directly instantiates the "composition is a first-class design surface" principle
Value delivered	Makes the behavioral envelope explicit; prevents the "composition by accident" anti-pattern AoI identifies

2. AI Cost Posture (Feature Spec Template)

Aspect	Detail
What changed	Feature template gains a gated ## AI Cost Posture block with five fields: model tier, latency budget, prompt stability, per-call cost ceiling, cost-incident escalation
AoI source	§4 Cost Posture sub-block; Part 6 Ch.2 Cost and Latency Engineering; four signal metrics (cost-per-correct-outcome)
Alignment quality	🟢 Excellent — near 1:1 structural match with the five Cost Posture bullets in AoI's canonical template
Value delivered	Gives DevSquad specs a production-readiness commitment that was previously implicit; prevents the "pilot works, rollout doesn't pencil" failure shape
Design choice	Gated behind Describes AI capability: yes in the Executive Summary — smart scoping; not every feature spec needs this

3. Three-Category Failure Taxonomy (Debugging-Recovery)

Aspect	Detail
What changed	Debugging-recovery gains an upstream-artifact principle: failure (spec) / failure (validation) / failure (agent)
AoI source	Part 0 Ch.5 — Failure Modes and How to Diagnose Them (seven-category fix-locus taxonomy)
Alignment quality	🟡 Good — justified simplification
Value delivered	Routes failures to the artifact that owns the fix; prevents the "blame the model" attribution instinct
Simplification rationale	Collapses AoI's seven categories into three upstream-artifact buckets. This is correct for DevSquad's context: DevSquad agents don't perceive physical environments (no Cat 7), and the finer distinctions (Cat 2 Tool vs. Cat 3 Composition vs. Cat 4 Oversight) can be collapsed since DevSquad's debugging surface doesn't need that granularity to route a fix. ADR 0014 makes this explicit.

4. Spec Evolution Log (Templates)

Aspect	Detail
What changed	Feature and migration spec templates gain a spec evolution log with three failure trigger values
AoI source	Part 5 — Closed-loop discipline (amendments flow back to the artifact each Cat names)
Alignment quality	🟢 Excellent — directly implements the closed-loop: failure → categorize → amend upstream artifact

5. Supporting Changes

• Concept page: "AI Capability Specs" on docs site — good discoverability
• Spec Amendment additions: two new sections contextualizing the evolution log
• Glossary: five new entries grounding the vocabulary
• ACKNOWLEDGMENTS: AoI attributed under Articles and Blog Posts
• CHANGELOG: filed under [Unreleased]; no version bump yet (correct — bump belongs to release commit)

---

What Was Deliberately Not Adopted (ADR 0014)

AoI Construct	Reason for Rejection	Assessment
Custom frontmatter scalars	DevSquad already has its own frontmatter convention	✅ Correct
Reversibility tier (R1–R4)	DevSquad's undo model is structural (git + spec versioning), not tiered	✅ Correct
Pattern A/B/C/D/E composition taxonomy	Too granular for DevSquad's composition surface; the principle matters, the taxonomy doesn't	✅ Correct
Seven-category failure taxonomy	Three categories sufficient for DevSquad's debugging surface	✅ Correct
Standalone authoring handbook	DevSquad's docs site already serves this role	✅ Correct
Signal metrics	DevSquad measures differently (backlog health, velocity, quality gate pass rate)	✅ Correct
Phase rename	DevSquad's eight-phase names are established; renaming would break muscle memory	✅ Correct

Assessment: Every rejection is well-reasoned. The PR demonstrates the AoI Adoption Playbook's first principle: tight-focus — adopt what solves your acute problem, leave the rest.

---

Conductor Agent Refactoring

Beyond the AoI adoptions, the PR cleans up the conductor agent:

• Removed the inline sub-agent routing table (agents are surfaced via description: at invocation time — no need to duplicate)
• Streamlined routing decisions to a focused bullet list
• Tightened behavioral language: "relay sub-agent questions to the user verbatim" → explicit no-filter policy
• Removed "run mutating terminal commands" from "You do NOT" — correct Orchestrator discipline

This maps cleanly to AoI's Orchestrator archetype: coordinates, delegates, sequences; does not generate output that belongs to a sub-agent's scope.

---

Suggestions (Non-Blocking)

1. Consider linking failure categories to the evolution log

The three failure triggers (failure (spec) / failure (validation) / failure (agent)) in the spec evolution log could reference which section of the spec is most likely to need amendment for each category. AoI's discipline: "failure → categorize → amend the specific artifact that owns the fix." A one-line hint per trigger type would close the loop tighter.

2. Cost Posture: consider naming the downstream metric

AoI's Cost Posture sub-block explicitly names cost-per-correct-outcome as the downstream metric the upstream commitment serves. If DevSquad has (or plans) a cost efficiency metric, naming it in the template text would close the spec↔measurement loop.

3. Future consideration: Cat 7 awareness

If DevSquad ever gains computer-use or browser-use agent capabilities, the three-category taxonomy will need a fourth bucket (perceptual failure). The ADR could note this as an explicit future-trigger for re-evaluation.

---

Final Assessment

Criterion	Rating
Structural soundness	⭐⭐⭐⭐⭐
Honest accounting (what adopted / what rejected)	⭐⭐⭐⭐⭐
Alignment with AoI principles	⭐⭐⭐⭐⭐
Practical value to DevSquad users	⭐⭐⭐⭐
Documentation quality	⭐⭐⭐⭐⭐

This is how selective framework adoption should look: identify the structural gaps, adopt the constructs that close them, document what you evaluated and rejected, and attribute the source. Well done.