agentplane 0.2.19 → 0.2.21

package/dist/commands/task/shared.js

@@ -9,6 +9,7 @@ import { exitCodeForError } from "../../cli/exit-codes.js";
 import { CliError } from "../../shared/errors.js";
 import { dedupeStrings } from "../../shared/strings.js";
 import { parseGitLogHashSubject } from "../../shared/git-log.js";
+import { isRecord } from "../../shared/guards.js";
 export { dedupeStrings } from "../../shared/strings.js";
 export const execFileAsync = promisify(execFile);
 async function listAgentIdsMemo(ctx) {
@@ -87,6 +88,115 @@ export function requiresVerify(tags, requiredTags) {
         return false;
     return tags.some((tag) => required.has(tag.trim().toLowerCase()));
 }
+function readStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+function readBoolean(value, fallback) {
+    return typeof value === "boolean" ? value : fallback;
+}
+function readString(value, fallback) {
+    if (typeof value !== "string")
+        return fallback;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : fallback;
+}
+function configFromInput(input) {
+    return "config" in input ? input.config : input;
+}
+export function readTaskTagPolicy(input) {
+    const config = configFromInput(input);
+    const tasks = isRecord(config.tasks) ? config.tasks : {};
+    const rawTagsCandidate = tasks.tags;
+    const rawTags = isRecord(rawTagsCandidate) ? rawTagsCandidate : {};
+    const fallbackAllowlist = ["code", "data", "research", "docs", "ops", "product", "meta"];
+    const normalizedAllowlist = dedupeStrings(readStringArray(rawTags.primary_allowlist)
+        .map((tag) => tag.toLowerCase())
+        .filter(Boolean));
+    return {
+        primaryAllowlist: normalizedAllowlist.length > 0 ? normalizedAllowlist : fallbackAllowlist,
+        strictPrimary: readBoolean(rawTags.strict_primary, false),
+        fallbackPrimary: readString(rawTags.fallback_primary, "meta").toLowerCase(),
+        lockPrimaryOnUpdate: readBoolean(rawTags.lock_primary_on_update, true),
+    };
+}
+function readVerifyPrimaryPolicy(config) {
+    const tasks = isRecord(config.tasks) ? config.tasks : {};
+    const rawVerifyCandidate = tasks.verify;
+    const rawVerify = isRecord(rawVerifyCandidate)
+        ? rawVerifyCandidate
+        : {};
+    const explicitSteps = dedupeStrings(readStringArray(rawVerify.require_steps_for_primary)
+        .map((tag) => tag.toLowerCase())
+        .filter(Boolean));
+    const legacySteps = dedupeStrings(readStringArray(rawVerify.require_steps_for_tags ?? rawVerify.required_tags)
+        .map((tag) => tag.toLowerCase())
+        .filter(Boolean));
+    const requireStepsForPrimary = new Set(explicitSteps.length > 0 ? explicitSteps : legacySteps);
+    const explicitVerification = dedupeStrings(readStringArray(rawVerify.require_verification_for_primary)
+        .map((tag) => tag.toLowerCase())
+        .filter(Boolean));
+    const requireVerificationForPrimary = new Set(explicitVerification.length > 0 ? explicitVerification : [...requireStepsForPrimary.values()]);
+    return { requireStepsForPrimary, requireVerificationForPrimary };
+}
+export function resolvePrimaryTagFromConfig(tags, config) {
+    const policy = readTaskTagPolicy(config);
+    const allowlist = policy.primaryAllowlist;
+    if (allowlist.length === 0) {
+        throw new CliError({
+            exitCode: 3,
+            code: "E_VALIDATION",
+            message: "tasks.tags.primary_allowlist must contain at least one tag.",
+        });
+    }
+    const normalizedTags = dedupeStrings(tags.map((t) => t.trim().toLowerCase()).filter(Boolean));
+    const matched = normalizedTags.filter((tag) => allowlist.includes(tag));
+    if (matched.length > 1) {
+        throw new CliError({
+            exitCode: exitCodeForError("E_USAGE"),
+            code: "E_USAGE",
+            message: `Task must include exactly one primary tag from allowlist (${allowlist.join(", ")}); ` +
+                `found multiple: ${matched.join(", ")}`,
+        });
+    }
+    if (matched.length === 1) {
+        return { primary: matched[0], matched, usedFallback: false };
+    }
+    const strict = policy.strictPrimary;
+    if (strict) {
+        throw new CliError({
+            exitCode: exitCodeForError("E_USAGE"),
+            code: "E_USAGE",
+            message: `Task must include exactly one primary tag from allowlist (${allowlist.join(", ")}); ` +
+                "none found and strict_primary=true",
+        });
+    }
+    const fallback = policy.fallbackPrimary;
+    if (!fallback || !allowlist.includes(fallback)) {
+        throw new CliError({
+            exitCode: 3,
+            code: "E_VALIDATION",
+            message: `tasks.tags.fallback_primary=${JSON.stringify(policy.fallbackPrimary)} ` +
+                `must be present in tasks.tags.primary_allowlist (${allowlist.join(", ")}).`,
+        });
+    }
+    return { primary: fallback, matched, usedFallback: true };
+}
+export function requiresVerifyStepsByPrimary(tags, config) {
+    const primary = resolvePrimaryTagFromConfig(tags, config).primary;
+    return readVerifyPrimaryPolicy(config).requireStepsForPrimary.has(primary);
+}
+export function requiresVerificationByPrimary(tags, config) {
+    const primary = resolvePrimaryTagFromConfig(tags, config).primary;
+    return readVerifyPrimaryPolicy(config).requireVerificationForPrimary.has(primary);
+}
+export function resolvePrimaryTag(tags, ctx) {
+    return resolvePrimaryTagFromConfig(tags, ctx.config);
+}
 export async function warnIfUnknownOwner(ctx, owner) {
     const trimmed = owner.trim();
     if (!trimmed)
@@ -125,6 +235,8 @@ export function ensurePlanApprovedIfRequired(task, config) {
 export function ensureVerificationSatisfiedIfRequired(task, config) {
     if (config.agents?.approvals?.require_verify !== true)
         return;
+    if (!requiresVerificationByPrimary(toStringArray(task.tags), config))
+        return;
     const state = task.verification?.state ?? "missing";
     if (state === "ok")
         return;
@@ -232,6 +344,14 @@ export async function readHeadCommit(cwd) {
     return { hash, message: subject };
 }
 export function enforceStatusCommitPolicy(opts) {
+    if (!isMajorStatusCommitTransition(opts.statusFrom, opts.statusTo)) {
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: `${opts.action}: status/comment-driven commit is allowed only for major transitions ` +
+                `(got ${opts.statusFrom.toUpperCase()} -> ${opts.statusTo.toUpperCase()})`,
+        });
+    }
     if (opts.policy === "off")
         return;
     if (opts.policy === "warn") {
@@ -249,6 +369,23 @@ export function enforceStatusCommitPolicy(opts) {
         });
     }
 }
+const MAJOR_STATUS_COMMIT_TRANSITIONS = new Set([
+    "READY->DOING",
+    "TODO->DOING",
+    "DOING->BLOCKED",
+    "BLOCKED->DOING",
+    "DOING->DONE",
+    "DONE->VERIFIED",
+    "VERIFIED->FINISHED",
+    "VERIFIED->EXPORTED",
+]);
+export function isMajorStatusCommitTransition(statusFrom, statusTo) {
+    const from = statusFrom.trim().toUpperCase();
+    const to = statusTo.trim().toUpperCase();
+    if (!from || !to)
+        return false;
+    return MAJOR_STATUS_COMMIT_TRANSITIONS.has(`${from}->${to}`);
+}
 export async function readCommitInfo(cwd, rev) {
     const { stdout } = await execFileAsync("git", ["log", "-1", "--pretty=%H%x00%s", rev], { cwd });
     const { hash, subject } = parseGitLogHashSubject(stdout);

package/dist/commands/task/start-ready.command.d.ts

@@ -0,0 +1,14 @@
+import type { CommandCtx, CommandSpec } from "../../cli/spec/spec.js";
+import type { CommandContext } from "../shared/task-backend.js";
+type TaskStartReadyParsed = {
+    taskId: string;
+    author: string;
+    body: string;
+    force: boolean;
+    yes: boolean;
+    quiet: boolean;
+};
+export declare const taskStartReadySpec: CommandSpec<TaskStartReadyParsed>;
+export declare function makeRunTaskStartReadyHandler(getCtx: (cmd: string) => Promise<CommandContext>): (ctx: CommandCtx, p: TaskStartReadyParsed) => Promise<number>;
+export {};
+//# sourceMappingURL=start-ready.command.d.ts.map

package/dist/commands/task/start-ready.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-ready.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/start-ready.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGhE,KAAK,oBAAoB,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,oBAAoB,CA2DhE,CAAC;AAEF,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IAC7E,KAAK,UAAU,EAAE,GAAG,oBAAoB,KAAG,OAAO,CAAC,MAAM,CAAC,CAazE"}

package/dist/commands/task/start-ready.command.js

@@ -0,0 +1,77 @@
+import { usageError } from "../../cli/spec/errors.js";
+import { cmdTaskStartReady } from "./start-ready.js";
+export const taskStartReadySpec = {
+    id: ["task", "start-ready"],
+    group: "Task",
+    summary: "Run readiness checks and start a task in one deterministic command.",
+    args: [{ name: "task-id", required: true, valueHint: "<task-id>" }],
+    options: [
+        {
+            kind: "string",
+            name: "author",
+            valueHint: "<id>",
+            required: true,
+            description: "Comment author id (e.g. CODER).",
+        },
+        {
+            kind: "string",
+            name: "body",
+            valueHint: "<text>",
+            required: true,
+            description: "Structured Start comment body.",
+        },
+        {
+            kind: "boolean",
+            name: "force",
+            default: false,
+            description: "Override readiness and transition checks.",
+        },
+        {
+            kind: "boolean",
+            name: "yes",
+            default: false,
+            description: "Auto-approve force-action checks when required.",
+        },
+        { kind: "boolean", name: "quiet", default: false, description: "Suppress output." },
+    ],
+    examples: [
+        {
+            cmd: 'agentplane task start-ready 202602030608-F1Q8AB --author CODER --body "Start: implement parser hardening"',
+            why: "Check readiness and transition to DOING without command chaining.",
+        },
+    ],
+    validateRaw: (raw) => {
+        const taskId = typeof raw.args["task-id"] === "string" ? raw.args["task-id"].trim() : "";
+        const author = typeof raw.opts.author === "string" ? raw.opts.author.trim() : "";
+        const body = typeof raw.opts.body === "string" ? raw.opts.body.trim() : "";
+        if (!taskId)
+            throw usageError({ spec: taskStartReadySpec, message: "Invalid value for task-id: empty." });
+        if (!author)
+            throw usageError({ spec: taskStartReadySpec, message: "Invalid value for --author: empty." });
+        if (!body)
+            throw usageError({ spec: taskStartReadySpec, message: "Invalid value for --body: empty." });
+    },
+    parse: (raw) => ({
+        taskId: String(raw.args["task-id"]),
+        author: String(raw.opts.author),
+        body: String(raw.opts.body),
+        force: raw.opts.force === true,
+        yes: raw.opts.yes === true,
+        quiet: raw.opts.quiet === true,
+    }),
+};
+export function makeRunTaskStartReadyHandler(getCtx) {
+    return async (ctx, p) => {
+        return await cmdTaskStartReady({
+            ctx: await getCtx("task start-ready"),
+            cwd: ctx.cwd,
+            rootOverride: ctx.rootOverride,
+            taskId: p.taskId,
+            author: p.author,
+            body: p.body,
+            force: p.force,
+            yes: p.yes,
+            quiet: p.quiet,
+        });
+    };
+}

package/dist/commands/task/start-ready.d.ts

@@ -0,0 +1,13 @@
+import { type CommandContext } from "../shared/task-backend.js";
+export declare function cmdTaskStartReady(opts: {
+    ctx?: CommandContext;
+    cwd: string;
+    rootOverride?: string;
+    taskId: string;
+    author: string;
+    body: string;
+    force: boolean;
+    yes: boolean;
+    quiet: boolean;
+}): Promise<number>;
+//# sourceMappingURL=start-ready.d.ts.map

package/dist/commands/task/start-ready.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-ready.d.ts","sourceRoot":"","sources":["../../../src/commands/task/start-ready.ts"],"names":[],"mappings":"AAEA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAKpF,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAuClB"}

package/dist/commands/task/start-ready.js

@@ -0,0 +1,46 @@
+import { mapBackendError } from "../../cli/error-map.js";
+import { CliError } from "../../shared/errors.js";
+import { loadCommandContext } from "../shared/task-backend.js";
+import { cmdReady } from "./ready.js";
+import { cmdStart } from "./start.js";
+export async function cmdTaskStartReady(opts) {
+    try {
+        const ctx = opts.ctx ??
+            (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
+        const readyCode = await cmdReady({
+            ctx,
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride,
+            taskId: opts.taskId,
+        });
+        if (readyCode !== 0 && !opts.force) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: `Task is not ready: ${opts.taskId} (resolve dependencies or use --force)`,
+            });
+        }
+        return await cmdStart({
+            ctx,
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride,
+            taskId: opts.taskId,
+            author: opts.author,
+            body: opts.body,
+            commitFromComment: false,
+            commitAllow: [],
+            commitAutoAllow: false,
+            commitAllowTasks: true,
+            commitRequireClean: false,
+            confirmStatusCommit: false,
+            force: opts.force,
+            yes: opts.yes,
+            quiet: opts.quiet,
+        });
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw mapBackendError(err, { command: "task start-ready", root: opts.rootOverride ?? null });
+    }
+}

