@pmelab/gtd 36.0.0 → 37.0.0

package/src/edge/Edge.ts

@@ -54,6 +54,7 @@ import {
   type ModelCost,
   type SliceEntry,
   type StepAccess,
+  type StepContextLimit,
 } from "../wire/index.js"
 
 import { GTD_VERSION } from "../install/index.js"
@@ -722,6 +723,13 @@ type RequestOf<K extends ReachedStep["request"]["kind"]> = Extract<
   { kind: K }
 >
 
+const stepContext = (
+  context: { readonly soft?: number | undefined; readonly hard?: number | undefined } | undefined,
+): StepContextLimit | undefined =>
+  context === undefined
+    ? undefined
+    : { ...optional("soft", context.soft), ...optional("hard", context.hard) }
+
 const promptDef = (
   common: StepCommon,
   request: RequestOf<"agent">,
@@ -735,6 +743,7 @@ const promptDef = (
   ...optional("system", request.options.system),
   ...optional("allowEmpty", request.options.allowEmpty),
   ...optional("keep", request.options.keep),
+  ...optional("context", stepContext(request.options.context)),
   ...optional("skills", skills),
   ...optional("access", access),
 })
@@ -850,6 +859,7 @@ export interface RestHints {
   readonly mode?: string
   readonly skills?: readonly string[]
   readonly access?: StepAccess
+  readonly context?: StepContextLimit
 }
 
 const hintsOf = (def: StepDef): RestHints => ({
@@ -861,6 +871,7 @@ const hintsOf = (def: StepDef): RestHints => ({
   ...optional("mode", def.mode),
   ...optional("skills", def.skills),
   ...optional("access", def.access),
+  ...optional("context", def.context),
 })
 
 const normalizeStatus = (raw: string): ChangeStatus => (raw === "A" ? "A" : raw === "D" ? "D" : "M")

package/src/flows/runtime.ts

@@ -16,9 +16,18 @@ export interface SteeringOptions {
   readonly base?: string | undefined
 }
 
+/** Shares of the model's context window at which a driver stops the turn — `gtd next --json`'s `context`. */
+export interface ContextLimitOptions {
+  /** Ask the agent to wrap up with a handoff note. Driver default 0.6. */
+  readonly soft?: number | undefined
+  /** Stop the turn outright. Driver default 0.7. */
+  readonly hard?: number | undefined
+}
+
 export interface AgentOptions extends SteeringOptions {
   readonly model?: string | undefined
   readonly system?: string | undefined
+  readonly context?: ContextLimitOptions | undefined
   /**
    * A turn that changes nothing completes the step. Without this an empty turn
    * is an attempt: recorded, but the process stays at the step (a stall).
@@ -115,6 +124,8 @@ export interface ScopeOptions {
   readonly model?: string | undefined
   /** The system prompt every agent step inside runs with, unless it sets its own. */
   readonly system?: string | undefined
+  /** The context limit every agent step inside runs with; a nested scope's or a step's own replaces it key by key. */
+  readonly context?: ContextLimitOptions | undefined
   /** The skill names every agent step inside declares — `gtd next --json`'s `skills`. A nested scope inherits it unless it sets its own. */
   readonly skills?: readonly string[] | undefined
   /** The file access every agent step inside runs with — `gtd next --json`'s `access`. A nested scope inherits it; its own replaces it wholesale. */

package/src/replay/Replay.ts

@@ -8,6 +8,7 @@ import {
   type ScopeAccess,
   type AccessDef,
   type ScopeOptions,
+  type ContextLimitOptions,
   type StepRequest,
   type Flow,
   type Mark,
@@ -21,7 +22,7 @@ import {
   unansweredQuestions,
 } from "../steering/index.js"
 import { accessShapeFault, foldAccess, sameAccess } from "./Access.js"
-import { globMatches } from "../wire/index.js"
+import { contextLimitFault, contextShapeFault, globMatches } from "../wire/index.js"
 import { refNameFault } from "./RefName.js"
 import { IMPLICIT_SLICE, SLICE_NAME, type SliceSpan } from "./Slices.js"
 import { diffTrees, isEmptyDiff, type TreeView } from "./Tree.js"
@@ -207,6 +208,28 @@ const budgeted = (
   return { evidence: bounded, truncated }
 }
 
+// The innermost of `chain`, named by its full path.
+const scopeLabel = (chain: readonly ScopeOptions[]): string => {
+  const path = chain.flatMap((o) => (o.name === undefined ? [] : [o.name])).join(".")
+  if (chain.at(-1)?.name !== undefined) return `scope "${path}"`
+  return path === "" ? "an unnamed scope" : `an unnamed scope inside "${path}"`
+}
+
+// Key by key, innermost last: a scope or step that sets only `hard` keeps the outer `soft`.
+const inheritedContext = (
+  layers: readonly (ContextLimitOptions | undefined)[],
+): ContextLimitOptions | undefined =>
+  layers.reduce<ContextLimitOptions | undefined>(
+    (merged, layer) =>
+      layer === undefined
+        ? merged
+        : {
+            ...merged,
+            ...Object.fromEntries(Object.entries(layer).filter(([, value]) => value !== undefined)),
+          },
+    undefined,
+  )
+
 interface Identity {
   readonly model: string | undefined
   readonly system: string | undefined
@@ -243,7 +266,7 @@ const STEERING_OPTIONS = ["file", "mode", "label", "base"]
 // The option keys each step accepts. A gtd.config.ts is evaluated without a
 // type check, so a misspelt key would otherwise be silently ignored.
 const KNOWN_OPTIONS: Readonly<Record<StepKind, ReadonlySet<string>>> = {
-  agent: new Set([...STEERING_OPTIONS, "model", "system", "allowEmpty", "keep"]),
+  agent: new Set([...STEERING_OPTIONS, "model", "system", "context", "allowEmpty", "keep"]),
   human: new Set([...STEERING_OPTIONS, "message", "acceptClean", "approve"]),
   run: new Set(STEERING_OPTIONS),
   judge: new Set([...STEERING_OPTIONS, "message"]),
@@ -426,11 +449,13 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
         if (s.model !== undefined) persona.model = s.model
         if (s.system !== undefined) persona.system = s.system
       }
+      const context = inheritedContext([...scopes.map((s) => s.context), request.options.context])
       return {
         ...request,
         options: {
           ...persona,
           ...request.options,
+          ...(context === undefined ? {} : { context }),
         },
       }
     }
@@ -575,6 +600,28 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     return landPending(step, input.pending)
   }
 
+  // Each layer on its own first, so a bad scope or workflow option is named as
+  // such rather than blamed on the step it reached; then the merged limit.
+  const scopeContextFault = (): string | undefined => {
+    for (const [i, s] of scopes.entries()) {
+      const fault = s.context === undefined ? undefined : contextShapeFault(s.context)
+      if (fault !== undefined)
+        return `the context of ${scopeLabel(scopes.slice(0, i + 1))}: ${fault}`
+    }
+    return undefined
+  }
+
+  const resolvedContextFault = (
+    request: Extract<StepRequest, { kind: "agent" }>,
+  ): string | undefined => {
+    const own = request.options.context
+    const layered = scopeContextFault() ?? (own === undefined ? undefined : contextShapeFault(own))
+    if (layered !== undefined) return layered
+    const resolved = resolve(request)
+    const context = resolved.kind === "agent" ? resolved.options.context : undefined
+    return context === undefined ? undefined : contextLimitFault(context)
+  }
+
   // gtd.config.ts is loaded without a type check.
   const requestFault = (request: Exclude<StepRequest, { kind: "restart" }>): string | undefined => {
     if (request.kind === "run" && typeof request.body !== "string") {
@@ -582,6 +629,8 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     }
     if (request.kind !== "agent") return undefined
     const name = scoped(request.name)
+    const contextFault = resolvedContextFault(request)
+    if (contextFault !== undefined) return `gtd: step "${name}": ${contextFault}`
     if (request.options.keep === true) {
       // A clean allowEmpty keep would land an ordinary commit with no Gtd-Kept: a silent skip.
       if (request.options.allowEmpty === true) {

package/src/testkit/Layers.ts

@@ -206,6 +206,7 @@ const missingToolCommands: ToolCommands["Type"] = {
   ui: missingTool("ui"),
   lsp: missingTool("lsp"),
   loop: missingTool("loop"),
+  contextHook: missingTool("context-hook"),
   judge: () =>
     Promise.reject(
       new Error("gtd judge run: ToolCommands has no test double wired into testLayers()"),

package/src/wire/BeatDocument.ts

@@ -1,6 +1,14 @@
 import type { BeatKind, Demand, DemandSession } from "./Demand.js"
 import type { BeatStatus, NextMatch, StatusChange } from "./BeatStatus.js"
-import type { Actor, ApprovalEntry, ModelCost, StateMode, StateName, StepAccess } from "./types.js"
+import type {
+  Actor,
+  ApprovalEntry,
+  ModelCost,
+  StateMode,
+  StateName,
+  StepAccess,
+  StepContextLimit,
+} from "./types.js"
 import { WIRE_SCHEMA } from "./constants.js"
 
 /** `gtd next --json`'s `next` key — `null` when landing would commit nothing. */
@@ -56,6 +64,7 @@ export interface BeatDocument {
   readonly session: DemandSession | undefined
   readonly model: string | undefined
   readonly system: string | undefined
+  readonly context: StepContextLimit | undefined
   readonly validate: string | undefined
   readonly log: string
   readonly state: StateName
@@ -76,7 +85,7 @@ export interface BeatDocument {
 }
 
 /**
- * Flatten a `Demand` plus its `BeatStatus` into the single 25-key document
+ * Flatten a `Demand` plus its `BeatStatus` into the single 26-key document
  * `gtd next --json` emits — the ONLY place the two are joined. `cost`/
  * `costByModel` are omitted together, exactly when no cost was recorded
  * (`cost <= 0`).
@@ -93,6 +102,7 @@ export const beatDocument = (demand: Demand, status: BeatStatus): BeatDocument =
     session,
     model: status.model,
     system: status.system,
+    context: status.context,
     validate,
     log: status.log,
     state: status.state,

package/src/wire/BeatStatus.ts

@@ -5,6 +5,7 @@ import type {
   RenderedDemandSource,
   StateMode,
   StateName,
+  StepContextLimit,
 } from "./types.js"
 
 /** One pending change — `gtd next --json`'s `changes` entries. */
@@ -32,6 +33,7 @@ export interface BeatStatus {
   readonly initial: boolean
   readonly model: string | undefined
   readonly system: string | undefined
+  readonly context: StepContextLimit | undefined
   readonly log: string
   readonly state: StateName
   readonly actor: Actor
@@ -74,6 +76,7 @@ export const statusOf = (input: {
     initial,
     model: rendered.model,
     system: rendered.system !== undefined && rendered.system !== "" ? rendered.system : undefined,
+    context: rendered.context,
     log,
     state: rendered.state,
     actor: rendered.actor,

package/src/wire/ContextLimit.fixture.ts

@@ -0,0 +1,30 @@
+/** A Claude Code transcript whose latest assistant message used `tokens` of context, as the hook reads it from `transcript_path`. */
+export const transcriptAt = (tokens: number): string =>
+  [
+    { type: "user", message: { role: "user", content: "build it" } },
+    {
+      type: "assistant",
+      message: {
+        id: "msg_1",
+        role: "assistant",
+        usage: { input_tokens: 3, cache_read_input_tokens: 10, cache_creation_input_tokens: 7 },
+      },
+    },
+    { type: "user", message: { role: "user", content: [{ type: "tool_result" }] } },
+    {
+      type: "assistant",
+      message: {
+        id: "msg_2",
+        role: "assistant",
+        usage: {
+          input_tokens: 1,
+          cache_read_input_tokens: tokens - 1001,
+          cache_creation_input_tokens: 1000,
+          output_tokens: 500,
+        },
+      },
+    },
+    { type: "attachment", attachment: { type: "hook_success" } },
+  ]
+    .map((entry) => JSON.stringify(entry))
+    .join("\n") + "\n"

package/src/wire/ContextLimit.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest"
+import {
+  CONTEXT_LIMIT_MARKER,
+  DEFAULT_CONTEXT_LIMIT,
+  contextHook,
+  contextLimitFault,
+  contextWindowFor,
+  hookOutput,
+  subagentTranscriptPath,
+  transcriptTokens,
+} from "./ContextLimit.js"
+import { transcriptAt } from "./ContextLimit.fixture.js"
+
+const at = (tokens: number, event: "PostToolUse" | "PreCompact" = "PostToolUse") =>
+  contextHook({
+    event,
+    tokens: transcriptTokens(transcriptAt(tokens)),
+    window: 200_000,
+    limit: DEFAULT_CONTEXT_LIMIT,
+  })
+
+describe("transcriptTokens", () => {
+  it("counts the latest assistant message's input, cache-read and cache-creation tokens", () => {
+    expect(transcriptTokens(transcriptAt(50_000))).toBe(50_000)
+  })
+
+  it("is undefined for a transcript with no assistant usage yet", () => {
+    expect(transcriptTokens('{"type":"user"}\nnot json\n')).toBeUndefined()
+  })
+})
+
+describe("contextHook", () => {
+  it("lets a run below the soft limit go on", () => {
+    expect(at(119_999)).toBeUndefined()
+  })
+
+  it("blocks with a handoff-note request at the soft limit", () => {
+    const decision = at(120_000)
+    expect(decision?.kind).toBe("soft")
+    expect(hookOutput(decision!)).toEqual({
+      decision: "block",
+      reason: expect.stringContaining("short handoff note"),
+    })
+  })
+
+  it("stops the run at the hard limit, behind the marker", () => {
+    const decision = at(140_000)
+    expect(hookOutput(decision!)).toEqual({
+      continue: false,
+      stopReason: expect.stringMatching(new RegExp(`^${CONTEXT_LIMIT_MARKER}: 140000 of 200000`)),
+    })
+  })
+
+  it("stops the run on PreCompact, whatever the count", () => {
+    expect(hookOutput(at(1_000, "PreCompact")!)).toEqual({
+      continue: false,
+      stopReason: expect.stringContaining(
+        `${CONTEXT_LIMIT_MARKER}: the context is about to be compacted`,
+      ),
+    })
+  })
+
+  it("lets a run with no usage yet go on", () => {
+    const limit = DEFAULT_CONTEXT_LIMIT
+    expect(
+      contextHook({ event: "PostToolUse", tokens: undefined, window: 1, limit }),
+    ).toBeUndefined()
+  })
+})
+
+describe("contextLimitFault", () => {
+  it("accepts shares in (0, 1] with soft below hard", () => {
+    expect(contextLimitFault({ soft: 0.5, hard: 1 })).toBeUndefined()
+    expect(contextLimitFault({ hard: 0.9 })).toBeUndefined()
+  })
+
+  it("refuses a share outside (0, 1] and a soft limit at or above the hard one", () => {
+    expect(contextLimitFault({ soft: 0 })).toMatch(/context\.soft must be/)
+    expect(contextLimitFault({ hard: 70 })).toMatch(/context\.hard must be/)
+    expect(contextLimitFault({ soft: 0.8 })).toMatch(/below context\.hard \(0\.7\)/)
+    const misspelt: { hard: number } = Object.assign({ hard: 0.8 }, { sotf: 0.5 })
+    expect(contextLimitFault(misspelt)).toBe("unknown key(s) sotf in context")
+  })
+})
+
+it("reads the long window from Claude Code's [1m] suffix only", () => {
+  expect(contextWindowFor("opus[1m]")).toBe(1_000_000)
+  expect(contextWindowFor("opus")).toBe(200_000)
+  expect(contextWindowFor(undefined)).toBe(200_000)
+})
+
+it("finds a worker's own transcript beside the main session's", () => {
+  expect(subagentTranscriptPath("/p/session.jsonl", "a1")).toBe(
+    "/p/session/subagents/agent-a1.jsonl",
+  )
+})

package/src/wire/ContextLimit.ts

@@ -0,0 +1,169 @@
+// The context-limit decision every driver shares: the loop's `gtd context-hook`
+// and the Claude Code mod both answer a hook event through `contextHook`, so
+// the two cannot drift on thresholds, wording or which tokens count.
+
+/** A share of the model's context window, each in (0, 1]; `soft` below `hard`. */
+export interface ContextLimit {
+  readonly soft: number
+  readonly hard: number
+}
+
+export const DEFAULT_CONTEXT_LIMIT: ContextLimit = { soft: 0.6, hard: 0.7 }
+
+const DEFAULT_WINDOW = 200_000
+const LONG_WINDOW = 1_000_000
+
+/** Claude Code's `[1m]` suffix selects the long window; a transcript never names it, so the driver decides from the model it passed. */
+export const contextWindowFor = (model: string | undefined): number =>
+  model !== undefined && /\[1m\]/i.test(model) ? LONG_WINDOW : DEFAULT_WINDOW
+
+/** A positive whole number of tokens, or `undefined` for anything else. */
+export const parseContextWindow = (raw: string | undefined): number | undefined => {
+  const n = Number(raw)
+  return raw !== undefined && raw.trim() !== "" && Number.isInteger(n) && n > 0 ? n : undefined
+}
+
+/** `gtd context-hook`'s request: the hook's stdin and the limits its flags set. */
+export interface ContextHookRequest {
+  readonly input: string
+  readonly soft?: number
+  readonly hard?: number
+  readonly window?: number
+}
+
+/**
+ * Where a driver asks `gtd context-hook` to record a hard stop's `stopReason`:
+ * Claude Code prints it nowhere a driver reads, and `hook_stopped` alone would
+ * also name any other hook that stopped the turn.
+ */
+export const CONTEXT_STOP_FILE_ENV = "GTD_LOOP_CONTEXT_STOP_FILE"
+
+/**
+ * Why one layer of a limit (a scope's, a step's) is malformed, ignoring how its
+ * two shares relate: layers merge key by key, so only the merged limit has to
+ * keep `soft` below `hard`. Config is evaluated untyped, so anything may arrive.
+ */
+export const contextShapeFault = (limit: unknown): string | undefined => {
+  if (typeof limit !== "object" || limit === null || Array.isArray(limit)) {
+    return `context must be an object { soft, hard }, got ${JSON.stringify(limit)}`
+  }
+  const unknown = Object.keys(limit).filter((key) => key !== "soft" && key !== "hard")
+  if (unknown.length > 0) return `unknown key(s) ${unknown.join(", ")} in context`
+  const shares = limit as { readonly soft?: unknown; readonly hard?: unknown }
+  for (const key of ["soft", "hard"] as const) {
+    const value = shares[key]
+    if (value === undefined) continue
+    if (typeof value !== "number" || !(value > 0 && value <= 1)) {
+      return `context.${key} must be a share of the context window in (0, 1], got ${JSON.stringify(value)}`
+    }
+  }
+  return undefined
+}
+
+/** Why a whole limit is unusable, or `undefined` when it is fine. */
+export const contextLimitFault = (limit: unknown): string | undefined => {
+  const shape = contextShapeFault(limit)
+  if (shape !== undefined) return shape
+  const shares = limit as { readonly soft?: unknown; readonly hard?: unknown }
+  const soft = (shares.soft as number | undefined) ?? DEFAULT_CONTEXT_LIMIT.soft
+  const hard = (shares.hard as number | undefined) ?? DEFAULT_CONTEXT_LIMIT.hard
+  return soft < hard ? undefined : `context.soft (${soft}) must be below context.hard (${hard})`
+}
+
+const record = (value: unknown): Record<string, unknown> | undefined =>
+  typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined
+
+const count = (value: unknown): number => (typeof value === "number" && value > 0 ? value : 0)
+
+/** What a message's usage puts in the context window: its whole input, cached or not. */
+export const usageTokens = (usage: unknown): number | undefined => {
+  const u = record(usage)
+  if (u === undefined) return undefined
+  return (
+    count(u["input_tokens"]) +
+    count(u["cache_read_input_tokens"]) +
+    count(u["cache_creation_input_tokens"])
+  )
+}
+
+/**
+ * The context size of the latest assistant message in a Claude Code transcript
+ * (one JSON entry per line). Usage is per message, not a running sum, so the
+ * last entry alone is the window's fill.
+ */
+export const transcriptTokens = (transcript: string): number | undefined => {
+  const lines = transcript.split("\n")
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]!.trim()
+    if (line === "") continue
+    let entry: unknown
+    try {
+      entry = JSON.parse(line)
+    } catch {
+      continue
+    }
+    if (record(entry)?.["type"] !== "assistant") continue
+    const tokens = usageTokens(record(record(entry)?.["message"])?.["usage"])
+    if (tokens !== undefined) return tokens
+  }
+  return undefined
+}
+
+/**
+ * A worker subagent's own transcript. A hook its tool call fires is handed the
+ * MAIN session's `transcript_path`; the worker's sits beside it.
+ */
+export const subagentTranscriptPath = (transcriptPath: string, agentId: string): string =>
+  `${transcriptPath.replace(/\.jsonl$/, "")}/subagents/agent-${agentId}.jsonl`
+
+/** Every hard stop's `stopReason` starts with this: the driver's context-limit marker. */
+export const CONTEXT_LIMIT_MARKER = "gtd: context limit"
+
+export type ContextEvent = "PostToolUse" | "PreCompact"
+
+export type ContextDecision =
+  | { readonly kind: "soft"; readonly reason: string }
+  | { readonly kind: "hard"; readonly stopReason: string }
+
+const percent = (share: number): string => `${Math.round(share * 100)}%`
+
+/**
+ * What a hook answers, or `undefined` to let the run go on. Compaction about
+ * to happen means the limit was missed, so `PreCompact` is a hard stop whatever
+ * the count says.
+ */
+export const contextHook = (input: {
+  readonly event: ContextEvent
+  readonly tokens: number | undefined
+  readonly window: number
+  readonly limit: ContextLimit
+}): ContextDecision | undefined => {
+  const { event, tokens, window, limit } = input
+  if (event === "PreCompact") {
+    return {
+      kind: "hard",
+      stopReason: `${CONTEXT_LIMIT_MARKER}: the context is about to be compacted — the run is too big for one turn`,
+    }
+  }
+  if (tokens === undefined) return undefined
+  const used = `${tokens} of ${window} tokens`
+  if (tokens >= limit.hard * window) {
+    return {
+      kind: "hard",
+      stopReason: `${CONTEXT_LIMIT_MARKER}: ${used}, past the ${percent(limit.hard)} hard limit`,
+    }
+  }
+  if (tokens >= limit.soft * window) {
+    return {
+      kind: "soft",
+      reason: `Context limit: ${used} used, past the ${percent(limit.soft)} soft limit. Stop working now. Do not start anything new; end your turn with a short handoff note as your answer: what you touched, and what was next.`,
+    }
+  }
+  return undefined
+}
+
+/** A decision as Claude Code's settings-hook JSON output. */
+export const hookOutput = (decision: ContextDecision): Record<string, unknown> =>
+  decision.kind === "soft"
+    ? { decision: "block", reason: decision.reason }
+    : { continue: false, stopReason: decision.stopReason }

package/src/wire/index.ts

@@ -11,3 +11,4 @@ export { selectPath } from "./Select.js"
 export { resolveSession } from "./Sessions.js"
 export { globMatches } from "./Glob.js"
 export * from "./Slices.js"
+export * from "./ContextLimit.js"

package/src/wire/types.ts

@@ -38,6 +38,12 @@ export interface ApprovalEntry {
   readonly commit: string
 }
 
+/** The context-limit shares a step sets; a driver fills an absent one from its defaults. */
+export interface StepContextLimit {
+  readonly soft?: number
+  readonly hard?: number
+}
+
 export interface RenderedDemandSource {
   readonly state: StateName
   readonly actor: Actor
@@ -51,4 +57,5 @@ export interface RenderedDemandSource {
   readonly judge?: string
   readonly skills?: readonly string[]
   readonly access?: StepAccess
+  readonly context?: StepContextLimit
 }

package/src/workflow/Workflow.ts

@@ -1,5 +1,12 @@
 import type { WorkflowBase, Flow, ScopeAccess, Summary } from "../flows/index.js"
-import type { Actor, ContentKind, StateMode, StateName, StepAccess } from "../wire/index.js"
+import type {
+  Actor,
+  ContentKind,
+  StateMode,
+  StateName,
+  StepAccess,
+  StepContextLimit,
+} from "../wire/index.js"
 
 export type { Actor, ContentKind, StateMode, StateName }
 
@@ -44,6 +51,7 @@ export interface StepDef {
   readonly approve?: boolean
   readonly skills?: readonly string[]
   readonly access?: StepAccess
+  readonly context?: StepContextLimit
 }
 
 /**

package/src/workflows/feature/context-limit.feature

@@ -0,0 +1,37 @@
+@inmem
+Feature: the shipped workflows take a context limit as an option
+
+  `contextLimit: { soft, hard }` is a factory option: every agent step of the
+  workflow runs under it, carried as `gtd next --json`'s `context`. Without it a
+  step carries none and the driver's defaults apply.
+
+  Scenario Outline: every agent step carries the configured limit, or none
+    Given a gtd config with:
+      """
+      import { feature } from "@pmelab/gtd/workflows/feature"
+      export { summary, steering, skills, access } from "@pmelab/gtd/workflows/feature"
+      export default feature(<options>)
+      """
+    And a file "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      """
+    And the working tree is committed as "feat: add calculator"
+    And a file "TODO.md" with:
+      """
+      # Add subtract
+
+      subtract(a, b) returns the difference.
+      """
+    And step "unwind" changes nothing
+    And step "start-gate.check" changes nothing
+    When the process is driven
+    Then the process rests at "design.triage"
+    And the output of gtd "next --json" <carries>
+
+    Examples:
+      | options                                     | carries                                             |
+      | { contextLimit: { soft: 0.5, hard: 0.65 } } | contains "\"context\":{\"soft\":0.5,\"hard\":0.65}" |
+      | { contextLimit: { hard: 0.8 } }             | contains "\"context\":{\"hard\":0.8}"               |
+      | {}                                          | does not contain "\"context\""                      |
+

package/src/workflows/feature/coverage.ts

@@ -23,7 +23,7 @@ const COVERING_RETRIES = 2
 
 const frozen = (): void => requireCriteriaFrozen(REQUIREMENTS)
 
-export const green = (): Promise<void> =>
+export const green = (guard?: () => void): Promise<void> =>
   healthy(
     () =>
       t.agentWithSkills("fix.suite.fixing", t.implementFixPrompt(), {
@@ -32,7 +32,13 @@ export const green = (): Promise<void> =>
         model: coder(),
         system: t.builderSystem(),
       }),
-    { guard: frozen, guardRests: false },
+    {
+      guard: () => {
+        frozen()
+        guard?.()
+      },
+      guardRests: false,
+    },
   )
 
 // A budget cut keeps the end, so the files naming a criterion ID go last.

package/src/workflows/feature/feature.ts

@@ -47,10 +47,14 @@ export const buildFeature = async (firstBase: string): Promise<void> => {
       tier,
       afterRefactor: seam.refactored,
       naive: seam.land === true ? seam.reference : undefined,
+      rebuild: seam.rebuild,
     })
-    // An empty feature slice: the refactor carried the feature, so the lap covers the whole change.
+    // A feature slice with no code beyond the carried-over tests: the refactor carried the
+    // feature, so the lap covers the whole change.
+    const carried = seam.rebuild?.acceptance?.tests ?? []
     const base =
-      seam.refactored === true && !changesSince(seam.base).some((c) => isCode(c.path))
+      seam.refactored === true &&
+      !changesSince(seam.base).some((c) => isCode(c.path) && !carried.includes(c.path))
         ? firstBase
         : seam.base
     await tail(settleQuality, { green: true, lensBase: base })