Status: Accepted (inferred) — carried forward from v3, rationale reconstructed from the codebase

Context: docToolchain uses scripts in multiple languages. The team needed a consistent primary language for maintainability.

Decision: Use Groovy for all scripting tasks. Exception: Visual Basic for Windows COM automation (Enterprise Architect, PowerPoint export) where no Java library exists.

Alternatives considered:

Quality Tradeoffs:

Status: Superseded by ADR-3

Context: ADR-2 proposed isolating business logic into a compiled core/ submodule (Shadow JAR) to decouple from Gradle.

Superseded because: v4 removes Gradle entirely (ADR-3) and reverts to scripts as the primary code organization. Compiled code requires a build step that slows the edit-run cycle. Scripts are easier to adapt and maintain, especially for community contributors. The problem ADR-2 tried to solve (Gradle coupling) is better addressed by removing Gradle, not by adding a compilation layer.

Status: Accepted (for v4)

Context: Gradle has been the task orchestration framework since docToolchain’s inception. Over time it has caused significant problems:

Decision: Remove Gradle entirely. The dtcw wrapper invokes Groovy scripts directly via the java/groovy runtime. AsciiDoctor is an external CLI tool, auto-installed by dtcw (ADR-6). Task orchestration is handled by simple script conventions, not a build framework.

Alternatives considered:

Quality Tradeoffs:

Consequences: build.gradle, settings.gradle, gradle.properties, libs.versions.toml, and the gradle/ wrapper directory are removed. The core/ module is dissolved back into scripts. Dependencies are managed as JARs in a lib/ directory or downloaded on demand. This decision creates risk R-002 (v3 migration path) — Gradle-based workflows break — and R-003 (script loading and classpath conflicts) now that Gradle no longer resolves dependencies; both are tracked in [section-technical-risks].

Status: Accepted (for v4) — implemented in v4.0 as MicrositeBaker (scripts/lib/MicrositeBaker.groovy, see Chapter 8)

Context: jBake is the current static site generator for docToolchain’s microsite feature. Critical problems:

Decision: Build a custom Groovy-based static site generator using Groovy SimpleTemplate. The core requirement is: AsciiDoc files + templates → static HTML site with navigation, search, and theming.

Alternatives considered:

Quality Tradeoffs:

Consequences: Existing 23 Groovy SimpleTemplate files can be reused with minimal changes. The custom SSG parses AsciiDoc metadata (:jbake-: attributes) itself — a simple regex pass over file headers (~20 LOC, reused from v3’s generateSite.gradle). AsciiDoctor CLI handles HTML rendering (ADR-6). No database — in-memory content model. Modern UI theme replaces Docsy (Phase 1: modern look; Phase 2: LLM-augmented UI in future version). This decision creates risk *R-001 (custom site generator maturity) — feature-parity and regression risk — tracked in [section-technical-risks].

Status: Accepted (for v4)

Context: The GenAI era changes how documentation is created and consumed. Traditional export scripts (EA, PPT, Visio, Excel) address a workflow where humans manually extract data from tools. LLMs can handle these transformations directly. Meanwhile, LLMs need structured document access (daCLI) and benefit from Skills, Prompts, and Semantic Anchors.

Decision: Shift docToolchain’s strategic focus toward LLM-native tooling:

Quality Tradeoffs:

Consequences: Existing scripts remain available but strategic investment shifts to MCP tools, Prompts, and Semantic Anchors. The docToolchain ecosystem becomes: docToolchain (generation) + daCLI (LLM access) + Bausteinsicht (architecture diagrams) + LLM-Prompts (interaction patterns). Traditional scripts are maintained but not the primary growth area.

Status: Accepted (for v4) — revised: the analysis below favoured the external CLI, but v4 as built embeds AsciidoctorJ in-process (the external-CLI option was not adopted). See the Revision note after the matrix; the footprint consequences are reflected in ADR-7 and Chapter 11.