package/dist/commands/task/start.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../../src/commands/task/start.ts"],"names":[],"mappings":"AAQA,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAoBnC,wBAAsB,QAAQ,CAAC,IAAI,EAAE;IACnC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,eAAe,EAAE,OAAO,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoMlB"}
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../../src/commands/task/start.ts"],"names":[],"mappings":"AAQA,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAqBnC,wBAAsB,QAAQ,CAAC,IAAI,EAAE;IACnC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,eAAe,EAAE,OAAO,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAqMlB"}

package/dist/commands/task/start.js

@@ -7,7 +7,7 @@ import { ensureActionApproved } from "../shared/approval-requirements.js";
 import { listTasksMemo, loadCommandContext, loadTaskFromContext, } from "../shared/task-backend.js";
 import { backendIsLocalFileBackend, getTaskStore } from "../shared/task-store.js";
 import { readDirectWorkLock } from "../../shared/direct-work-lock.js";
-import { appendTaskEvent, buildDependencyState, ensurePlanApprovedIfRequired, enforceStatusCommitPolicy, defaultCommitEmojiForAgentId, extractDocSection, isVerifyStepsFilled, isTransitionAllowed, nowIso, requiresVerify, requireStructuredComment, toStringArray, } from "./shared.js";
+import { appendTaskEvent, buildDependencyState, ensurePlanApprovedIfRequired, enforceStatusCommitPolicy, defaultCommitEmojiForAgentId, extractDocSection, isVerifyStepsFilled, isTransitionAllowed, nowIso, requiresVerifyStepsByPrimary, requireStructuredComment, resolvePrimaryTag, toStringArray, } from "./shared.js";
 export async function cmdStart(opts) {
     try {
         const ctx = opts.ctx ??
@@ -20,14 +20,6 @@ export async function cmdStart(opts) {
                 reason: "start --force",
             });
         }
