From 97f6f48098c6ca343371e175451445026ab4a237 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 9 Nov 2026 14:02:56 +0000 Subject: [PATCH] Record remaining adoption and output-failure decisions --- docs/roadmap/commandkit.md | 35 +++++++++++++++-- docs/roadmap/library-adoption.md | 67 ++++++++++++++++++++++++++++++-- 2 files changed, 96 insertions(+), 6 deletions(-) diff --git a/docs/roadmap/commandkit.md b/docs/roadmap/commandkit.md index b4f49ad..d93e2c4 100644 --- a/docs/roadmap/commandkit.md +++ b/docs/roadmap/commandkit.md @@ -1,6 +1,6 @@ # CommandKit Adoption Outline -**Updated:** 2026-11-08 +**Updated:** 2026-11-09 **Status:** Initial outline. Adoption is part of the agreed target, not an optional future evaluation. Implementation is gated on the upstream release described @@ -44,6 +44,7 @@ Before opening the gate, review the published APIs against the capture and destination-validation cases below, select compatible released ckconfig and ckprompt versions, and record the exact versions and source revisions in the [master dependency selection](library-adoption.md#baseline-and-selected-dependency-set). +The concrete release selection is [master open decision 1](library-adoption.md#1-commandkit-released-dependency-set). No future version number is assumed. The integrations need new releases only if their existing releases are incompatible with the selected core version. @@ -209,8 +210,9 @@ design and inventory work can proceed before it opens. framework around CommandKit. 4. Adapt domain process handlers to reporting/outcome boundaries, preserving transcript/artifact integrity, cancellation, and partial success. Apply the - resolved visibility and completion-summary rules above; specify write failures - before implementation. Standard command statuses, including comparison status + resolved visibility and completion-summary rules above; resolve + [output-failure behavior](#output-failure-behavior) before implementation. + Standard command statuses, including comparison status 3, should not be forced into the old Audita-only status table without a domain reason. Validate quiet mode against the transcript destination before creating outputs or starting model work, using the released reporting-mode accessor. @@ -318,3 +320,30 @@ quiet destination validation. Presence information remains available through native typed input. Resolve any remaining integration gap upstream rather than inspecting private state, inferring input from emitted output, redeclaring the core flag, or reparsing arguments. The mode accessor alone does not unblock capture wiring. + +## Open Decisions + +### Output-Failure Behavior + +This is decision 3 in the [master discussion order](library-adoption.md#open-decisions). +Specify how failed transcript, report, debug-artifact, and standard reporter writes +influence the process outcome. The existing visibility rules and prohibition on +a successful completion summary after required-output failure remain selected. + +**Recommendation:** required transcript and enabled ordinary-report failures fail +the invocation. Optional debug-artifact failures remain nonfatal and use the +standard reporting path with existing redaction and visibility rules. Standard +CommandKit reporter failures follow native behavior rather than an Audita-owned +replacement policy. This preserves the distinction between delivering the +requested product and retaining supplemental diagnostic evidence, while avoiding +a second reporting implementation. Validate the exact adopted reporter behavior +and cover early and late output failures, including a report failure after the +transcript has already been written. + +**Alternative:** also make debug-artifact failures fatal when debug capture was +explicitly requested. This treats capture as a required deliverable and makes +incomplete evidence visible in the process outcome, but can fail an otherwise +successful transcript run solely because supplemental evidence could not be +saved. Standard reporter behavior would still remain upstream-owned. Choose the +artifact requirement deliberately rather than infer it from the debug reporting +mode, which remains independent of capture. diff --git a/docs/roadmap/library-adoption.md b/docs/roadmap/library-adoption.md index 7b5ab14..742c939 100644 --- a/docs/roadmap/library-adoption.md +++ b/docs/roadmap/library-adoption.md @@ -1,9 +1,10 @@ # Next Major Release Roadmap -**Updated:** 2026-11-08 +**Updated:** 2026-11-09 **Status:** Agreed direction with proposed sequencing. Initial outlines only; -no implementation or dependency changes have been made for this plan. +no implementation or dependency changes have been made for this plan. Resolve +the three remaining [open decisions](#open-decisions) in the listed order. ## Objective and Document Ownership @@ -115,7 +116,8 @@ resolved reporting-mode accessor for quiet destination validation, as required b the [CommandKit outline](commandkit.md#adoption-gate-released-debug-binding-and-reporting-mode-access). Either API alone is insufficient. Replace the reviewed v0.5.0 core target with that release and record compatible released integration versions -and exact source revisions after review. No replacement version is selected yet. +and exact source revisions after review. No replacement version is selected yet; +this is [open decision 1](#1-commandkit-released-dependency-set). ReleaseKit v0.9.0 at `go.maximumdirect.net/releasekit` is also a required target. The library graph already brings in that version, but Audita's direct tool still @@ -183,6 +185,9 @@ implementation stage is ready. ## ReleaseKit Adoption Work +The concrete workflow and validator selection remain +[open decision 2](#2-releasekit-workflow-and-validator-selection). + 1. Review v0.9.0's supported release workflow, validators, and version integration. Inventory Audita's launcher, scripts, CI responsibilities, and local release checks against those facilities. Select the best target workflow without @@ -242,3 +247,59 @@ Refresh [attribution](../oss/attribution.md) for the exact selected dependencies and toolchain under [OSS policy](../policy/oss.md). The reviewed library grants remain LGPL-3.0-or-later; remove old catalog entries when no longer incorporated and retain shared license texts. Do not copy upstream policy inventories. + +## Open Decisions + +Work through these decisions in order. Recommendations below remain proposals; +the existing adoption principles and CommandKit release gate remain in force. + +### 1. CommandKit Released Dependency Set + +Select and record published core, ckconfig, and ckprompt versions and exact +source revisions after verifying the required independent debug binding and +resolved reporting-mode accessor. The roadmap has not yet established that a +released set satisfies both requirements; historical review evidence does not +open the gate. + +**Recommendation:** select a published core release that passes the required +behavior checks, retaining the reviewed integration versions if they remain +compatible. Verify the assembled dependency graph and capture/quiet-destination +cases before recording the gate as satisfied. This minimizes unrelated migration +scope while adopting the required public APIs. If no qualifying release is +available, keep the implementation gate closed and continue independent planning +and library work. + +**Alternative:** adopt a newer compatible released set of core and both +integrations together. This may incorporate useful fixes and simplify alignment +with current upstream guidance, but requires reviewing additional behavior and +API changes. Neither option permits unreleased replacements, private-state +inspection, or duplicate argument parsing. + +### 2. ReleaseKit Workflow and Validator Selection + +Inventory the current launcher, scripts, CI responsibilities, version integration, +and local release checks against ReleaseKit v0.9.0. Select the concrete workflow, +upstream validators, machinery to remove, and any remaining domain-specific +checks. ReleaseKit adoption and its target version are already agreed. + +**Recommendation:** use the upstream-supported release workflow to own as much +orchestration and validation as it supports. Select all ReleaseKit-owned validators +appropriate to Audita's release requirements, and retain local validation only +with a documented domain-specific justification. This directly reduces Audita's +maintenance burden and follows the suite's standard path. The inventory must +establish which facilities cover the current responsibilities and whether an +upstream request is needed. + +**Alternative:** let CI explicitly sequence ReleaseKit commands through a thin +repository-owned orchestration layer where the upstream workflow cannot express +Audita's required scheduling or platform coordination. Validation still belongs +upstream except for justified domain checks. This can fit concrete CI needs but +retains local sequencing to maintain; prefer an upstream enhancement for a +reusable gap rather than permanently duplicating release machinery. + +### 3. Output-Failure Behavior + +Resolve the [output-failure decision](commandkit.md#output-failure-behavior) in +the CommandKit roadmap after the two selections above. That document owns the +recommendation, alternative, and behavior contract. This decision completes the +remaining write-failure detail before implementing the output/reporting boundary.