* 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>
This commit is contained in:
Tom Boucher
@@ -693,6 +693,43 @@ walkthrough: [Consume the planning snapshot](how-to/consume-the-planning-snapsho
|
||||
|
||||
---
|
||||
|
||||
### `task resolve-content --plan <path> --task-id <id> --raw`
|
||||
|
||||
Resolves one task's content (`action`/`verify`/`acceptance_criteria`/`read_first`/`done`) from an
|
||||
external issue tracker instead of reading it inline from a task's `PLAN.md` body. Called by
|
||||
`execute-plan.md`'s per-task loop, once per task carrying a `tracker-id` attribute, before that
|
||||
task's read_first gate. See [ADR-3646](adr/3646-per-task-content-resolution-seam.md) and
|
||||
[Develop a task-content resolver capability](how-to/develop-a-task-content-resolver-capability.md).
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `--plan` | **Yes** | Path to the `PLAN.md` the task belongs to |
|
||||
| `--task-id` | **Yes** | The task's `tracker-id` attribute value, e.g. `beads:GSD-42` |
|
||||
| `--raw` | No | Machine-readable JSON output |
|
||||
|
||||
**Exit codes:**
|
||||
|
||||
| Exit | Meaning |
|
||||
|------|---------|
|
||||
| `0` | Resolution attempted (or not needed) — see `resolved`/`reason` below |
|
||||
| non-zero | **Hard halt.** A resolver was found and invoked but failed (tracker unreachable, id not found, timeout, malformed JSON output). stderr names the tracker-id, the tracker prefix, and the resolver's error. Never fall back to inline `PLAN.md` content on this outcome. |
|
||||
|
||||
**Output fields (JSON, exit 0 only):**
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `resolved` | `boolean` | `true` only when a resolver was found, invoked, and returned non-empty content |
|
||||
| `reason` | `string` | Present when `resolved` is `false`: `"no-resolver"` (task has a `tracker-id` but no installed capability declares a matching `trackerPrefix`) or `"empty"` (the resolver ran successfully but returned empty/absent content — the one legitimate pre-migration fallback case) |
|
||||
| `content` | `object` | Present when `resolved` is `true`. Supersedes this task's inline `<action>`/`<verify>`/`<acceptance_criteria>`/`<read_first>`/`<done>` for every downstream gate in the execute step |
|
||||
|
||||
```bash
|
||||
node gsd-tools.cjs task resolve-content --plan .planning/phases/03-name/03-1-PLAN.md --task-id beads:GSD-42 --raw
|
||||
```
|
||||
|
||||
`execute-plan.md` only invokes this command when the task carries a `tracker-id` attribute; a task with no `tracker-id` is unaffected.
|
||||
|
||||
---
|
||||
|
||||
## Navigation Commands
|
||||
|
||||
### `/gsd-next`
|
||||
|
||||
@@ -204,6 +204,7 @@
|
||||
- [Hooks Declare Their Crash Policy](#3911-hooks-declare-their-crash-policy)
|
||||
- [gsd-tools Declares Outcomes, Pinned at v1](#3912-gsd-tools-declares-outcomes-pinned-at-v1)
|
||||
- [Reachable Lint Rules and a Non-Destructive Quick-Task Append](#3951-reachable-lint-rules-and-a-non-destructive-quick-task-append)
|
||||
- [Per-Task External-Tracker Content-Resolution Seam](#3970-per-task-external-tracker-content-resolution-seam)
|
||||
|
||||
---
|
||||
|
||||
@@ -4142,6 +4143,47 @@ regressing to the old seconds-based default had been inert. It is now row-scoped
|
||||
|
||||
---
|
||||
|
||||
### 3970. Per-Task External-Tracker Content-Resolution Seam
|
||||
|
||||
**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.
|
||||
|
||||
---
|
||||
|
||||
_Generated by `scripts/gen-features.cjs` — add a fragment under `docs/features/` and run `--write`._
|
||||
|
||||
<!-- FEATURES:END -->
|
||||
|
||||
@@ -515,6 +515,7 @@
|
||||
"state.cjs",
|
||||
"surface.cjs",
|
||||
"task-command-router.cjs",
|
||||
"task-content-resolution.cjs",
|
||||
"teams-status.cjs",
|
||||
"template.cjs",
|
||||
"text-lines.cjs",
|
||||
|
||||
@@ -646,7 +646,8 @@ Full listing: `gsd-core/bin/lib/*.cjs`.
|
||||
| `state-document.cjs` | Pure STATE.md field extraction, replacement, status normalization, and progress calculation transforms |
|
||||
| `milestone-lock.cjs` | Milestone lock (compiled from `src/milestone-lock.cts`, gitignored) — advisory (phase, session id) claim over STATE.md's single Current Position slot: `.planning/milestone.lock` claim IO, liveness (TTL + heartbeat), conflict detection, and the shared stderr warning; consumed by `state.begin-phase` / `state.advance-plan` / `phase.complete` so parallel phases in one working tree get a visible conflict instead of silently overwriting each other (#3311) |
|
||||
| `surface.cjs` | Runtime surface module — manages the runtime enable/disable surface state independently of the install-time profile marker (ADR-0011 Phase 2) |
|
||||
| `task-command-router.cjs` | Thin CJS subcommand router adapter for `gsd-tools task` |
|
||||
| `task-command-router.cjs` | Thin CJS subcommand router adapter for `gsd-tools task`; `resolve-content` subcommand resolves a task's `tracker-id` via `task-content-resolution.cjs` (ADR-3646, #3970) |
|
||||
| `task-content-resolution.cjs` | Resolves a task's `tracker-id` to external-tracker content via a capability-declared `taskContentResolver` and a bounded subprocess call; hard-halts on ambiguous/failed/timeout/malformed resolution (compiled from `src/task-content-resolution.cts`, gitignored) (ADR-3646, #3970) |
|
||||
| `teams-status.cjs` | Detects agent-teams status from environment and runtime; pure core (#1355) |
|
||||
| `template.cjs` | Template selection and filling with variable substitution |
|
||||
| `text-lines.cjs` | Line-terminator handling seam — `splitLines`/`normalizeEol`/`detectEol`/`joinLines`, the sole owner of `\r?\n` splitting and CRLF normalization; closes #3360's split-then-match fix in `frontmatter.cjs` (ADR-3212 §3, epic #3212 Phase 2, #3413) |
|
||||
|
||||
@@ -64,6 +64,7 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md)
|
||||
- [Design a UI phase](how-to/design-a-ui-phase.md) — use the UI phase loop for frontend and visual work
|
||||
- [Enable live-DOM verification](how-to/enable-live-dom-verification.md) — opt a project into browser-backed UI acceptance checks during execution, handle the browser-profile lock, and tell "nothing to report" apart from "could not look"
|
||||
- [Develop a Capability for GSD 1.5+](how-to/develop-a-capability.md) — add feature Capabilities, hook fragments, and registry entries
|
||||
- [Develop a task-content resolver capability](how-to/develop-a-task-content-resolver-capability.md) — declare a `taskContentResolver` so `execute-plan.md` resolves per-task content from your external issue tracker instead of `PLAN.md`
|
||||
- [Ship a reviewer lane in your capability](how-to/ship-a-reviewer-lane.md) — declare a `reviewer` body so `/gsd-review` discovers, invokes, and renders your external review CLI or model endpoint
|
||||
- [List your reviewer lane in the registry](how-to/list-your-reviewer-lane.md) — publish a lane you have built to the Reviewer Lane Registry so other people can find and install it
|
||||
- [Take over a capability or EoS integration](how-to/take-over-a-capability-or-eos.md) — assume maintainership of an existing third-party capability, reviewer lane, or EoS host integration through a handoff, an adoption fork, first-party absorption, or a de-listing
|
||||
|
||||
42
docs/features/task-content-resolution-seam.md
Normal file
42
docs/features/task-content-resolution-seam.md
Normal file
@@ -0,0 +1,42 @@
|
||||
---
|
||||
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.
|
||||
172
docs/how-to/develop-a-task-content-resolver-capability.md
Normal file
172
docs/how-to/develop-a-task-content-resolver-capability.md
Normal file
@@ -0,0 +1,172 @@
|
||||
# Develop a task-content resolver capability
|
||||
|
||||
**Goal:** Declare a `taskContentResolver` in a capability manifest so `execute-plan.md` resolves
|
||||
a task's `<action>`/`<verify>`/`<acceptance_criteria>`/`<read_first>`/`<done>` content from your
|
||||
external issue tracker instead of reading it inline from `PLAN.md`.
|
||||
|
||||
**Prerequisites:** You already have a capability (`capability.json`), or you are creating one —
|
||||
see [Develop a Capability for GSD 1.5+](develop-a-capability.md) first if this is your first one.
|
||||
GSD 1.28 or later ([ADR-3646](../adr/3646-per-task-content-resolution-seam.md)).
|
||||
|
||||
---
|
||||
|
||||
## Why this exists
|
||||
|
||||
A project that wants an external tracker — beads, Linear, Jira, GitHub Issues — to own task
|
||||
*content*, not just task *status*, has no seam for that today: `execute-plan.md` reads every
|
||||
task's instructions directly out of the `PLAN.md` task block. `taskContentResolver` adds one, with
|
||||
a hard-halt guarantee: if your tracker is declared as the source of truth and it fails to resolve,
|
||||
execution stops rather than silently falling back to stale `PLAN.md` text. That guarantee is the
|
||||
entire point of the feature — a silent fallback would require the tracker and `PLAN.md` to stay in
|
||||
sync forever, defeating the reason to move content out of `PLAN.md` in the first place.
|
||||
|
||||
---
|
||||
|
||||
## Declare the resolver
|
||||
|
||||
Add a `taskContentResolver` block to your capability's manifest body (`role: "feature"` only):
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "beads",
|
||||
"role": "feature",
|
||||
"version": "1.0.0",
|
||||
"title": "Beads issue tracker",
|
||||
"description": "Resolves task content from the bd issue tracker.",
|
||||
"tier": "standard",
|
||||
"requires": [],
|
||||
"runtimeCompat": { "supported": ["*"], "unsupported": [] },
|
||||
"skills": [],
|
||||
"agents": [],
|
||||
"hooks": [],
|
||||
"config": {},
|
||||
"steps": [],
|
||||
"contributions": [],
|
||||
"gates": [],
|
||||
|
||||
"taskContentResolver": {
|
||||
"trackerPrefix": "beads",
|
||||
"invoke": {
|
||||
"binary": "bd",
|
||||
"args": ["show", "{{id}}", "--json"],
|
||||
"timeoutMs": 10000
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Two fields decide whether the seam works at all:
|
||||
|
||||
- **`trackerPrefix`** must match the prefix of a task's `tracker-id` attribute — everything
|
||||
before the **first** `:`. Given `<task tracker-id="beads:GSD-42">`, the prefix is `beads` and
|
||||
the id passed to your resolver is `GSD-42`. If a tracker's own ids contain colons, that is fine:
|
||||
only the first colon splits prefix from id, so `beads:team:GSD-42` resolves to id `team:GSD-42`.
|
||||
- **`invoke.args`** must contain the `{{id}}` placeholder at least once — GSD substitutes it with
|
||||
the task's id before spawning your binary. A declaration whose `args` never carries the
|
||||
placeholder fails validation at install time, because the id could never reach your resolver.
|
||||
|
||||
`invoke.timeoutMs` is required. An unbounded resolver subprocess is this repo's named Unbounded
|
||||
Subprocesses defect class — declare a bound that matches how long your tracker's lookup actually
|
||||
takes, plus margin.
|
||||
|
||||
`trackerPrefix` must be unique across the merged first-party ∪ overlay capability set; a
|
||||
collision — two installed capabilities both claiming `"beads"` — is a build-time validation
|
||||
error, not a runtime ambiguity.
|
||||
|
||||
---
|
||||
|
||||
## What your resolver must output
|
||||
|
||||
`execute-plan.md` invokes your `invoke.binary`/`invoke.args` and expects a single JSON object on
|
||||
stdout when the lookup succeeds:
|
||||
|
||||
| Field | Type | Required | Maps to |
|
||||
|---|---|---|---|
|
||||
| `description` | string | Yes | The task's `<action>` |
|
||||
| `verify` | string | No | The task's `<verify>` |
|
||||
| `acceptance_criteria` | string[] | No | The task's `<acceptance_criteria>` |
|
||||
| `read_first` | string[] | No | The task's `<read_first>` |
|
||||
| `done` | string | No | The task's `<done>` |
|
||||
|
||||
An absent or empty-string `description` is treated as "nothing resolved" — `execute-plan.md`
|
||||
falls back to the task's inline `PLAN.md` content, the one legitimate pre-migration boundary case
|
||||
(for tasks authored before your tracker migration). This is the *only* silent fallback path; every
|
||||
other failure is a hard halt.
|
||||
|
||||
**Exit code and stderr matter.** Exit `0` with valid JSON on stdout is the only success path.
|
||||
Anything else — a non-zero exit, a timeout past `invoke.timeoutMs`, or stdout that fails to parse
|
||||
as JSON — is treated as a resolution failure. Write a clear one-line reason to stderr; it is
|
||||
surfaced verbatim to the person watching execution. Stderr on a **successful** (exit 0) run is not
|
||||
an error — write informational logs there if your CLI already does; only the exit code and the
|
||||
JSON parse outcome decide success.
|
||||
|
||||
---
|
||||
|
||||
## What happens on failure
|
||||
|
||||
A resolver that is declared, invoked, and fails — non-zero exit, timeout, or malformed JSON —
|
||||
makes `gsd_run task resolve-content` itself exit non-zero. `execute-plan.md` treats that as a
|
||||
**hard halt**: it stops before doing any work on the task, surfaces the tracker-id, the tracker
|
||||
prefix, and your resolver's stderr, and never proceeds to read the task's inline `PLAN.md` content
|
||||
as a substitute. See [ADR-3646](../adr/3646-per-task-content-resolution-seam.md) for why this is
|
||||
the load-bearing safety property of the whole feature, and
|
||||
[`loop-hook-dispatch.md`](../../gsd-core/references/loop-hook-dispatch.md#the-executetask-point-a-different-shape)
|
||||
for how this call site differs from the twelve prose-dispatched loop extension points.
|
||||
|
||||
---
|
||||
|
||||
## Worked example: a `bd`/beads-shaped resolver
|
||||
|
||||
Suppose `bd show GSD-42 --json` already returns:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "GSD-42",
|
||||
"title": "Add rate-limit check to login",
|
||||
"status": "open",
|
||||
"description": "Add a rate-limit check to processLogin using the existing RateLimiter.",
|
||||
"acceptance": [
|
||||
"Login attempts beyond the configured limit return 429",
|
||||
"Existing successful-login tests still pass"
|
||||
],
|
||||
"notes": "See src/util/rate.ts for the existing limiter."
|
||||
}
|
||||
```
|
||||
|
||||
Your resolver is a thin adapter, not `bd` itself — it maps `bd`'s field names onto the shape
|
||||
`execute-plan.md` expects and exits non-zero on anything `bd` itself reports as a failure:
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
id="$1"
|
||||
raw=$(bd show "$id" --json)
|
||||
|
||||
node -e '
|
||||
const raw = JSON.parse(process.argv[1]);
|
||||
const out = {
|
||||
description: raw.description || "",
|
||||
acceptance_criteria: raw.acceptance || [],
|
||||
};
|
||||
process.stdout.write(JSON.stringify(out));
|
||||
' "$raw"
|
||||
```
|
||||
|
||||
Declare it as the `invoke.binary`/`invoke.args` pair (or point `invoke.binary` at `bd` directly if
|
||||
its own `--json` output already matches the expected field names — no adapter needed in that
|
||||
case). Either way, `invoke.args` must carry `{{id}}` so GSD can substitute the task's tracker id
|
||||
before spawning it.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [ADR-3646](../adr/3646-per-task-content-resolution-seam.md) — the design decision and rejected
|
||||
alternatives
|
||||
- [Capability manifest → `taskContentResolver`](../reference/capability-manifest.md#taskcontentresolver) —
|
||||
the full field table
|
||||
- [`loop-hook-dispatch.md`](../../gsd-core/references/loop-hook-dispatch.md#the-executetask-point-a-different-shape) —
|
||||
how `execute:task` differs from the twelve loop extension points
|
||||
- [Develop a Capability for GSD 1.5+](develop-a-capability.md) — manifests, registry generation,
|
||||
and federated config
|
||||
@@ -117,6 +117,28 @@ Gates check a condition at a loop extension point and optionally block progressi
|
||||
| Predicate | `{ "predicate": { "kind": "artifact-exists" \| "config-equals" \| …, … } }` | Yes | Declarative; no code path. |
|
||||
| Agent verdict | `{ "agentVerdict": { "ref": …, "prompt": … } }` | No (forced advisory) | LLM evaluation; non-deterministic checks may not halt the loop. |
|
||||
|
||||
### `taskContentResolver`
|
||||
|
||||
Declares that this capability resolves per-task content (`<action>`/`<verify>`/
|
||||
`<acceptance_criteria>`/`<read_first>`/`<done>`) from an external issue tracker instead of
|
||||
`execute-plan.md`'s per-task loop reading it inline from a task's `PLAN.md` body. This is **not**
|
||||
one of `steps` / `contributions` / `gates`, and it does not use a `point` value from the closed
|
||||
12-point vocabulary above — it is dispatched directly, once per task, by `execute-plan.md` before
|
||||
that task's `read_first` gate, documented separately in
|
||||
[`loop-hook-dispatch.md`](../../gsd-core/references/loop-hook-dispatch.md#the-executetask-point-a-different-shape).
|
||||
See [ADR-3646](../adr/3646-per-task-content-resolution-seam.md) for the full design and
|
||||
[Develop a task-content resolver capability](../how-to/develop-a-task-content-resolver-capability.md)
|
||||
for the authoring walkthrough.
|
||||
|
||||
| Sub-field | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `trackerPrefix` | string (kebab-case) | Yes | Matches the prefix of a task's `<task tracker-id="beads:GSD-42">` attribute — everything before the **first** `:`. Text after the first colon, including further colons, is passed through verbatim as the id. Must be unique across the merged first-party ∪ overlay capability set. |
|
||||
| `invoke.binary` | string | Yes | Executable name or path for the resolver subprocess. |
|
||||
| `invoke.args` | string[] | Yes | Argv passed to `invoke.binary`. Must contain the `{{id}}` placeholder at least once — GSD substitutes it with the task's tracker id (everything after the first `:`); an `args` array that never carries the placeholder fails validation, since the id could never reach the resolver. |
|
||||
| `invoke.timeoutMs` | number | Yes | Bound on the subprocess invocation. Required — an unbounded resolver subprocess is this repo's named Unbounded Subprocesses defect class. A resolver exceeding this bound is killed and `task resolve-content` exits non-zero. |
|
||||
|
||||
`taskContentResolver` is feature-role only (`role: "feature"`); it is not admissible on `role: "runtime"` or `role: "reviewer"` bodies.
|
||||
|
||||
---
|
||||
|
||||
## Valid `point` values
|
||||
@@ -289,6 +311,7 @@ The following invariants are enforced at **build time** by `scripts/gen-capabili
|
||||
- **`engines.gsd` is a hard gate.** A capability whose `engines.gsd` range does not satisfy the installed GSD version is blocked at install and skipped (with a warning) at load time.
|
||||
- **Path confinement.** Declared module paths may not use parent-directory traversal (`../`); modules are `require()`'d only from the capability's own install root.
|
||||
- **Reserved namespace.** Capability `id` values beginning with `gsd-`, `gsd-core-`, or `anthropic-` are reserved; third-party capabilities using these prefixes are rejected.
|
||||
- **`taskContentResolver.trackerPrefix` uniqueness, feature-only.** `trackerPrefix` must be unique across the merged first-party ∪ overlay capability set (mirrors `reviewsSection` uniqueness on the reviewer body above); a collision is a build-time violation. `taskContentResolver` is admissible only on `role: "feature"` bodies.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user