-        if (opts.commitFromComment) {
-            enforceStatusCommitPolicy({
-                policy: ctx.config.status_commit_policy,
-                action: "start",
-                confirmed: opts.confirmStatusCommit,
-                quiet: opts.quiet,
-            });
-        }
         const { prefix, min_chars: minChars } = ctx.config.tasks.comments.start;
         requireStructuredComment(opts.body, prefix, minChars);
         const useStore = backendIsLocalFileBackend(ctx);
@@ -39,9 +31,8 @@ export async function cmdStart(opts) {
             const enforce = ctx.config.tasks.verify.enforce_on_start_when_no_plan !== false;
             if (enforce) {
                 const tags = toStringArray(task.tags);
-                const requireStepsTags = ctx.config.tasks.verify.require_steps_for_tags ?? ctx.config.tasks.verify.required_tags;
                 const spikeTag = (ctx.config.tasks.verify.spike_tag ?? "spike").trim().toLowerCase();
-                const verifyRequired = requiresVerify(tags, requireStepsTags);
+                const verifyRequired = requiresVerifyStepsByPrimary(tags, ctx.config);
                 const isSpike = tags.some((tag) => tag.trim().toLowerCase() === spikeTag);
                 const doc = typeof task.doc === "string" ? task.doc : "";
                 if (verifyRequired || isSpike) {
@@ -77,6 +68,16 @@ export async function cmdStart(opts) {
                 message: `Refusing status transition ${currentStatus} -> DOING (use --force to override)`,
             });
         }
+        if (opts.commitFromComment) {
+            enforceStatusCommitPolicy({
+                policy: ctx.config.status_commit_policy,
+                action: "start",
+                confirmed: opts.confirmStatusCommit,
+                quiet: opts.quiet,
+                statusFrom: currentStatus,
+                statusTo: "DOING",
+            });
+        }
         if (!opts.force) {
             const allTasks = await listTasksMemo(ctx);
             const depState = buildDependencyState(allTasks);
@@ -151,6 +152,7 @@ export async function cmdStart(opts) {
                 cwd: opts.cwd,
                 rootOverride: opts.rootOverride,
                 taskId: opts.taskId,
+                primaryTag: resolvePrimaryTag(toStringArray(task.tags), ctx).primary,
                 executorAgent,
                 author: opts.author,
                 statusFrom: currentStatus,

package/dist/commands/task/update.command.d.ts

@@ -12,6 +12,7 @@ export type TaskUpdateParsed = {
     replaceDependsOn: boolean;
     verify: string[];
     replaceVerify: boolean;
+    allowPrimaryChange: boolean;
 };
 export declare const taskUpdateSpec: CommandSpec<TaskUpdateParsed>;
 export declare function makeRunTaskUpdateHandler(getCtx: (cmd: string) => Promise<CommandContext>): (ctx: CommandCtx, p: TaskUpdateParsed) => Promise<number>;

package/dist/commands/task/update.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/update.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAKhE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,aAAa,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAiHxD,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IACzE,KAAK,UAAU,EAAE,GAAG,gBAAgB,KAAG,OAAO,CAAC,MAAM,CAAC,CAkBrE"}
+{"version":3,"file":"update.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/update.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAKhE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,aAAa,EAAE,OAAO,CAAC;IACvB,kBAAkB,EAAE,OAAO,CAAC;CAC7B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAwHxD,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IACzE,KAAK,UAAU,EAAE,GAAG,gBAAgB,KAAG,OAAO,CAAC,MAAM,CAAC,CAmBrE"}

package/dist/commands/task/update.command.js

@@ -63,6 +63,12 @@ export const taskUpdateSpec = {
             default: false,
             description: "Replace existing verify commands (instead of merging).",
         },
+        {
+            kind: "boolean",
+            name: "allow-primary-change",
+            default: false,
+            description: "Explicitly allow changing the task primary tag during update.",
+        },
     ],
     examples: [
         {
@@ -110,6 +116,7 @@ export const taskUpdateSpec = {
             replaceDependsOn: raw.opts["replace-depends-on"] === true,
             verify,
             replaceVerify: raw.opts["replace-verify"] === true,
+            allowPrimaryChange: raw.opts["allow-primary-change"] === true,
         };
     },
 };
@@ -130,6 +137,7 @@ export function makeRunTaskUpdateHandler(getCtx) {
             replaceDependsOn: p.replaceDependsOn,
             verify: p.verify,
             replaceVerify: p.replaceVerify,
+            allowPrimaryChange: p.allowPrimaryChange,
         });
     };
 }

