* 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
@@ -11,6 +11,20 @@ import path from 'node:path';
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import ioMod = require('./io.cjs');
|
||||
const { output, error, ERROR_REASON } = ioMod;
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import planDocumentMod = require('./plan-document.cjs');
|
||||
const { parsePlanDocument } = planDocumentMod;
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import capabilityLoaderMod = require('./capability-loader.cjs');
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import taskContentResolutionMod = require('./task-content-resolution.cjs');
|
||||
const {
|
||||
resolveTaskContent,
|
||||
ResolverAmbiguousError,
|
||||
ResolverFailedError,
|
||||
ResolverTimeoutError,
|
||||
ResolverMalformedOutputError,
|
||||
} = taskContentResolutionMod;
|
||||
|
||||
// ─── Types ────────────────────────────────────────────────────────────────────
|
||||
|
||||
@@ -32,6 +46,26 @@ interface RouteTaskCommandOptions {
|
||||
raw: boolean;
|
||||
}
|
||||
|
||||
interface PlanTaskLike {
|
||||
trackerId: string | null;
|
||||
}
|
||||
|
||||
interface CapabilityLike {
|
||||
id: string;
|
||||
taskContentResolver?: unknown;
|
||||
}
|
||||
|
||||
/**
|
||||
* Testability seam for `routeResolveContent` (mirrors this codebase's other
|
||||
* routers' `_`-prefixed injection convention, e.g.
|
||||
* `refactor-trigger-command-router.cts`'s `_git`/`_windows`/`_core`).
|
||||
* Production callers omit both fields.
|
||||
*/
|
||||
interface ResolveContentDeps {
|
||||
loadCapabilities?: (cwd: string) => CapabilityLike[];
|
||||
resolveTaskContentFn?: typeof resolveTaskContent;
|
||||
}
|
||||
|
||||
// ─── Implementation ───────────────────────────────────────────────────────────
|
||||
|
||||
function isBehaviorAddingTaskContent(content: string): BehaviorAddingResult {
|
||||
@@ -75,10 +109,127 @@ function isBehaviorAddingTaskContent(content: string): BehaviorAddingResult {
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Default (production) capability loader for `resolve-content`: the merged
|
||||
* first-party + validated-installed-overlay registry (ADR-1244 D2), the
|
||||
* established runtime read path for "installed capabilities including
|
||||
* third-party" — as opposed to `capability-loader.cts`'s heavier build-time
|
||||
* validation entry points or the static `capability-registry.cjs` alone
|
||||
* (first-party only, would miss a third-party capability's
|
||||
* `taskContentResolver` declaration entirely).
|
||||
*/
|
||||
function defaultLoadCapabilities(cwd: string): CapabilityLike[] {
|
||||
const registry = capabilityLoaderMod.loadRegistry({ includeInstalled: true, cwd }) as {
|
||||
capabilities?: Record<string, CapabilityLike>;
|
||||
};
|
||||
return Object.values(registry.capabilities ?? {});
|
||||
}
|
||||
|
||||
function parseResolveContentArgs(args: string[]): { plan: string | null; taskId: string | null } {
|
||||
let plan: string | null = null;
|
||||
let taskId: string | null = null;
|
||||
for (let i = 2; i < args.length; i++) {
|
||||
if (args[i] === '--plan') {
|
||||
plan = args[i + 1] ?? null;
|
||||
i++;
|
||||
} else if (args[i] === '--task-id') {
|
||||
taskId = args[i + 1] ?? null;
|
||||
i++;
|
||||
}
|
||||
}
|
||||
return { plan, taskId };
|
||||
}
|
||||
|
||||
/**
|
||||
* `task resolve-content --plan <PLAN.md path> --task-id <tracker-id value> --raw`
|
||||
* (ADR-3646 Decision 2). Resolves one task's content from the external
|
||||
* tracker its `tracker-id` attribute names, via `task-content-resolution.cts`.
|
||||
*
|
||||
* HARD-HALT CONTRACT: a thrown `ResolverAmbiguousError` / `ResolverFailedError`
|
||||
* / `ResolverTimeoutError` / `ResolverMalformedOutputError` from
|
||||
* `resolveTaskContent` is turned into this CLI's own non-zero exit via
|
||||
* `error()` — never swallowed into a `{resolved: false}` JSON answer. Any
|
||||
* other thrown error is not one of the four documented resolver-error
|
||||
* classes and is allowed to propagate uncaught.
|
||||
*/
|
||||
function routeResolveContent(
|
||||
{ args, cwd, raw }: RouteTaskCommandOptions,
|
||||
deps: ResolveContentDeps = {},
|
||||
): void {
|
||||
const usage = 'Usage: task resolve-content --plan <path> --task-id <tracker-id> --raw';
|
||||
const { plan, taskId } = parseResolveContentArgs(args);
|
||||
if (!plan || !taskId) {
|
||||
error(usage, ERROR_REASON.USAGE);
|
||||
return;
|
||||
}
|
||||
|
||||
const projectRoot = path.resolve(cwd || process.cwd());
|
||||
const resolvedPlanPath = path.resolve(projectRoot, plan);
|
||||
const rel = path.relative(projectRoot, resolvedPlanPath);
|
||||
if (rel === '..' || rel.startsWith(`..${path.sep}`)) {
|
||||
error(`Plan file is outside project scope: ${plan}`, ERROR_REASON.USAGE);
|
||||
return;
|
||||
}
|
||||
if (!fs.existsSync(resolvedPlanPath)) {
|
||||
error(`Plan file not found: ${plan}`, ERROR_REASON.USAGE);
|
||||
return;
|
||||
}
|
||||
|
||||
const planContent = fs.readFileSync(resolvedPlanPath, 'utf-8');
|
||||
const parsedPlan = parsePlanDocument(planContent, resolvedPlanPath) as { tasks?: PlanTaskLike[] };
|
||||
const task = (parsedPlan.tasks ?? []).find((t) => t.trackerId === taskId);
|
||||
if (!task) {
|
||||
error(`No task with tracker-id '${taskId}' found in plan: ${plan}`, ERROR_REASON.USAGE);
|
||||
return;
|
||||
}
|
||||
|
||||
const loadCapabilities = deps.loadCapabilities ?? defaultLoadCapabilities;
|
||||
const capabilities = loadCapabilities(projectRoot);
|
||||
const resolveFn = deps.resolveTaskContentFn ?? resolveTaskContent;
|
||||
|
||||
let result;
|
||||
try {
|
||||
result = resolveFn({ trackerId: task.trackerId, capabilities });
|
||||
} catch (err) {
|
||||
if (
|
||||
err instanceof ResolverAmbiguousError ||
|
||||
err instanceof ResolverFailedError ||
|
||||
err instanceof ResolverTimeoutError ||
|
||||
err instanceof ResolverMalformedOutputError
|
||||
) {
|
||||
error((err as Error).message, ERROR_REASON.UNKNOWN);
|
||||
return;
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
|
||||
switch (result.kind) {
|
||||
case 'not-applicable':
|
||||
output({ resolved: false }, raw, undefined);
|
||||
return;
|
||||
case 'no-resolver':
|
||||
output({ resolved: false, reason: 'no-resolver' }, raw, undefined);
|
||||
return;
|
||||
case 'empty':
|
||||
output({ resolved: false, reason: 'empty' }, raw, undefined);
|
||||
return;
|
||||
case 'resolved':
|
||||
output({ resolved: true, content: result.content }, raw, undefined);
|
||||
return;
|
||||
}
|
||||
}
|
||||
|
||||
function routeTaskCommand({ args, cwd, raw }: RouteTaskCommandOptions): void {
|
||||
const subcommand = args[1];
|
||||
if (subcommand === 'resolve-content') {
|
||||
routeResolveContent({ args, cwd, raw });
|
||||
return;
|
||||
}
|
||||
if (subcommand !== 'is-behavior-adding') {
|
||||
error('Unknown task subcommand. Available: is-behavior-adding', ERROR_REASON.SDK_UNKNOWN_COMMAND);
|
||||
error(
|
||||
'Unknown task subcommand. Available: is-behavior-adding, resolve-content',
|
||||
ERROR_REASON.SDK_UNKNOWN_COMMAND,
|
||||
);
|
||||
}
|
||||
|
||||
let content: string | null = null;
|
||||
@@ -108,4 +259,5 @@ function routeTaskCommand({ args, cwd, raw }: RouteTaskCommandOptions): void {
|
||||
export = {
|
||||
isBehaviorAddingTaskContent,
|
||||
routeTaskCommand,
|
||||
routeResolveContent,
|
||||
};
|
||||
|
||||
Reference in New Issue
Block a user