dd4f179672
* feat(#3970): per-task external-tracker content-resolution seam Implements ADR-3646 (Phase 1, #3970): a `<task tracker-id="...">` attribute plus a new optional `taskContentResolver` capability-manifest field let a capability resolve a task's action/verify/acceptance-criteria/read_first/done content from an external issue tracker instead of PLAN.md's inline body. - src/plan-document.cts: parses the `tracker-id` attribute into `PlanTask.trackerId` - src/task-content-resolution.cts: new leaf module — split/find/build/resolve, with a hard-halt (throw) contract on ambiguous/failed/timeout/malformed resolution, never a silent fallback to possibly-stale inline text - src/task-command-router.cts: new `task resolve-content --plan --task-id --raw` CLI verb wiring the module into a real process exit code - gsd-core/bin/lib/capability-validator.cjs: validates the new `taskContentResolver` manifest field (feature-role only, cross-capability trackerPrefix uniqueness) - gsd-core/workflows/execute-plan.md, gsd-core/references/loop-hook-dispatch.md, docs/reference/capability-manifest.md: wire the seam into the per-task loop and document it as a new `execute:task` point outside the existing contribution/step/gate vocabulary (unconditional in autonomous mode) Closes #3970 * fix(#3970): gate checkpoint tasks out of content resolution, close trackerPrefix grammar parity gap, cover path-traversal guard Standards/Spec code-review pass on the task-content-resolution seam (ADR-3646 Phase 1) found three defects: 1. execute-plan.md's task-content-resolution bullet fired on any tracker-id-bearing task with no check that it wasn't type="checkpoint:*", contradicting ADR-3646 Decision 1 (a checkpoint task must never enter resolve-content). plan-document.cts already parses trackerId: null unconditionally for checkpoint tasks; only the workflow prose needed the fix, so the bullet now explicitly excludes checkpoint tasks. 2. task-content-resolution.cts's parseResolverDeclaration accepted any non-empty trackerPrefix with no grammar check, while capability- validator.cjs's KEBAB_RE enforces kebab-case at install time — a Generative Fix Divergence gap. Added the same grammar (as a literal regex, documented as intentionally not shared across the .cts/.cjs build boundary) plus a parity test asserting the two surfaces agree across a valid/invalid trackerPrefix table. 3. task-command-router.cts's routeResolveContent path-traversal guard on --plan had zero test coverage. Added a test exercising a ../../../etc/passwit-shaped path and asserting the USAGE rejection names the offending path. * fix(#3970): sanitize resolver diagnostics and cap resolver timeoutMs Two findings caught by an isolated security-review pass on the task content resolution seam: - ResolverFailedError/ResolverMalformedOutputError embedded raw, unsanitized subprocess stderr/stdout (attacker/model-influenced via the tracker-id argv token) into .message. A hostile or buggy resolver could smuggle a newline plus a forged "Error: " line, or terminal escape sequences, into a diagnostic io.cjs's error() writes verbatim to stderr. Fixed at the constructor (task-content-resolution.cts) via io.cjs's existing formatDiagnosticToken(), so every caller of resolveTaskContent gets a safe .message by construction. - capability-validator.cjs's validateTaskContentResolverFields had no upper bound on taskContentResolver.invoke.timeoutMs, letting a manifest declare an effectively unbounded value and defeat the "bounded subprocess" design intent. Added a 120000ms ceiling specific to this field, without touching the shared isPositiveIntegerMs() helper (still used unbounded by the reviewer lane's timeoutFloorMs and probe timeoutMs). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix(#3970): fix gsd-test failures — stale prose allowlist line and stderr-vs-message assertion gsd-test (remote dockerized matrix) came back red with 5 failures on this PR; all five are real defects, fixed here. - tests/no-bare-gsd-tools-command-position.test.cjs: PROSE_ALLOWLIST's execute-plan.md entry pointed at line 415, which ffc190df4's checkpoint-exclusion caveat (added near line 221) shifted down by one line. The actual "validated downstream by gsd-tools uat classify-coverage" descriptive mention now sits at line 416. Updated the allowlist entry's line number to match. - tests/task-command-router-resolve-content.test.cjs: the path-traversal test asserted the outside-project-scope diagnostic against the thrown ExitError's own .message. io.cts's error() (ADR-3889) writes its human-readable message to fd 2 via writeAllSync and then throws a bare `new ExitError(1)` with no message argument — by design, so the exception carries no duplicate text and the thrown ExitError's message defaults to "process exit 1" (cli-exit.cts's ExitError constructor). Root cause was the test, not the source: task-command-router.cjs's outside-project-scope rejection already calls error() correctly and the diagnostic text is genuinely emitted, just on fd 2, not on the exception. Fixed the test to capture fd-2 writes (mirroring tests/estimate-calibrate.test.cjs's runCalibrateExpectError and this same file's own captureStdout for fd 1) and assert against the captured stderr text instead of err.message. This was masked locally because a manual `node -e` sanity check that only inspects the caught exception's .message cannot see what the real node:test run actually failed on. Emitted-Drift-Ack-Growth: execute-plan.md — adds the ADR-3646 task-content-resolution bullet and checkpoint-exclusion caveat to the per-task execute loop; a real behavioral prose addition, not incidental bloat. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * docs(#3970): backfill changeset PR number (pr:0 -> pr:4000) --------- Co-authored-by: sim <sim@local> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
43 lines
2.8 KiB
Markdown
43 lines
2.8 KiB
Markdown
---
|
|
id: 3970
|
|
title: Per-Task External-Tracker Content-Resolution Seam
|
|
group: v1.7.0 Features
|
|
---
|
|
|
|
**Purpose:** Let a capability declare that an external issue tracker — beads, Linear, Jira,
|
|
GitHub Issues — owns a task's *content* (`<action>`/`<verify>`/`<acceptance_criteria>`/
|
|
`<read_first>`/`<done>`), not just its status, so `execute-plan.md` can resolve that content
|
|
from the tracker at execution time instead of reading it inline out of `PLAN.md`.
|
|
|
|
**What changed (ADR-3646, #3970):**
|
|
|
|
- A new optional feature-body manifest field, `taskContentResolver`, declares a `trackerPrefix`
|
|
(matched against a task's `<task tracker-id="beads:GSD-42">` attribute — everything before the
|
|
first `:`) and a bounded `invoke` (`binary`, `args` carrying the `{{id}}` placeholder,
|
|
`timeoutMs`).
|
|
- `execute-plan.md`'s per-task loop gains one new, unconditional call before that task's
|
|
`read_first` gate: `gsd_run task resolve-content --plan <path> --task-id <tracker-id> --raw`.
|
|
A task with no `tracker-id` attribute is unaffected — the call is only made when the attribute
|
|
is present, and resolves instantly to a no-op for every project that declares none.
|
|
- **The safety property is a real process exit code, not a prose dispatch.** No capability
|
|
registered for the tracker, or resolution succeeds with empty content, exits `0` with
|
|
`resolved: false` and falls back to inline `PLAN.md` — the one legitimate pre-migration
|
|
boundary case. Resolution succeeding with non-empty content exits `0` with `resolved: true` and
|
|
its `content` supersedes the task's inline fields for every downstream gate in the execute step.
|
|
A resolver that is declared but fails — tracker unreachable, id not found, timeout, malformed
|
|
JSON — makes `task resolve-content` itself **exit non-zero**, which `execute-plan.md` treats as
|
|
a **hard halt**: stop, surface the tracker-id/prefix/stderr, never fall back to stale
|
|
`PLAN.md` content.
|
|
- `execute:task` is a new dispatch shape below wave granularity, deliberately **not** one of the
|
|
12 existing loop extension points (`discuss:pre` … `ship:post`) and not routed through
|
|
`gsd_run loop render-hooks <point>` / `activeHooks`. It exists because the existing
|
|
`step`/`gate` prose-dispatch mechanism cannot deliver a hard-halt guarantee while dispatch
|
|
reliability at that layer is an open concern (#3647) — see ADR-3646's Context and Rejected
|
|
Alternatives for the full reasoning.
|
|
|
|
See [Develop a task-content resolver capability](../how-to/develop-a-task-content-resolver-capability.md)
|
|
for the authoring walkthrough, [Capability manifest → `taskContentResolver`](../reference/capability-manifest.md#taskcontentresolver)
|
|
for the field reference, and
|
|
[`loop-hook-dispatch.md`](../../gsd-core/references/loop-hook-dispatch.md#the-executetask-point-a-different-shape)
|
|
for how `execute:task` differs from the twelve prose-dispatched points.
|