package/dist/commands/task/update.d.ts

@@ -14,5 +14,6 @@ export declare function cmdTaskUpdate(opts: {
     replaceDependsOn: boolean;
     verify: string[];
     replaceVerify: boolean;
+    allowPrimaryChange?: boolean;
 }): Promise<number>;
 //# sourceMappingURL=update.d.ts.map

package/dist/commands/task/update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../src/commands/task/update.ts"],"names":[],"mappings":"AAIA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGpF,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,aAAa,EAAE,OAAO,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,CAqDlB"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../src/commands/task/update.ts"],"names":[],"mappings":"AAIA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAUpF,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,aAAa,EAAE,OAAO,CAAC;IACvB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,GAAG,OAAO,CAAC,MAAM,CAAC,CAwElB"}

package/dist/commands/task/update.js

@@ -2,7 +2,7 @@ import { mapBackendError } from "../../cli/error-map.js";
 import { successMessage, unknownEntityMessage, warnMessage } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
 import { loadCommandContext } from "../shared/task-backend.js";
-import { dedupeStrings, requiresVerify, toStringArray, warnIfUnknownOwner } from "./shared.js";
+import { dedupeStrings, requiresVerifyStepsByPrimary, readTaskTagPolicy, resolvePrimaryTag, toStringArray, warnIfUnknownOwner, } from "./shared.js";
 export async function cmdTaskUpdate(opts) {
     try {
         const ctx = opts.ctx ??
@@ -26,14 +26,27 @@ export async function cmdTaskUpdate(opts) {
             next.owner = opts.owner;
             await warnIfUnknownOwner(ctx, opts.owner);
         }
+        const currentPrimary = resolvePrimaryTag(toStringArray(next.tags), ctx).primary;
         const existingTags = opts.replaceTags ? [] : dedupeStrings(toStringArray(next.tags));
         const mergedTags = dedupeStrings([...existingTags, ...opts.tags]);
+        const nextPrimary = resolvePrimaryTag(mergedTags, ctx).primary;
+        const tagPolicy = readTaskTagPolicy(ctx);
+        if (currentPrimary !== nextPrimary &&
+            tagPolicy.lockPrimaryOnUpdate === true &&
+            opts.allowPrimaryChange !== true) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: `Primary tag change is locked (${currentPrimary} -> ${nextPrimary}). ` +
+                    "Use --allow-primary-change to override explicitly.",
+            });
+        }
         next.tags = mergedTags;
         const spikeTag = (ctx.config.tasks.verify.spike_tag ?? "spike").trim().toLowerCase();
         const hasSpike = mergedTags.some((tag) => tag.trim().toLowerCase() === spikeTag);