Context: In v3, AsciiDoctor is embedded as asciidoctorj — a Java wrapper that bundles JRuby (~30 MB). Together with transitive dependencies, this adds ~25 JARs and ~45 MB to the classpath. JRuby initialization adds 2-3 seconds to every startup. AsciiDoctor also exists as a standalone CLI tool installable via gem, brew, or apt.

Decision: Use AsciiDoctor as an external tool, auto-installed by dtcw in a pinned version. This follows the same pattern as Java auto-installation. AsciiDoctor CLI supports batch processing (asciidoctor *.adoc), so 50 files are handled in one process invocation.

Alternatives considered:

Quality Tradeoffs:

Consequences (as built, per the Revision above): scripts call the AsciidoctorJ Java API in-process — there is no external asciidoctor CLI step in dtcw. The asciidoctorj, asciidoctorj-diagram, asciidoctorj-pdf, and JRuby JARs are retained in lib/ (the original plan to remove them was not carried out). This keeps v4 self-contained at the cost of footprint and JRuby startup — the real lib/ footprint is 177 JARs / ~126 MB (ADR-7), tracked as technical debt in [section-technical-risks].

Status: Accepted (for v4)

Context: AsciiDoctor is embedded as AsciidoctorJ (ADR-6, revised), so the Java dependencies that ship in lib/ are:

Decision: Ship all JARs in a lib/ directory. dtcw sets the classpath via java -cp lib/*. No runtime resolution, no Grape, no downloads.

Rationale: A bundled lib/ gives zero resolution overhead (supports QS-9), full offline capability, and determinism — every user gets the exact same JARs. The simplest possible solution. The trade-off is size: the real footprint is ~126 MB (not the 23 MB first estimated), driven by embedding AsciidoctorJ/JRuby (ADR-6, revised) — recorded as technical debt in Chapter 11.

Alternatives considered:

Quality Tradeoffs:

Consequences: Release process must resolve all transitive dependencies and package them into lib/ (177 JARs today). A simple shell script or one-time Gradle/Maven call at release time handles this. The ~126 MB footprint is the main downside; POI and AsciidoctorJ/JRuby JARs could be made optional/lazy in a future optimization (load only when the task needs them) — tracked as technical debt in [section-technical-risks]. This decision creates risk R-005 (release-time dependency resolution) — a tampered or vulnerable JAR (threat T-006) would reach every user — and contributes to R-003 (script loading and classpath conflicts); both are tracked in [section-technical-risks].

Status: Accepted (for v4) — carrier implemented; rollout in progress. The hierarchy and top-level handler below exist in scripts/lib/DtcException.groovy (DtcError.report() maps each type to a differentiated exit code; DtcError.redact() masks secret-shaped values), unit-tested in DtcExceptionSpec. Seven tasks are migrated (generateHTML, generatePDF, publishToConfluence, copyThemes, lintAsciiDoc, generateCICD, downloadTemplate): they throw DtcConfigException/DtcApiException/DtcException with guidance and route everything through a single top-level handler (differentiated exit codes 0/1/2/3). The remaining task scripts still use System.exit + println and are migrated incrementally (risk R-004). redact() also delivers the T-002 secret-redaction mitigation for script-level error output, and DtcRestClient redacts its own HTTP error output via the same logic (Chapter 8).

Context: v3 error handling is inconsistent: RuntimeException in core, GradleException in scripts, println + silent continuation in some scripts. With Gradle removed, GradleException is gone. More importantly, the fundamental problem is not how errors are thrown, but what the user sees. v3 shows stack traces and technical error messages. Users cannot determine what to do next.

Decision: Every user-recoverable error must include an actionable remediation step — not what went wrong, but what the user should do to fix it. Implemented as a lightweight exception hierarchy with mandatory guidance messages (scripts/lib/DtcException.groovy):

// Shared helper (lib/DtcException.groovy, ~25 LOC)
class DtcException extends RuntimeException {
    String guidance  // What the user should do
    int exitCode
    DtcException(String guidance, int exitCode = 1, Throwable cause = null) {
        super(guidance, cause)
        this.guidance = guidance
        this.exitCode = exitCode
    }
}
class DtcConfigException extends DtcException {
    DtcConfigException(String guidance) { super(guidance, 2) }
}
class DtcApiException extends DtcException {
    DtcApiException(String guidance) { super(guidance, 3) }
}

// Usage in scripts:
if (!outputFile.canWrite()) {
    throw new DtcException(
        "Die Datei ${outputFile.name} ist gesperrt. " +
        "Bitte schließe sie in deinem PDF-Viewer und führe den Befehl erneut aus."
    )
}

if (!configFile.exists()) {
    throw new DtcConfigException(
        "Config-Datei '${configFile.name}' nicht gefunden. " +
        "Erstelle sie mit: ./dtcw4 downloadTemplate"
    )
}

if (response.statusCode == 401) {
    throw new DtcApiException(
        "Confluence-Authentifizierung fehlgeschlagen. " +
        "Prüfe confluence.api/credentials in docToolchainConfig.groovy bzw. die passenden Umgebungsvariablen."
    )
}

// Top-level runner (in dtcw wrapper or bootstrap script):
try { script.run() }
catch (DtcConfigException e) { System.err.println("⚙ ${e.guidance}"); System.exit(2) }
catch (DtcApiException e)    { System.err.println("🌐 ${e.guidance}"); System.exit(3) }
catch (DtcException e)       { System.err.println("→ ${e.guidance}"); System.exit(1) }
catch (Exception e)          { System.err.println("BUG: ${e.message}"); e.printStackTrace(System.err); System.exit(99) }

Alternatives considered:

Quality Tradeoffs:

Consequences: Every script must use DtcException (or subclass) instead of println for errors. Existing RequestFailedException is replaced by DtcApiException. A catalog of common error scenarios with guidance messages should be maintained (see examples in Risks section). The guidance messages should be in English (matching the codebase language), with the tone of a helpful colleague, not a system log. This decision mitigates risk R-004 (residual inconsistent error handling) in [section-technical-risks]: until every script adopts DtcException, the mixed-error-handling risk remains tracked.

Status: Accepted (for v4) — decided; not yet implemented. The diagramServer config key, the auto-started local Kroki container, and the QS-16 external-URL warning described below do not exist in code yet (risk R-007). Today diagrams render through the embedded asciidoctor-diagram (AsciidoctorJ, ADR-6 revised), and DiagramToolHints.groovy points users at the public kroki.io with no warning — which is exactly the privacy gap this ADR closes. Goal #1 (no implicit cloud processing) is therefore met today only because the default render path happens to be local, not because the documented control is enforced.

Context: With AsciiDoctor embedded (ADR-6, revised), diagram rendering (PlantUML, Mermaid, GraphViz, Ditaa, C4, BPMN) requires either locally installed tools or a diagram server. Local tools mean installing PlantUML (Java), Graphviz (C binary), Mermaid (Node.js) — different package managers per OS, per tool. A diagram server reduces this to one URL.

Decision: Use a Kroki-compatible diagram server as the rendering strategy. The user configures one URL — everything else follows. The default is docker (a local Kroki container), which keeps all diagram source on the machine and satisfies quality goal #1 (no implicit cloud processing). Users may opt in to the public https://kroki.io/ service or, for enterprises, point to their own Kroki or GitLab PlantUML server.

// Option 1: dtcw starts a local Kroki Docker container automatically
diagramServer = 'docker'

// Option 2: Public Kroki service
diagramServer = 'https://kroki.io/'

// Option 3: Enterprise server (GitLab PlantUML / self-hosted Kroki)
diagramServer = 'https://gitlab.company.com/kroki/'

⚠ Diagramm-Quelltexte werden an kroki.io gesendet.
  Für lokale Verarbeitung setze diagramServer = 'docker' in docToolchainConfig.groovy.

Alternatives considered:

Quality Tradeoffs:

Consequences: docker (a local Kroki container) is the default diagram server, so no diagram data leaves the machine unless the user explicitly configures an external URL (QS-16). asciidoctor-diagram configuration attributes are set automatically based on the diagramServer config key. Enterprise users point to their GitLab PlantUML server or self-hosted Kroki. The docToolchain Docker image does NOT bundle Kroki — it connects to the configured server. A docker-compose.yml example is provided for users who want to run Kroki locally alongside docToolchain.

Status: Accepted

Context: docToolchain v4 uses AI-assisted development (Claude Code). AI-generated code carries risks that depend on code type, language safety, deployment context, data sensitivity, and blast radius. Without a systematic framework, mitigation measures are applied inconsistently — some areas are over-tested while critical gaps remain.

Decision: Adopt the Vibe-Coding Risk Radar as the quality assurance framework. The risk assessment is documented in CLAUDE.md (machine-readable for AI agents) and reviewed when the codebase changes significantly.

Alternatives considered:

Quality Tradeoffs:

Consequences: The risk assessment in CLAUDE.md must be updated when new modules are added or when the deployment context changes. Pending mitigations (type checking, pre-commit hooks, dependency audit, property-based tests) should be addressed incrementally. The tier may change if docToolchain adds authentication features or processes sensitive data.

Status: Accepted

Context: ADR-10 assessed docToolchain as Tier 2 (Extended Assurance) with only 5 of 10 required mitigations in place. Four gaps needed to be closed: pre-commit hooks, dependency checking, type checking/static analysis, and AI code review. Property-based tests were identified as the tenth measure but deferred.

Decision: Implement the four missing mitigations using free, open-source tools that work independently of Gradle (preparing for the v4 transition per ADR-3).

Alternatives considered:

Quality Tradeoffs:

Consequences: All CI workflows are independent of Gradle and will survive the v4 migration unchanged. The pre-commit framework must be installed in the devcontainer (added to post-create.sh). CodeNarc downloads JARs from Maven Central at CI runtime (~12 MB). Trivy scans require ./gradlew packageLibs to populate build/lib/ — after v4 migration this will be replaced by whatever populates lib/.

Status: Accepted (port of publishToConfluence pending)

Context: ADR-3 decided to remove Gradle and stated as a consequence that "the core/ module is dissolved back into scripts." Eleven of the twelve v4 tasks honour this — they are standalone scripts/*.groovy files that use only the scripts/lib/ helpers and third-party JARs. One task does not: scripts/publishToConfluence.groovy:10 imports org.docToolchain.tasks.Asciidoc2ConfluenceTask, an 823-LOC class in the compiled core/ module that pulls in six further core classes. Because packageLibs does not ship the core module’s own JAR, that class is not on the task classpath and publishToConfluence fails to load at all (#1626). The compiled core module therefore survives solely for this one task, contradicting ADR-3 and keeping a build-and-package step alive that the rest of v4 has shed.

Decision: Make "a task is a self-contained Groovy script with no compiled core/ dependency" an explicit, enforced architectural rule. Port Asciidoc2ConfluenceTask (and the core classes it needs) into a standalone scripts/publishToConfluence.groovy built on the lib/ helpers (DtcRestClient, DtcConfig). Once that is the last consumer, drop the compiled core/ module from the runtime classpath entirely.

Alternatives considered:

Quality Tradeoffs:

Consequences: publishToConfluence is rewritten as a standalone script; the core/tasks/Asciidoc2ConfluenceTask logic and its required helpers move into scripts//scripts/lib/. After the port, the compiled core/ module is dropped from the packaged classpath, completing ADR-3’s "core dissolved into scripts." This decision creates risk R-006 (publishToConfluence port regression) — re-implementing the most complex task (page tree, attachments, new-editor handling, rate limiting) risks behavioural regressions in Confluence publishing — tracked in [section-technical-risks]. Until the port lands, publishToConfluence remains non-functional (#1626); the ADR Status stays "Accepted (port pending)" and flips to "Accepted" when the script ships and the core module is removed.

Status: Accepted (inferred) — reconstructed from dtcw4 and dtcw; no prior written decision.

Context: v4 is distributed as a git checkout that must be built (packageLibs) before use, and it coexists on developer machines with v3. A project needs some entry point checked into its repository, but that entry point should not pin a project to one machine’s installation, nor require every project to carry the full wrapper logic. Two concerns pull apart: the per-project bootstrap (what lives in the repo) and the installed runtime (what actually runs tasks).

Decision: Ship only a thin dtcw4 bootstrap in the project directory. It performs v4-specific installation — clone main-4.x, run packageLibs — into ~/.doctoolchain/docToolchain-<version>/, then delegates all task execution to the installed dtcw there (dtcw4 lines 5-9). The installed dtcw owns environment detection, classpath construction from lib/, and task dispatch. Only dtcw4 needs to live in a project; upgrading the runtime does not touch the project.

Alternatives considered:

Consequences: A project commits one small dtcw4 file. The heavy wrapper logic lives once in the installed dtcw, so fixes ship with a runtime upgrade rather than requiring every project to re-copy a wrapper. The delegation seam means task-execution behaviour is identical whether invoked via dtcw4 or the installed dtcw directly. The bootstrap depends on git and network access on first install; this is the same install-time dependency already accepted for Java/AsciiDoctor provisioning and is not separately risk-tracked.

Status: Accepted (inferred) — reconstructed from dtcw; no prior written decision.

Context: v4 tasks are plain Groovy files in scripts/. That same directory also holds non-task code: scripts/lib/ helpers (DtcConfig.groovy, MicrositeBaker.groovy, DtcRestClient.groovy, …) that are loaded by tasks but must never be invoked as tasks themselves. The wrapper needs a reliable way to answer two questions — "which scripts may a user run?" (for dtcw tasks) and "is this name a real task?" (for dtcw <name>) — without a central registry that every new task has to be added to.

Decision: A script is a runnable task iff it carries the line marker // @task within its first 5 lines. dtcw discovers tasks by scanning scripts/*.groovy and grepping the file head for that marker (dtcw lines 685 and 702); listing and validation use the same check. Adding a task is therefore a one-file operation: drop a scripts/<name>.groovy with // @task near the top — no edit to any registry, build file, or the wrapper.

Alternatives considered:

Consequences: The marker is the single source of truth for "is this a task", so the task list never drifts from the files on disk. Helper code stays safe simply by living in scripts/lib/ and omitting the marker. The cost is a convention contributors must know: a new task silently fails to appear if the // @task line is missing or pushed past the first 5 lines — a documentation/onboarding concern rather than a runtime risk. The marker is intentionally a comment, so it costs nothing at execution time and survives any Groovy tooling that ignores comments.

Status: Accepted (for v4) — model authored; inline C4-PlantUML kept as the rendered artifact; export wiring deferred. The spike (#1641) confirmed that Bausteinsicht has no PlantUML exporter, so the hoped-for model → PlantUML → microsite round-trip does not exist yet. The Level-1 model lives at src/docs/arc42/models/level1-container.jsonc; it is authored against the published Bausteinsicht JSON schema and the online-shop reference example and parses as JSONC, but has not yet been validated by the Bausteinsicht binary (not available in the docs build environment) — a bausteinsicht sync validation pass is the open follow-up.

Context: The arc42 Chapter 5 building-block views are hand-written C4-PlantUML embedded directly in 05_building_block_view.adoc (level1-container-v4, level3-atlassian-v4). They satisfy the Semantic Contract (PlantUML + C4-PlantUML stdlib !include <C4/…​>), but every structural change means editing PlantUML by hand and there is no single, tool-readable source of truth. Bausteinsicht — our own Go architecture-as-code tool (JSONC model, bidirectional draw.io sync) — exists precisely for this, and the cross-repo relationship states "Bausteinsicht generates architecture diagrams consumable by docToolchain." We do not currently eat our own dog food for docToolchain’s own architecture docs.

Decision: Maintain the structural (C4 building-block) views as a versioned Bausteinsicht JSONC model — the single, machine-readable, LLM-editable source of truth — but keep the inline C4-PlantUML block as the rendered artifact in the microsite for now. Start with the Level-1 container view; keep Level-3 (level3-atlassian-v4) inline-only until the model proves itself. Wire an automatic render path only once a clean text-based export exists (a Bausteinsicht PlantUML exporter — to be requested upstream — or an accepted draw.io-CLI image step). Until then, the model and the inline PlantUML are kept in sync by hand (tracked as technical debt in [section-technical-risks]).

Alternatives considered:

Quality Tradeoffs:

Consequences: src/docs/arc42/models/level1-container.jsonc becomes the source of truth for the Level-1 container view; 05_building_block_view.adoc carries a NOTE linking the inline level1-container-v4 block to that model and to this ADR. The decision creates a technical-debt item — "Hand-synchronised Bausteinsicht model and inline PlantUML" — recorded in [section-technical-risks] (11.2) against the Chapter 5 building-block view documentation; it is explicitly accepted as low-cost (one Level-1 view, changed rarely) rather than tracked as an R-NNN risk. The debt retires when either (a) Bausteinsicht ships a PlantUML/C4-PlantUML exporter — to be requested upstream — and generateSite consumes it as a generated include kept inside the rendered doc tree (a file-outside-tree include is fatal), or (b) the team accepts a draw.io-CLI PNG/SVG step in the build. Level-3 stays inline-only; rolling the model out to Level-3 is a follow-up gated on the same export path. Open follow-up: validate the model with bausteinsicht sync once the binary is available in the build environment, and add the bausteinsicht ecosystem tool note in Chapter 5 (already present).

Status: Accepted (for v4)

Context: v4 tasks are self-contained Groovy scripts (ADR-12) discovered by the // @task marker (ADR-14), but dtcw only ever resolves them from the installed runtime (~/.doctoolchain/docToolchain-<version>/scripts/). A project therefore could not (a) add its own task without forking docToolchain, nor (b) modify a shipped task short of editing the shared installation — which every other project on the machine then inherits. The v3 mechanism for this (scripts/customTasks.gradle, the customTasks = […​] config list, and a Gradle createTask) is Gradle-bound and dead under the Gradle-free v4 runtime (ADR-3). Quality goal QS-1 ("a contributor adds a task as one script, no build-system knowledge") is only half met: it holds for docToolchain’s own repo, not for a consuming project. Two distinct user needs share one root cause — dtcw does not look in the project:

Decision: dtcw resolves a task from a project-local scripts directory first, then the installation. The directory defaults to scripts/ under the project root and is overridable via DTC_PROJECT_SCRIPTS_DIR. The same ADR-14 rule applies: a file is a task iff it is a *.groovy with // @task in its first 5 lines — so discovery is uniform across installed and project tasks, with no registry and no config edit (extending QS-1 to consuming projects).

Alternatives considered:

Quality Tradeoffs:

Consequences: dtcw gains a project-first resolution step in assert_v4_task_exists, list_v4_tasks, and build_command; the listing flags overrides and groups custom tasks. Project tasks are executable Groovy authored by the project — the same local-trust assumption already accepted for docToolchainConfig.groovy (threat T-005, [section-concepts]): opening and running dtcw in a project already runs that project’s Groovy, so project tasks add no new trust class, only more surface within it. The override Note: keeps shadowing visible. This decision depends on ADR-17 so that a copied or custom script can still load the bundled lib/ helpers from the installation. No new Chapter 11 risk is created; the consequence is recorded as accepted under the existing T-005 local-trust model. The Windows wrappers (dtcw.ps1/dtcw.bat) do not yet carry the v4 path at all (Chapter 11 technical debt), so project-task resolution lands in the Bash dtcw first; Windows parity rides on the existing "no v4 Windows wrapper path" debt item.

Status: Accepted (for v4)

Context: Every v4 task script loads its shared helpers relative to its own file location: def scriptDir = new File(getClass().protectionDomain.codeSource.location.toURI()).parentFile and then new File(scriptDir, 'lib/DtcConfig.groovy'). Three scripts likewise derive dtcHome = scriptDir.parentFile to find bundled resources (themes, landing page). This works only because installed scripts sit next to lib/. ADR-16 lets a script run from the project scripts/ directory, where there is no lib/ and no bundled resources — so a copied (monkey-patched) or custom script would fail to load DtcConfig/DtcException and break at startup. The helpers and resources it needs live in the installation, not the project.

Decision: dtcw passes the installed scripts directory to every run as a system property: -Ddtc.scriptsHome="${dtc_home}/scripts" (and /opt/docToolchain/scripts inside the Docker image). Scripts resolve their helper/resource base from that property, falling back to the on-disk script location when it is absent:

def scriptDir = System.getProperty('dtc.scriptsHome')
    ? new File(System.getProperty('dtc.scriptsHome'))
    : new File(getClass().protectionDomain.codeSource.location.toURI()).parentFile

Alternatives considered:

Quality Tradeoffs:

Consequences: The scriptDir/dtcHome definition is updated to the property-first form across the v4 scripts that load lib/ or bundled resources, and dtcw exports dtc.scriptsHome on every v4 invocation (local and Docker). This unblocks ADR-16: monkey-patched and custom scripts run against the installed helpers. It also contributes to R-003 (script loading / classpath) — helper resolution now hinges on a correctly-set property — mitigated by the safe fallback to the script’s own directory when the property is unset (e.g. direct groovy invocation outside dtcw).

Status: Accepted (for v4)

Context: v4 task dispatch logic currently lives in the Bash wrapper dtcw: task discovery (list_v4_tasks), validation (assert_v4_task_exists), and selection/invocation (the v4 branch of build_command), including the project-first resolution and override notes added for ADR-16. dtcw4 only bootstraps and exec`s the installed `dtcw (ADR-13). Two forces make Bash the wrong long-term home for this logic:

Decision: Extract v4 task discovery, resolution, and invocation into a single Groovy launcher (e.g. scripts/Launcher.groovy) executed inside the JVM the wrapper already starts. The platform wrappers (dtcw, dtcw.ps1, dtcw.bat) are reduced to what only they can do — detect the environment, locate Java, build the lib/* classpath, and hand all arguments to the launcher with the existing system properties (docDir, dtc.scriptsHome, DTC_PROJECT_SCRIPTS_DIR, …). The launcher owns: scanning the project and installed scripts directories, the // @task marker check, project-first selection with override/custom notes (ADR-16), unknown-task guidance, and dispatch to the chosen task script. This is the structural move; behaviour is preserved (the bats acceptance tests from ADR-16 stay green and are joined by Spock unit tests around the launcher).

Alternatives considered:

Quality Tradeoffs:

Consequences: The v4 dispatch in dtcw (the ADR-16 resolution, listing, and notes) has moved into scripts/Launcher.groovy, with the pure logic in scripts/lib/TaskLauncher.groovy (IOSP: Operation vs Integration) and unit tests in scripts/lib/TaskLauncherTest.groovy. The Bash wrapper now only validates the task-name format, enforces the docker relative-path constraint, and invokes groovy.ui.GroovyMain …​/Launcher.groovy <task> <args>. The launcher runs the resolved task script in the same JVM via GroovyShell; dtc.scriptsHome (ADR-17) lets that script load its lib/ helpers regardless of where it lives. ADR-16’s user-visible behaviour is preserved; the bats suite now asserts the wrapper delegates (java is mocked there), while discovery/resolution/listing are covered by TaskLauncherTest. This decision does not change ADR-13 (thin dtcw4 → installed wrapper) or ADR-17 (dtc.scriptsHome), which already live in Groovy. A consequence is that dtcw tasks and unknown-task errors now start the JVM (no separate process — the launcher runs in the JVM started for the task); acceptable since QS-9 targets task runs, not listing. Wiring dtcw.ps1/dtcw.bat to the same launcher — closing the "No v4 Windows wrapper path" debt in [section-technical-risks] — is the remaining follow-up.

Status: Proposed (deferred — decide when Confluence publishing is reworked)

Context: Two parallel Confluence client implementations (V1 for Server, V2 for Cloud). Lower priority in the LLM era — documentation increasingly consumed via daCLI/MCP rather than pushed to Confluence.

Status: Proposed (deferred — decide when Jira integration is reworked)

Context: Only JiraServerClient exists. Lower priority — LLMs can query Jira directly via MCP tools, reducing the need for batch export scripts.