11. Risks and Technical Debt
These risks follow from the accepted contracts, external dependencies and gaps in their evidence. They are not a list of observed production incidents. The documented Python timing regression is an observed deviation; most other entries are implementation or integration risks. An unimplemented feature is not automatically technical debt, and accepting an ADR does not close a risk.
11.1 Priorities and responsibility
Section titled “11.1 Priorities and responsibility”P1 identifies a risk to authority, data integrity or trustworthy outcomes. It must be addressed before offering the affected guarantee. P2 identifies a risk to usability, performance or operational suitability that must be evaluated for the advertised support profile. These are review priorities, not measured probabilities or a product delivery schedule.
The responsible roles below identify who must provide evidence. In a small team one person can hold several roles; none implies a new department or service. A risk closes for an exact implementation, configuration and environment, not for every adapter by association.
| Risk | Priority / responsible role | Consequence and required evidence |
|---|---|---|
| R01 — Contracts agree on paper but implementations diverge | P1 · core and adapter maintainers | A parser, built-in handler or MCP adapter may skip a check enforced elsewhere. Executable schemas, negative conformance cases and one integrated local CLI/MCP composition must verify the same command, authority and outcome contracts, including independent extension updates. Reference process tests do not establish that composition. Q05, Q07, Q17, Q19 |
| R03 — Advertised execution guarantees are unavailable on the actual host | P1 · executor maintainer and CLI owner | Restricted accounts, process controls, inherited handles, mutable paths or escaped descendants can invalidate a guarantee. Record the exact supported OS/runtime/filesystem and policy configuration; verify establishment before code starts, failure handling and cleanup. A host-trusted process remains outside confinement regardless of task quotas. Q09, Q15 |
| R04 — Concurrent writes or a crash corrupt shared ownership | P1 · storage/coordinator maintainer | A mixed profile, reused task budget or premature collection can execute the wrong release or lose protected state. Fault-inject writes, flushes, commits and reference acquisition across processes; distinguish an incomplete tail from corruption. Network or synchronized storage needs its own evidence and is not interchangeable with verified local storage. Q03, Q08 |
| R05 — External authority changes or fails during an operation | P1 · identity/permission adapter maintainer and CLI owner | Stale responses, renewal or a local fallback could restore withdrawn rights. Verify final admission against invalidation and account changes; document the selected provider’s propagation and validity semantics. Observed local revocation does not prove immediate fleet-wide revocation. Q02, Q16 |
| R06 — An effect succeeds externally but its result is lost | P1 · operation adapter and effect-store maintainers | Blind retry can duplicate the action; deleting uncertainty can release spent allowance. Verify one-use admission, crash recovery and service-specific reconciliation. Unknown effects retain reservations and may exhaust capacity; cancellation is not rollback. Q10, Q18 |
| R07 — Artifact integrity is mistaken for publisher approval | P1 · CLI owner and distribution adapter maintainer | A checksum from the same untrusted source does not establish trust. Test publisher/package/digest approval, changed bytes, archive boundaries, revoked candidates and rollback under current policy. Larger signing and key-distribution schemes need explicit trust-lifecycle decisions. Q11 |
| R08 — Preparation or trusted integration escapes its ownership boundary | P1 · runtime/integration maintainer | A manager hook, global installation or uncooperative in-process callback can exceed authority or prevent shutdown. Check exact preparation plans, per-waiter authorization, cancellation, finite resources and non-interference with borrowed tools. Work requiring forced stopping needs a supported supervised binding. Q04, Q05, Q14 |
| R09 — Output, diagnostics or interaction cross the wrong boundary | P1 · core, UI and operation adapter maintainers | Terminal control, secrets or private membership can leak through protocol output, logs, public catalogs or untrusted confirmation. Check byte-preserving pipes, terminal ownership, noninteractive behavior, protected credential references and required-audit failure. Accessibility and real terminal behavior need separate environment evidence. Q12, Q16, Q18 |
| R02 — Python startup exceeds the accepted comparison limits | P2 · process/runtime adapter maintainer | The ADR-0003 reference meets the small IPC limits but exceeds readiness and complete-invocation limits for Python. Isolate startup/import/adapter cost and repeat comparable measurements without removing required checks. The thresholds remain unchanged. Q06 |
| R10 — Design quotas are mistaken for measured capacity | P2 · core maintainer and CLI owner | Catalog size, concurrent calls, output, slow dependencies and retained uncertain records may make a valid configuration impractical. Measure the selected workload and exhaustion behavior; quotas must not be reported as throughput, RAM, latency or availability guarantees. Keep local setup and operation in the same evaluation. Q13, Q14, Q15 |
The order groups risks by priority; identifiers remain stable when priorities change. Exact rules and historical results stay in the defining records:
| Risks | Defining decisions |
|---|---|
| R01 | ADR-0002, ADR-0006, ADR-0010, ADR-0013 |
| R02 | ADR-0001, ADR-0003 |
| R03 | ADR-0003, ADR-0014, ADR-0015 |
| R04 | ADR-0007, ADR-0009, ADR-0014 |
| R05 | ADR-0005, ADR-0011, ADR-0012 |
| R06 | ADR-0004, ADR-0016 |
| R07 | ADR-0007, ADR-0009 |
| R08 | ADR-0008, ADR-0010, ADR-0015 |
| R09 | ADR-0002, ADR-0009, ADR-0011, ADR-0013, ADR-0016 |
| R10 | ADR-0003, ADR-0007–ADR-0010, ADR-0014, ADR-0016 |
11.2 Open assumptions and acceptance evidence
Section titled “11.2 Open assumptions and acceptance evidence”The deployment view describes placement and operating dependencies; quality scenarios describe the required response. Neither substitutes for an implementation support record. For each claimed configuration, the CLI owner and maintainers need the following evidence:
| Open area | Evidence needed to evaluate suitability |
|---|---|
| Platform and organization policy | Exact OS, architecture, runtime, filesystem, account permissions and execution restrictions; results for normal and restricted environments, not only an administrator’s workstation |
| Workload and performance | Extension/command counts, payload and output sizes, concurrent callers and preparation, cache state, retained state and dependency latency; separate core overhead from command work and downloads |
| Dependency availability | Required versus optional services, selected deadlines and freshness rules, diagnostic behavior during disconnection, and the provider’s own commitments. No external outage silently selects a weaker local policy |
| Durable state and recovery | Fault-injection results for the selected store; safe recovery after corruption or loss, including stale policy, task/effect records and credentials. Restoring files alone is not evidence that an old grant or consumed permit is valid |
| Operations and data handling | Responsible role and procedure for trust/policy changes, protected-store failures, quota exhaustion and unresolved effects; permitted diagnostic fields, access and retention rules for the selected integrations |
No generic fleet availability percentage, recovery time, data-retention period or concurrency promise is selected by these pages. Missing values remain explicit in section 10, where measurements can be attached to the exact scenario. Choosing a new guarantee requires the defining ADR to be refined before it is advertised. Routine conformance results can be added without pretending they are new architecture decisions.
11.3 Boundaries requiring additional decisions
Section titled “11.3 Boundaries requiring additional decisions”The accepted local baseline already permits trusted extensions, local policy and protected local coordination. It must not acquire mandatory enterprise services merely to close the above risks. Conversely, small-team deployment does not remove integrity, authorization or ownership checks. ADR-0009, ADR-0010
Additional executors and background ownership, broader signing/trust distribution, external audit retention and concrete distributed coordination need separate decisions where they add guarantees beyond the accepted contracts. They are not implicitly provided by the current diagrams. ADR-0002, ADR-0004, ADR-0007, ADR-0015, ADR-0016