-        const hasImplementationTags = requiresVerify(mergedTags, ctx.config.tasks.verify.required_tags);
+        const hasImplementationTags = requiresVerifyStepsByPrimary(mergedTags, ctx.config);
         if (hasSpike && hasImplementationTags) {
-            process.stderr.write(`${warnMessage("spike is combined with code/backend/frontend tags; consider splitting spike vs implementation tasks")}\n`);
+            process.stderr.write(`${warnMessage("spike is combined with a primary tag that requires verify steps; consider splitting spike vs implementation tasks")}\n`);
         }
         const existingDepends = opts.replaceDependsOn
             ? []
@@ -48,6 +61,9 @@ export async function cmdTaskUpdate(opts) {
         return 0;
     }
     catch (err) {
+        if (err instanceof CliError) {
+            throw err;
+        }
         throw mapBackendError(err, { command: "task update", root: opts.rootOverride ?? null });
     }
 }

package/dist/shared/errors.d.ts

@@ -10,5 +10,13 @@ export declare class CliError extends Error {
         context?: Record<string, unknown>;
     });
 }
-export declare function formatJsonError(err: CliError): string;
+export type JsonErrorGuidance = {
+    hint?: string;
+    nextAction?: {
+        command: string;
+        reason: string;
+        reasonCode?: string;
+    };
+};
+export declare function formatJsonError(err: CliError, guidance?: JsonErrorGuidance): string;
 //# sourceMappingURL=errors.d.ts.map

package/dist/shared/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,cAAc,GACd,MAAM,GACN,OAAO,GACP,WAAW,GACX,WAAW,GACX,YAAY,CAAC;AAEjB,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,IAAI,EAAE,SAAS,CAAC;IAChC,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAEtC,IAAI,EAAE;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,SAAS,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC;CAMF;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAYrD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,cAAc,GACd,MAAM,GACN,OAAO,GACP,WAAW,GACX,WAAW,GACX,YAAY,CAAC;AAEjB,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,IAAI,EAAE,SAAS,CAAC;IAChC,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAEtC,IAAI,EAAE;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,SAAS,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC;CAMF;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH,CAAC;AAEF,wBAAgB,eAAe,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAcnF"}

package/dist/shared/errors.js

@@ -9,12 +9,14 @@ export class CliError extends Error {
         this.context = opts.context;
     }
 }
-export function formatJsonError(err) {
+export function formatJsonError(err, guidance) {
     return JSON.stringify({
         error: {
             code: err.code,
             message: err.message,
             context: err.context ?? undefined,
+            hint: guidance?.hint,
+            next_action: guidance?.nextAction,
         },
     }, null, 2);
 }

package/dist/shared/runtime-artifacts.d.ts

@@ -0,0 +1,3 @@
+export declare const RUNTIME_GITIGNORE_LINES: readonly ["# agentplane: ignore runtime/transient workspace artifacts", ".env", ".agentplane/worktrees", ".agentplane/cache", ".agentplane/recipes-cache", ".agentplane/.upgrade", ".agentplane/.release", ".agentplane/upgrade", ".agentplane/tasks.json", "AGENTS.md.bak-*", ".agentplane/agents/*.bak-*"];
+export declare const AGENT_PROMPT_GITIGNORE_LINES: readonly ["# agentplane: ignore local agent prompts/templates", "AGENTS.md", ".agentplane/agents/"];
+//# sourceMappingURL=runtime-artifacts.d.ts.map

package/dist/shared/runtime-artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-artifacts.d.ts","sourceRoot":"","sources":["../../src/shared/runtime-artifacts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,8SAY1B,CAAC;AAEX,eAAO,MAAM,4BAA4B,qGAI/B,CAAC"}

package/dist/shared/runtime-artifacts.js

@@ -0,0 +1,18 @@
+export const RUNTIME_GITIGNORE_LINES = [
+    "# agentplane: ignore runtime/transient workspace artifacts",
+    ".env",
+    ".agentplane/worktrees",
+    ".agentplane/cache",
+    ".agentplane/recipes-cache",
+    ".agentplane/.upgrade",
+    ".agentplane/.release",
+    ".agentplane/upgrade",
+    ".agentplane/tasks.json",
+    "AGENTS.md.bak-*",
+    ".agentplane/agents/*.bak-*",
+];
+export const AGENT_PROMPT_GITIGNORE_LINES = [
+    "# agentplane: ignore local agent prompts/templates",
+    "AGENTS.md",
+    ".agentplane/agents/",
+];

package/dist/usecases/context/resolve-context.d.ts

@@ -1,3 +1,4 @@
+import type { AgentplaneConfig, ResolvedProject } from "@agentplaneorg/core";
 import type { Adapters } from "../../adapters/index.js";
 import { type CommandContext } from "../../commands/shared/task-backend.js";
 import { PolicyEngine } from "../../policy/engine.js";
@@ -9,6 +10,8 @@ export type UsecaseContext = {
 export declare function resolveContext(opts: {
     cwd: string;
     rootOverride?: string | null;
+    resolvedProject?: ResolvedProject;
+    config?: AgentplaneConfig;
 }): Promise<CommandContext>;
 export declare function makeUsecaseContext(command: CommandContext): UsecaseContext;
 //# sourceMappingURL=resolve-context.d.ts.map

package/dist/usecases/context/resolve-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-context.d.ts","sourceRoot":"","sources":["../../../src/usecases/context/resolve-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAExD,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAChG,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,GAAG,OAAO,CAAC,cAAc,CAAC,CAE1B;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,CAM1E"}
+{"version":3,"file":"resolve-context.d.ts","sourceRoot":"","sources":["../../../src/usecases/context/resolve-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAExD,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAChG,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B,GAAG,OAAO,CAAC,cAAc,CAAC,CAO1B;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,CAM1E"}

package/dist/usecases/context/resolve-context.js

@@ -2,7 +2,12 @@ import { buildAdapters } from "../../adapters/index.js";
 import { loadCommandContext } from "../../commands/shared/task-backend.js";
 import { PolicyEngine } from "../../policy/engine.js";
 export async function resolveContext(opts) {
-    return await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null });
+    return await loadCommandContext({
+        cwd: opts.cwd,
+        rootOverride: opts.rootOverride ?? null,
+        resolvedProject: opts.resolvedProject,
+        config: opts.config,
+    });
 }
 export function makeUsecaseContext(command) {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentplane",
-  "version": "0.2.19",
+  "version": "0.2.21",
   "description": "Agent Plane CLI for task workflows, recipes, and project automation.",
   "keywords": [
     "agentplane",
@@ -55,7 +55,7 @@
     "prepublishOnly": "node ../../scripts/enforce-github-publish.mjs && npm run prepack"
   },
   "dependencies": {
-    "@agentplaneorg/core": "0.2.17",
+    "@agentplaneorg/core": "0.2.21",
     "yauzl": "^2.10.0"
   },
   "devDependencies": {