@pmelab/gtd 2.2.0 → 2.4.0

package/dist/gtd.bundle.mjs

@@ -367039,6 +367039,7 @@ var Cwd = class _Cwd extends Context_exports.Tag("Cwd")() {
 var stateTier = {
   decompose: "planning",
   grilling: "planning",
+  architecting: "planning",
   building: "execution",
   fixing: "execution",
   "agentic-review": "planning",
@@ -367051,11 +367052,13 @@ var builtinTierDefault = {
 var DEFAULT_TEST_COMMAND = "npm run test";
 var DEFAULT_AGENTIC_REVIEW = true;
 var DEFAULT_SQUASH = true;
+var DEFAULT_LEARNING = true;
 var DEFAULT_FIX_ATTEMPT_CAP = 3;
 var DEFAULT_REVIEW_THRESHOLD = 3;
 var ModelStatesSchema = Schema_exports.Struct({
   decompose: Schema_exports.optional(Schema_exports.String),
   grilling: Schema_exports.optional(Schema_exports.String),
+  architecting: Schema_exports.optional(Schema_exports.String),
   building: Schema_exports.optional(Schema_exports.String),
   fixing: Schema_exports.optional(Schema_exports.String),
   "agentic-review": Schema_exports.optional(Schema_exports.String),
@@ -367071,6 +367074,7 @@ var ConfigSchema = Schema_exports.Struct({
   models: Schema_exports.optional(ModelsSchema),
   agenticReview: Schema_exports.optional(Schema_exports.Boolean),
   squash: Schema_exports.optional(Schema_exports.Boolean),
+  learning: Schema_exports.optional(Schema_exports.Boolean),
   fixAttemptCap: Schema_exports.optional(Schema_exports.Int.pipe(Schema_exports.greaterThanOrEqualTo(0))),
   reviewThreshold: Schema_exports.optional(Schema_exports.Int.pipe(Schema_exports.greaterThanOrEqualTo(1)))
 });
@@ -367202,6 +367206,7 @@ var toOperations = (decoded) => {
     resolveModel,
     agenticReview: decoded.agenticReview ?? DEFAULT_AGENTIC_REVIEW,
     squash: decoded.squash ?? DEFAULT_SQUASH,
+    learning: decoded.learning ?? DEFAULT_LEARNING,
     fixAttemptCap: decoded.fixAttemptCap ?? DEFAULT_FIX_ATTEMPT_CAP,
     reviewThreshold: decoded.reviewThreshold ?? DEFAULT_REVIEW_THRESHOLD
   };
@@ -387755,6 +387760,7 @@ var formatFile = (path16) => Effect_exports.gen(function* () {
 // src/Subjects.ts
 var turnSubject = (actor, gate) => `gtd(${actor}): ${gate}`;
 var ROUTING_SUBJECT = {
+  architecting: "gtd: architecting",
   grilled: "gtd: grilled",
   planning: "gtd: planning",
   "tests-green": "gtd: tests green",
@@ -387765,12 +387771,17 @@ var ROUTING_SUBJECT = {
   done: "gtd: done",
   "squash-template": "gtd: squash template",
   "health-check": "gtd: health-check",
-  "health-fix": "gtd: health-fix"
+  "health-fix": "gtd: health-fix",
+  "learning-template": "gtd: learning template",
+  "learning-drafted": "gtd: learning drafted",
+  "learning-approved": "gtd: learning approved",
+  "learning-applied": "gtd: learning applied"
 };
 var reviewingSubject = (baseHash) => `gtd: reviewing ${baseHash}`;
 var TURN_RE = /^gtd\((human|agent)\): (.+)$/;
 var TURN_GATES = /* @__PURE__ */ new Set([
   "grilling",
+  "architecting",
   "grilled",
   "building",
   "fixing",
@@ -387778,7 +387789,9 @@ var TURN_GATES = /* @__PURE__ */ new Set([
   "review",
   "squashing",
   "health-fixing",
-  "escalate"
+  "escalate",
+  "learning",
+  "learning-apply"
 ]);
 var ROUTING_SUBJECT_TO_PHASE = new Map(
   Object.entries(ROUTING_SUBJECT).map(([phase, subject]) => [
@@ -387813,19 +387826,34 @@ var parseSubject = (subject) => {
 // src/Events.ts
 var GTD_DIR = ".gtd";
 var TODO_FILE = `${GTD_DIR}/TODO.md`;
+var ARCHITECTURE_FILE = `${GTD_DIR}/ARCHITECTURE.md`;
 var REVIEW_FILE = `${GTD_DIR}/REVIEW.md`;
 var FEEDBACK_FILE = `${GTD_DIR}/FEEDBACK.md`;
 var ERRORS_FILE = `${GTD_DIR}/ERRORS.md`;
 var HEALTH_FILE = `${GTD_DIR}/HEALTH.md`;
 var SQUASH_MSG_FILE = `${GTD_DIR}/SQUASH_MSG.md`;
+var LEARNINGS_FILE = `${GTD_DIR}/LEARNINGS.md`;
 var LEGACY_FEEDBACK_FILE = "FEEDBACK.md";
 var emptyFailureSentinel = (command, exitCode3) => `Test command \`${command}\` failed with exit code ${exitCode3} and produced no output.`;
 var DONE_SUBJECT = "gtd: done";
 var WORKFLOW_FILE_EXCLUDES = [GTD_DIR];
 var GATE_OWN_STEERING_FILE = {
   grilling: TODO_FILE,
+  architecting: ARCHITECTURE_FILE,
   review: REVIEW_FILE
 };
+var SQUASH_OR_LEARNING_ROUTING_PHASES = /* @__PURE__ */ new Set([
+  "squash-template",
+  "learning-template",
+  "learning-drafted",
+  "learning-approved",
+  "learning-applied"
+]);
+var SQUASH_OR_LEARNING_TURN_GATES = /* @__PURE__ */ new Set([
+  "squashing",
+  "learning",
+  "learning-apply"
+]);
 var turnDiffExcludes = (gate) => {
   const ownFile = GATE_OWN_STEERING_FILE[gate];
   return ownFile ? [...WORKFLOW_FILE_EXCLUDES, `!${ownFile}`] : WORKFLOW_FILE_EXCLUDES;
@@ -388015,6 +388043,7 @@ var gatherEvents = (invoker) => (
     const gtdModified = entries2.some((e7) => isPackagePath(e7.path));
     const codeDirty = entries2.some((e7) => !isGtdPath(e7.path));
     const todoExists = yield* fs9.exists(resolve5(TODO_FILE));
+    const architectureExists = yield* fs9.exists(resolve5(ARCHITECTURE_FILE));
     const reviewPresent = yield* fs9.exists(resolve5(REVIEW_FILE));
     const feedbackPresent = yield* fs9.exists(resolve5(FEEDBACK_FILE));
     const errorsPresent = yield* fs9.exists(resolve5(ERRORS_FILE));
@@ -388029,6 +388058,7 @@ var gatherEvents = (invoker) => (
     const reviewCommitted = reviewTrackedAtHead && workingTreeClean;
     const reviewDirty = reviewTrackedAtHead && !workingTreeClean;
     const todoCommitted = todoExists && !isUncommitted(TODO_FILE);
+    const architectureCommitted = architectureExists && !isUncommitted(ARCHITECTURE_FILE);
     const pendingErrorsDeletion = entries2.some(
       (e7) => e7.path === ERRORS_FILE && e7.status.includes("D")
     );
@@ -388063,7 +388093,7 @@ var gatherEvents = (invoker) => (
       }
       const isGrillingTurn = (message) => {
         const parsed = parseSubject(subjectOf(message));
-        return parsed.kind === "turn" && parsed.gate === "grilling";
+        return parsed.kind === "turn" && (parsed.gate === "grilling" || parsed.gate === "architecting");
       };
       const firstGrilling = currentCycle.find((c7) => isGrillingTurn(c7.message));
       const lastAwaitingReview = (() => {
@@ -388096,8 +388126,8 @@ var gatherEvents = (invoker) => (
     let squashBase;
     let squashDiff;
     const headParsedForSquash = parseSubject(lastCommitSubject);
-    const inSquashChain = lastCommitSubject === DONE_SUBJECT || headParsedForSquash.kind === "routing" && headParsedForSquash.phase === "squash-template" || headParsedForSquash.kind === "turn" && headParsedForSquash.actor === "agent" && headParsedForSquash.gate === "squashing";
-    if (hasCommits && inSquashChain && config2.squash) {
+    const inSquashOrLearningChain = lastCommitSubject === DONE_SUBJECT || headParsedForSquash.kind === "routing" && SQUASH_OR_LEARNING_ROUTING_PHASES.has(headParsedForSquash.phase) || headParsedForSquash.kind === "turn" && SQUASH_OR_LEARNING_TURN_GATES.has(headParsedForSquash.gate);
+    if (hasCommits && inSquashOrLearningChain && (config2.squash || config2.learning)) {
       const squashHistory = history;
       let lastDoneIdxForSquash = -1;
       let prevDoneIdx = -1;
@@ -388111,7 +388141,7 @@ var gatherEvents = (invoker) => (
         const squashCycle = squashHistory.slice(prevDoneIdx + 1, lastDoneIdxForSquash + 1);
         const isGrillingTurnSubject = (subject) => {
           const parsed = parseSubject(subject);
-          return parsed.kind === "turn" && parsed.gate === "grilling";
+          return parsed.kind === "turn" && (parsed.gate === "grilling" || parsed.gate === "architecting");
         };
         const isReviewingAnchor = (subject) => {
           const parsed = parseSubject(subject);
@@ -388143,11 +388173,13 @@ var gatherEvents = (invoker) => (
     }
     const squashMsgPresent = yield* fs9.exists(resolve5(SQUASH_MSG_FILE));
     const squashMsgIsTemplate = squashMsgPresent && (yield* fs9.readFileString(resolve5(SQUASH_MSG_FILE))).trim() === SQUASH_TEMPLATE.trim();
+    const learningMsgPresent = yield* fs9.exists(resolve5(LEARNINGS_FILE));
+    const learningMsgIsTemplate = learningMsgPresent && (yield* fs9.readFileString(resolve5(LEARNINGS_FILE))).trim() === LEARNING_TEMPLATE.trim();
     const healthPresent = yield* fs9.exists(resolve5(HEALTH_FILE));
     const healthContent = healthPresent ? yield* fs9.readFileString(resolve5(HEALTH_FILE)) : "";
     const healthCommitted = healthPresent && !isUncommitted(HEALTH_FILE);
     let healthFixBase;
-    if (config2.squash) {
+    if (config2.squash || config2.learning) {
       let firstHealthCheckHash;
       let healthCheckCount = 0;
       for (const commit3 of commitEvents) {
@@ -388189,6 +388221,8 @@ var gatherEvents = (invoker) => (
       ...headTurnReviewSubstantive !== void 0 ? { headTurnReviewSubstantive } : {},
       todoExists,
       todoCommitted,
+      architectureExists,
+      architectureCommitted,
       packagesPresent: packages.length > 0,
       reviewPresent,
       feedbackPresent,
@@ -388221,7 +388255,10 @@ var gatherEvents = (invoker) => (
       healthPresent,
       healthContent,
       healthCommitted,
-      ...healthFixBase !== void 0 ? { healthFixBase } : {}
+      ...healthFixBase !== void 0 ? { healthFixBase } : {},
+      learningEnabled: config2.learning,
+      learningMsgPresent,
+      learningMsgIsTemplate
     };
     const resolveEvent = { type: "RESOLVE", payload };
     return [...commitEvents, resolveEvent];
@@ -388245,6 +388282,16 @@ var SQUASH_TEMPLATE = [
   "Longer description of the change, if needed.",
   ""
 ].join("\n");
+var ARCHITECTURE_SEED_BANNER = "<!-- gtd: seeded from the converged product plan (.gtd/TODO.md); decide the technical/architectural questions below. -->\n\n";
+var LEARNING_TEMPLATE = [
+  "<!-- gtd: replace this file's content with the actual distilled learnings for this cycle. -->",
+  "<!-- Keep only durable, generalizable lessons \u2014 delete anything that's a one-off detail. -->",
+  "",
+  "## Learnings",
+  "",
+  "- ...",
+  ""
+].join("\n");
 var perform = (action) => (
   // fallow-ignore-next-line complexity
   Effect_exports.gen(function* () {
@@ -388254,22 +388301,38 @@ var perform = (action) => (
     const resolve5 = (p4) => join10(root2, p4);
     const ensureGtdDir = fs9.makeDirectory(resolve5(GTD_DIR), { recursive: true }).pipe(Effect_exports.catchAll(() => Effect_exports.void));
     switch (action.kind) {
-      // Capture a human/agent turn: format the pending TODO.md (best-effort),
-      // then commit-all under `gtd(<actor>): <gate>` (--allow-empty).
+      // Capture a human/agent turn: format the pending TODO.md/ARCHITECTURE.md
+      // (best-effort), then commit-all under `gtd(<actor>): <gate>` (--allow-empty).
       case "captureTurn": {
         const todoExists = yield* fs9.exists(resolve5(TODO_FILE));
         if (todoExists) {
           yield* formatFile(resolve5(TODO_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
         }
+        const architectureExists = yield* fs9.exists(resolve5(ARCHITECTURE_FILE));
+        if (architectureExists) {
+          yield* formatFile(resolve5(ARCHITECTURE_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
+        }
         yield* git.commitAllWithPrefix(turnSubject(action.actor, action.gate));
         return { stop: false };
       }
       // Routing bookkeeping: delete the flagged files FIRST so their removal
       // lands in this same commit, then commit-all under `subject`.
+      // `seedArchitectureFromTodo` instead reads TODO.md, writes it (with a
+      // scaffold banner) as ARCHITECTURE.md, and deletes TODO.md — the
+      // grilling→architecting hand-off, in this same commit.
       case "commitRouting": {
-        if (action.removeTodo === true) {
+        if (action.seedArchitectureFromTodo === true) {
+          const todoContent = yield* fs9.readFileString(resolve5(TODO_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.succeed("")));
+          yield* ensureGtdDir;
+          yield* fs9.writeFileString(
+            resolve5(ARCHITECTURE_FILE),
+            ARCHITECTURE_SEED_BANNER + todoContent
+          );
           yield* fs9.remove(resolve5(TODO_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
         }
+        if (action.removeArchitecture === true) {
+          yield* fs9.remove(resolve5(ARCHITECTURE_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
+        }
         if (action.removeReview === true) {
           yield* fs9.remove(resolve5(REVIEW_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
         }
@@ -388279,6 +388342,9 @@ var perform = (action) => (
         if (action.removeHealth === true) {
           yield* fs9.remove(resolve5(HEALTH_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
         }
+        if (action.removeLearning === true) {
+          yield* fs9.remove(resolve5(LEARNINGS_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
+        }
         yield* git.commitAllWithPrefix(action.subject);
         return { stop: false };
       }
@@ -388326,6 +388392,14 @@ var perform = (action) => (
         yield* git.commitAllWithPrefix("gtd: squash template");
         return { stop: false };
       }
+      // Write the LEARNINGS.md template (a durable-lessons skeleton) and
+      // commit routing `gtd: learning template`.
+      case "writeLearningTemplate": {
+        yield* ensureGtdDir;
+        yield* fs9.writeFileString(resolve5(LEARNINGS_FILE), LEARNING_TEMPLATE);
+        yield* git.commitAllWithPrefix("gtd: learning template");
+        return { stop: false };
+      }
       // Squash: read SQUASH_MSG.md content (the real message authored by the
       // squashing turn), rm it, soft-reset to squashBase, commit-all under the
       // file's content as the message.
@@ -388337,10 +388411,11 @@ var perform = (action) => (
         return { stop: false };
       }
       // Health check: run tests on an idle/clean tree.
-      // Green, no squash-after chain queued → stop immediately, no commit/write.
-      // Green, `squashAfterGreen` → commit routing `gtd: tests green` (the
+      // Green, no learning/squash-after chain queued → stop immediately, no
+      //   commit/write.
+      // Green, `chainAfterGreen` → commit routing `gtd: tests green` (the
       //   observable green marker) and continue — the resolver chains
-      //   `writeSquashTemplate` at that HEAD next.
+      //   `writeLearningTemplate` or `writeSquashTemplate` at that HEAD next.
       // Red below cap → write HEALTH.md, commit routing `gtd: health-check` (the
       //   always-clean invariant: write-and-commit in the same chain).
       // Red at cap → write ERRORS.md, commit routing `gtd: health-check`.
@@ -388348,7 +388423,7 @@ var perform = (action) => (
         const runner = yield* TestRunner;
         const result = yield* runner.run();
         if (result.exitCode === 0) {
-          if (action.squashAfterGreen) {
+          if (action.chainAfterGreen) {
             yield* git.commitAllWithPrefix("gtd: tests green");
             return { stop: false };
           }
@@ -388419,6 +388494,8 @@ var DEFAULT_PAYLOAD = {
   headTurnIsEmpty: false,
   todoExists: false,
   todoCommitted: false,
+  architectureExists: false,
+  architectureCommitted: false,
   packagesPresent: false,
   reviewPresent: false,
   feedbackPresent: false,
@@ -388445,7 +388522,10 @@ var DEFAULT_PAYLOAD = {
   squashMsgIsTemplate: false,
   healthPresent: false,
   healthContent: "",
-  healthCommitted: false
+  healthCommitted: false,
+  learningEnabled: false,
+  learningMsgPresent: false,
+  learningMsgIsTemplate: false
 };
 var buildContext = (p4, counters) => ({
   testFixCount: counters.testFixCount,
@@ -388476,9 +388556,38 @@ var healthFileConflictRules = [
     message: ".gtd/HEALTH.md + .gtd/ERRORS.md"
   }
 ];
+var learningFileConflictRules = [
+  {
+    isViolated: (p4) => p4.learningMsgPresent && p4.packagesPresent,
+    message: ".gtd/LEARNINGS.md + packages"
+  },
+  {
+    isViolated: (p4) => p4.learningMsgPresent && p4.reviewPresent,
+    message: ".gtd/LEARNINGS.md + .gtd/REVIEW.md"
+  },
+  {
+    isViolated: (p4) => p4.learningMsgPresent && p4.feedbackPresent,
+    message: ".gtd/LEARNINGS.md + .gtd/FEEDBACK.md"
+  },
+  {
+    isViolated: (p4) => p4.learningMsgPresent && p4.errorsPresent,
+    message: ".gtd/LEARNINGS.md + .gtd/ERRORS.md"
+  },
+  {
+    isViolated: (p4) => p4.learningMsgPresent && p4.healthPresent,
+    message: ".gtd/LEARNINGS.md + .gtd/HEALTH.md"
+  },
+  {
+    isViolated: (p4) => p4.learningMsgPresent && p4.squashMsgPresent,
+    message: ".gtd/LEARNINGS.md + .gtd/SQUASH_MSG.md"
+  }
+];
 var isReviewPackagesConflict = (p4) => p4.reviewPresent && p4.packagesPresent;
 var isReviewCommittedTodoConflict = (p4) => p4.reviewPresent && p4.todoCommitted;
 var isUncommittedReviewWithTodoConflict = (p4) => p4.reviewPresent && !(p4.reviewCommitted || p4.reviewDirty) && p4.todoExists;
+var isReviewCommittedArchitectureConflict = (p4) => p4.reviewPresent && p4.architectureCommitted;
+var isUncommittedReviewWithArchitectureConflict = (p4) => p4.reviewPresent && !(p4.reviewCommitted || p4.reviewDirty) && p4.architectureExists;
+var isTodoArchitectureConflict = (p4) => p4.todoExists && p4.architectureExists;
 var isFeedbackReviewConflict = (p4) => p4.feedbackPresent && p4.reviewPresent;
 var isFeedbackWithoutPackages = (p4) => p4.feedbackPresent && !p4.packagesPresent;
 var isErrorsFeedbackConflict = (p4) => p4.errorsPresent && p4.feedbackPresent;
@@ -388494,18 +388603,68 @@ var reviewAndFeedbackRules = [
     isViolated: isUncommittedReviewWithTodoConflict,
     message: "uncommitted .gtd/REVIEW.md + .gtd/TODO.md"
   },
+  {
+    isViolated: isReviewCommittedArchitectureConflict,
+    message: ".gtd/REVIEW.md + committed .gtd/ARCHITECTURE.md"
+  },
+  {
+    isViolated: isUncommittedReviewWithArchitectureConflict,
+    message: "uncommitted .gtd/REVIEW.md + .gtd/ARCHITECTURE.md"
+  },
+  { isViolated: isTodoArchitectureConflict, message: ".gtd/TODO.md + .gtd/ARCHITECTURE.md" },
   { isViolated: isFeedbackReviewConflict, message: ".gtd/FEEDBACK.md + .gtd/REVIEW.md" },
   { isViolated: isFeedbackWithoutPackages, message: ".gtd/FEEDBACK.md without packages" },
   { isViolated: isErrorsFeedbackConflict, message: ".gtd/ERRORS.md + .gtd/FEEDBACK.md" },
   { isViolated: isErrorsWithoutPackages, message: ".gtd/ERRORS.md without packages" }
 ];
 var assertLegal = (p4) => {
-  for (const rule of [...healthFileConflictRules, ...reviewAndFeedbackRules]) {
+  for (const rule of [
+    ...healthFileConflictRules,
+    ...learningFileConflictRules,
+    ...reviewAndFeedbackRules
+  ]) {
     if (rule.isViolated(p4)) {
       throw new GtdStateError("illegal-combination", `illegal combination: ${rule.message}`);
     }
   }
 };
+var nextAfterReviewOrLearning = (flags, state, learningAlreadyRan) => {
+  if (!learningAlreadyRan && flags.learningEnabled && flags.hasSquashBase) {
+    return { kind: "mid-chain", state, actor: "agent", action: { kind: "writeLearningTemplate" } };
+  }
+  return flags.squashEnabled && flags.hasSquashBase ? { kind: "mid-chain", state, actor: "agent", action: { kind: "writeSquashTemplate" } } : { kind: "rest", state: "idle", actor: "human" };
+};
+var classifyLearningTurn = (actor, gate, flags) => {
+  if (actor === "agent" && gate === "learning") {
+    return flags.hasSquashBase && !flags.learningMsgIsTemplate ? {
+      kind: "mid-chain",
+      state: "learning",
+      actor: "agent",
+      action: { kind: "commitRouting", subject: "gtd: learning drafted" }
+    } : { kind: "rest", state: "learning", actor: "agent" };
+  }
+  if (actor === "human" && gate === "learning") {
+    return {
+      kind: "mid-chain",
+      state: "learning",
+      actor: "human",
+      action: { kind: "commitRouting", subject: "gtd: learning approved" }
+    };
+  }
+  if (actor === "agent" && gate === "learning-apply") {
+    return {
+      kind: "mid-chain",
+      state: "learning-apply",
+      actor: "agent",
+      action: {
+        kind: "commitRouting",
+        subject: "gtd: learning applied",
+        removeLearning: true
+      }
+    };
+  }
+  return null;
+};
 var classifyHead = (subject, flags) => {
   const parsed = parseSubject(subject);
   if (parsed.kind === "turn") {
@@ -388518,15 +388677,30 @@ var classifyHead = (subject, flags) => {
         kind: "mid-chain",
         state: "grilling",
         actor: "agent",
-        action: { kind: "commitRouting", subject: "gtd: grilled" }
+        action: {
+          kind: "commitRouting",
+          subject: "gtd: architecting",
+          seedArchitectureFromTodo: true
+        }
       } : { kind: "rest", state: "grilling", actor: "agent" };
     }
+    if (gate === "architecting") {
+      if (actor === "agent") {
+        return flags.headTurnIsEmpty ? { kind: "rest", state: "architecting", actor: "agent" } : { kind: "rest", state: "architecting", actor: "human" };
+      }
+      return flags.headTurnIsEmpty ? {
+        kind: "mid-chain",
+        state: "architecting",
+        actor: "agent",
+        action: { kind: "commitRouting", subject: "gtd: grilled" }
+      } : { kind: "rest", state: "architecting", actor: "agent" };
+    }
     if (actor === "agent" && gate === "grilled") {
       return flags.hasPackages ? {
         kind: "mid-chain",
         state: "grilled",
         actor: "agent",
-        action: { kind: "commitRouting", subject: "gtd: planning", removeTodo: true }
+        action: { kind: "commitRouting", subject: "gtd: planning", removeArchitecture: true }
       } : { kind: "rest", state: "grilled", actor: "agent" };
     }
     if (actor === "agent" && gate === "building") {
@@ -388578,6 +388752,8 @@ var classifyHead = (subject, flags) => {
         // squashBase filled in by the caller
       } : { kind: "rest", state: "squashing", actor: "agent" };
     }
+    const learningTurn = classifyLearningTurn(actor, gate, flags);
+    if (learningTurn !== null) return learningTurn;
     if (actor === "agent" && gate === "health-fixing") {
       return {
         kind: "mid-chain",
@@ -388598,6 +388774,8 @@ var classifyHead = (subject, flags) => {
   }
   if (parsed.kind === "routing") {
     switch (parsed.phase) {
+      case "architecting":
+        return { kind: "rest", state: "architecting", actor: "agent" };
       case "grilled":
         return { kind: "rest", state: "grilled", actor: "agent" };
       case "planning":
@@ -388611,12 +388789,7 @@ var classifyHead = (subject, flags) => {
             action: { kind: "closePackage" }
           } : { kind: "rest", state: "agentic-review", actor: "agent" };
         }
-        return flags.squashEnabled && flags.squashAfterGreen ? {
-          kind: "mid-chain",
-          state: "testing",
-          actor: "agent",
-          action: { kind: "writeSquashTemplate" }
-        } : { kind: "rest", state: "idle", actor: "human" };
+        return nextAfterReviewOrLearning(flags, "testing", false);
       case "errors":
         return flags.errorsPresent ? { kind: "rest", state: "escalate", actor: "human" } : { kind: "rest", state: "fixing", actor: "agent" };
       case "package-done":
@@ -388626,16 +388799,19 @@ var classifyHead = (subject, flags) => {
       case "review-feedback":
         return { kind: "rest", state: "grilling", actor: "agent" };
       case "done":
-        return flags.squashEnabled && flags.hasSquashBase ? {
-          kind: "mid-chain",
-          state: "done",
-          actor: "agent",
-          action: { kind: "writeSquashTemplate" }
-        } : { kind: "rest", state: "idle", actor: "human" };
+        return nextAfterReviewOrLearning(flags, "done", false);
       case "squash-template":
         return { kind: "rest", state: "squashing", actor: "agent" };
       case "reviewing":
         return { kind: "rest", state: "review", actor: "agent" };
+      case "learning-template":
+        return { kind: "rest", state: "learning", actor: "agent" };
+      case "learning-drafted":
+        return { kind: "rest", state: "await-learning-review", actor: "human" };
+      case "learning-approved":
+        return { kind: "rest", state: "learning-apply", actor: "agent" };
+      case "learning-applied":
+        return nextAfterReviewOrLearning(flags, "learning-applied", true);
       case "health-check":
         return flags.errorsPresent ? { kind: "rest", state: "escalate", actor: "human" } : { kind: "rest", state: "health-fixing", actor: "agent" };
       case "health-fix":
@@ -388646,6 +388822,7 @@ var classifyHead = (subject, flags) => {
 };
 var STATE_IS_OWN_GATE = /* @__PURE__ */ new Set([
   "grilling",
+  "architecting",
   "grilled",
   "building",
   "fixing",
@@ -388653,18 +388830,25 @@ var STATE_IS_OWN_GATE = /* @__PURE__ */ new Set([
   "review",
   "squashing",
   "health-fixing",
-  "escalate"
+  "escalate",
+  "learning",
+  "learning-apply"
 ]);
-var gateForState = (state) => STATE_IS_OWN_GATE.has(state) ? state : "review";
+var GATE_OVERRIDES = {
+  "await-learning-review": "learning"
+};
+var gateForState = (state) => STATE_IS_OWN_GATE.has(state) ? state : GATE_OVERRIDES[state] ?? "review";
 var INERT_EMPTY_AGENT_GATES = /* @__PURE__ */ new Set([
   "grilling",
+  "architecting",
   "grilled",
   "building",
   "fixing",
   "agentic-review",
-  "review"
+  "review",
+  "learning-apply"
 ]);
-var isInertEmptyAgentRest = (state, p4) => p4.workingTreeClean && (INERT_EMPTY_AGENT_GATES.has(state) || state === "squashing" && p4.squashMsgIsTemplate);
+var isInertEmptyAgentRest = (state, p4) => p4.workingTreeClean && (INERT_EMPTY_AGENT_GATES.has(state) || state === "squashing" && p4.squashMsgIsTemplate || state === "learning" && p4.learningMsgIsTemplate);
 var resolveBaseline = (p4, counters, head7, corrupt, lastTurn) => {
   const headIsFixerTurn = (() => {
     const parsed = parseSubject(head7);
@@ -388693,7 +388877,6 @@ var resolveBaseline = (p4, counters, head7, corrupt, lastTurn) => {
       action: { kind: "closePackage" }
     } : { kind: "rest", state: "fixing", actor: "agent" };
   }
-  const squashAfterGreen = p4.squashEnabled && counters.healthFixCount > 0 && p4.healthFixBase !== void 0;
   const reviewSubstantive = p4.headTurnReviewSubstantive !== void 0 ? p4.headTurnReviewSubstantive : p4.reviewDirty && !p4.reviewCheckboxOnly;
   const flags = {
     headTurnIsEmpty: p4.headTurnIsEmpty,
@@ -388701,7 +388884,8 @@ var resolveBaseline = (p4, counters, head7, corrupt, lastTurn) => {
     agenticReviewForceApproved: forceApprove,
     squashEnabled: p4.squashEnabled,
     hasSquashBase: p4.squashBase !== void 0,
-    squashAfterGreen,
+    learningEnabled: p4.learningEnabled,
+    learningMsgIsTemplate: p4.learningMsgIsTemplate,
     reviewSubstantive,
     // A pending (uncommitted) deletion of ERRORS.md still counts as "ERRORS.md
     // was committed at this HEAD" for classification purposes: `fs.exists`
@@ -388739,7 +388923,7 @@ var resolveBaseline = (p4, counters, head7, corrupt, lastTurn) => {
           kind: "runHealthCheck",
           errorCount: counters.healthFixCount,
           capReached: counters.healthFixCount >= p4.fixAttemptCap,
-          squashAfterGreen: classified.action.squashAfterGreen
+          chainAfterGreen: classified.action.chainAfterGreen
         }
       };
     }
@@ -388759,6 +388943,9 @@ var resolveBaseline = (p4, counters, head7, corrupt, lastTurn) => {
   if (p4.todoExists) {
     return { kind: "rest", state: "grilling", actor: "agent" };
   }
+  if (p4.architectureExists) {
+    return { kind: "rest", state: "architecting", actor: "agent" };
+  }
   if (p4.packagesPresent && p4.packages.length > 0 && lastTurn?.actor === "agent" && lastTurn.gate === "building") {
     return {
       kind: "mid-chain",
@@ -388767,7 +388954,7 @@ var resolveBaseline = (p4, counters, head7, corrupt, lastTurn) => {
       action: { kind: "runTest", errorCount: 0, capReached: false }
     };
   }
-  if (!p4.packagesPresent && !p4.reviewPresent && !p4.feedbackPresent && !p4.errorsPresent && !p4.healthPresent && !p4.todoExists) {
+  if (!p4.packagesPresent && !p4.reviewPresent && !p4.feedbackPresent && !p4.errorsPresent && !p4.healthPresent && !p4.todoExists && !p4.architectureExists) {
     return resolveIdleOrHealth(p4);
   }
   return corrupt();
@@ -388780,13 +388967,14 @@ var resolveIdleOrHealth = (p4) => {
 var applyTurnTaking = (p4, counters, head7, baseline) => {
   const context10 = buildContext(p4, counters);
   const invoker = p4.invoker;
-  const isDirtyBoundaryEntry = invoker === "human" && !p4.workingTreeClean && !p4.todoCommitted && !p4.packagesPresent && !p4.reviewPresent && !p4.feedbackPresent && !p4.errorsPresent && !p4.healthPresent && (parseSubject(head7).kind === "boundary" || head7 === "gtd: done");
+  const isDirtyBoundaryEntry = invoker === "human" && !p4.workingTreeClean && !p4.todoCommitted && !p4.architectureCommitted && !p4.packagesPresent && !p4.reviewPresent && !p4.feedbackPresent && !p4.errorsPresent && !p4.healthPresent && (parseSubject(head7).kind === "boundary" || head7 === "gtd: done");
   if (isDirtyBoundaryEntry) {
+    const entryGate = p4.architectureExists ? "architecting" : "grilling";
     return {
-      state: "grilling",
+      state: entryGate,
       actor: "human",
       pending: false,
-      edgeAction: { kind: "captureTurn", actor: "human", gate: "grilling" },
+      edgeAction: { kind: "captureTurn", actor: "human", gate: entryGate },
       context: context10
     };
   }
@@ -388808,7 +388996,7 @@ var applyTurnTaking = (p4, counters, head7, baseline) => {
   }
   const healthCheckCapReached = head7 === "gtd: health-check" && counters.healthFixCount >= p4.fixAttemptCap;
   if (head7 === "gtd: health-fix" && baseline.state === "idle" || healthCheckCapReached && baseline.state === "health-fixing") {
-    const squashAfterGreenAtHealthFix = p4.squashEnabled && counters.healthFixCount > 0 && p4.healthFixBase !== void 0;
+    const chainAfterGreenAtHealthFix = (p4.squashEnabled || p4.learningEnabled) && counters.healthFixCount > 0 && p4.healthFixBase !== void 0;
     return {
       state: "idle",
       actor: "agent",
@@ -388817,7 +389005,7 @@ var applyTurnTaking = (p4, counters, head7, baseline) => {
         kind: "runHealthCheck",
         errorCount: counters.healthFixCount,
         capReached: counters.healthFixCount >= p4.fixAttemptCap,
-        squashAfterGreen: squashAfterGreenAtHealthFix
+        chainAfterGreen: chainAfterGreenAtHealthFix
       },
       context: context10
     };
@@ -388832,7 +389020,7 @@ var applyTurnTaking = (p4, counters, head7, baseline) => {
     };
   }
   if (baseline.state === "idle" && invoker === "human") {
-    const squashAfterGreen = p4.squashEnabled && counters.healthFixCount > 0 && p4.healthFixBase !== void 0;
+    const chainAfterGreen = (p4.squashEnabled || p4.learningEnabled) && counters.healthFixCount > 0 && p4.healthFixBase !== void 0;
     return {
       state: "idle",
       actor: "human",
@@ -388841,7 +389029,7 @@ var applyTurnTaking = (p4, counters, head7, baseline) => {
         kind: "runHealthCheck",
         errorCount: counters.healthFixCount,
         capReached: counters.healthFixCount >= p4.fixAttemptCap,
-        squashAfterGreen
+        chainAfterGreen
       },
       context: context10
     };
@@ -388896,9 +389084,14 @@ var predictTurn = (events) => {
     const subject = baseline.action.kind === "commitRouting" ? baseline.action.subject : baseline.action.kind === "captureTurn" ? `gtd(${baseline.action.actor}): ${baseline.action.gate}` : null;
     return { actor: baseline.actor, subject, state: baseline.state };
   }
-  const isDirtyBoundaryEntry = !payload.workingTreeClean && !payload.todoCommitted && !payload.packagesPresent && !payload.reviewPresent && !payload.feedbackPresent && !payload.errorsPresent && !payload.healthPresent && (parseSubject(head7).kind === "boundary" || head7 === "gtd: done");
+  const isDirtyBoundaryEntry = !payload.workingTreeClean && !payload.todoCommitted && !payload.architectureCommitted && !payload.packagesPresent && !payload.reviewPresent && !payload.feedbackPresent && !payload.errorsPresent && !payload.healthPresent && (parseSubject(head7).kind === "boundary" || head7 === "gtd: done");
   if (isDirtyBoundaryEntry) {
-    return { actor: "human", subject: "gtd(human): grilling", state: "grilling" };
+    const entryGate = payload.architectureExists ? "architecting" : "grilling";
+    return {
+      actor: "human",
+      subject: `gtd(human): ${entryGate}`,
+      state: entryGate
+    };
   }
   if (baseline.state === "idle") {
     return { actor: "human", subject: null, state: "idle" };
@@ -389387,13 +389580,19 @@ var package_default = '<%\n  const lines = ["", "### Package: `" + it.pkg.name +
 var agent_turn_default = "Finish your turn by running `gtd step-agent`. Then run `gtd next` and follow\nits output \u2014 repeat this cycle as long as the output is addressed to you (the\nagent); when it awaits the human, stop and hand off.\n";
 
 // src/prompts/grilling-agent.md
-var grilling_agent_default = '<%~ include("@header") %>\n\n`.gtd/TODO.md` holds the plan under development. Develop it into a concrete,\nimplementation-ready plan **in this one turn** \u2014 use subagents / internal\niteration to go as deep as needed; there is no further agent-only round after\nthis one.\n\n### Develop the plan\n\nSpawn a **planning-model subagent** using model `<%= it.model %>` to develop the plan.\nThe subagent works entirely by editing `.gtd/TODO.md`:\n\n1. **Explore the codebase before asking anything** \u2014 read the relevant files,\n   tests, and docs so every question below is one the codebase genuinely\n   cannot answer.\n2. **Replace the captured input / seed template with a real implementation\n   plan** \u2014 the files to change, exactly what changes, and why, grounded in\n   the codebase.\n3. **Iterate internally** (spawn further subagents, reconsider, cross-check)\n   until the plan is as complete as it can get without human input. Do not\n   leave this to a future round \u2014 there isn\'t one before the human is asked.\n4. For every remaining open question, write it near the top of the file with\n   a **suggested default** \u2014 your best-guess answer, stated plainly, that the\n   human can accept as-is. A question with no suggested default is incomplete.\n5. Leave `.gtd/TODO.md` **uncommitted** \u2014 the human\'s turn (`gtd step`) reads it\n   next.\n<% if (it.context.turnDiff && it.context.turnDiff.trim()) { %>\n<%~ include("@diff", { heading: "Latest human input (answers / sketch / review feedback)", diff: it.context.turnDiff, fenceFor: it.fenceFor }) %>\n\nRead the diff above as **feedback, not finished work**:\n\n- Code changes are suggestions \u2014 fold them into the plan and re-implement them\n  properly, including test coverage, rather than restoring them verbatim.\n- Code comments are positional feedback about the code at that location.\n- Plan-text changes are global feedback on the plan (or the reviewed work) as\n  a whole.\n<% } %>\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
+var grilling_agent_default = '<%~ include("@header") %>\n\n`.gtd/TODO.md` holds the plan under development. Develop it into a concrete,\nproduct-level plan **in this one turn** \u2014 use subagents / internal iteration\nto go as deep as needed; there is no further agent-only round after this one.\n\n**Scope: product and user-facing decisions only.** Do not decide\nimplementation details in this file \u2014 file/module structure, data models,\nlibrary or tech-stack choices, and other architecture questions belong to the\nnext phase (`.gtd/ARCHITECTURE.md`) and must not be treated as open questions\nhere.\n\n### Develop the plan\n\nSpawn a **planning-model subagent** using model `<%= it.model %>` to develop the plan.\nThe subagent works entirely by editing `.gtd/TODO.md`:\n\n1. **Explore the codebase before asking anything** \u2014 read the relevant files,\n   tests, and docs so every question below is one the codebase genuinely\n   cannot answer.\n2. **Replace the captured input / seed template with a real product plan** \u2014\n   what to build and why, and the user-facing behavior it should have,\n   grounded in the codebase. Leave *how* to build it for the next phase.\n3. **Iterate internally** (spawn further subagents, reconsider, cross-check)\n   until the plan is as complete as it can get without human input. Do not\n   leave this to a future round \u2014 there isn\'t one before the human is asked.\n4. For every remaining open question, write it near the top of the file with\n   a **suggested default** \u2014 your best-guess answer, stated plainly, that the\n   human can accept as-is. A question with no suggested default is incomplete.\n5. Leave `.gtd/TODO.md` **uncommitted** \u2014 the human\'s turn (`gtd step`) reads it\n   next.\n<% if (it.context.turnDiff && it.context.turnDiff.trim()) { %>\n<%~ include("@diff", { heading: "Latest human input (answers / sketch / review feedback)", diff: it.context.turnDiff, fenceFor: it.fenceFor }) %>\n\nRead the diff above as **feedback, not finished work**:\n\n- Code changes are suggestions \u2014 fold them into the plan and re-implement them\n  properly, including test coverage, rather than restoring them verbatim.\n- Code comments are positional feedback about the code at that location.\n- Plan-text changes are global feedback on the plan (or the reviewed work) as\n  a whole.\n<% } %>\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
 
 // src/prompts/grilling-answers.md
-var grilling_answers_default = '<%~ include("@header") %>\n\n`.gtd/TODO.md` holds the plan under development, with open questions written near\nthe top \u2014 each one carrying a suggested default.\n\nThis is a human gate; there is nothing for the agent to do.\n\nTell the user:\n\n- To answer a question, edit `.gtd/TODO.md` in place (replace the question\'s text\n  with your answer, or annotate it), then run `gtd step`.\n- To accept **all** suggested defaults as-is, run `gtd step` with **no\n  edits** \u2014 this converges the plan and moves on to decomposition.\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
+var grilling_answers_default = '<%~ include("@header") %>\n\n`.gtd/TODO.md` holds the plan under development, with open questions written near\nthe top \u2014 each one carrying a suggested default.\n\nThis is a human gate; there is nothing for the agent to do.\n\nTell the user:\n\n- To answer a question, edit `.gtd/TODO.md` in place (replace the question\'s text\n  with your answer, or annotate it), then run `gtd step`.\n- To accept **all** suggested defaults as-is, run `gtd step` with **no\n  edits** \u2014 this converges the plan and moves on to technical architecting.\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
+
+// src/prompts/architecting-agent.md
+var architecting_agent_default = '<%~ include("@header") %>\n\n`.gtd/ARCHITECTURE.md` holds the technical plan under development \u2014 seeded\nfrom the converged product plan, or, if this is the very first turn on\nalready-technical input, written directly by the human. Develop it into a concrete,\nimplementation-ready technical plan **in this one turn** \u2014 use subagents /\ninternal iteration to go as deep as needed; there is no further agent-only\nround after this one.\n\n**Scope: technical/architectural decisions only.** Decide file/module\nstructure, data models, module boundaries, library or tech-stack choices, and\nerror-handling/concurrency strategy \u2014 the *how*, building on the *what*\nalready settled in this file\'s product content. Do not re-open or re-litigate\nproduct/user-facing decisions from the prior phase; treat them as settled\ncontext.\n\n### Develop the architecture\n\nSpawn a **planning-model subagent** using model `<%= it.model %>` to develop the\narchitecture. The subagent works entirely by editing `.gtd/ARCHITECTURE.md`:\n\n1. **Explore the codebase before asking anything** \u2014 read the relevant files,\n   tests, and docs so every question below is one the codebase genuinely\n   cannot answer.\n2. **Replace the seeded/captured content with a real architecture** \u2014 the\n   files to change, module/data-model structure, and why, grounded in the\n   codebase.\n3. **Iterate internally** (spawn further subagents, reconsider, cross-check)\n   until the architecture is as complete as it can get without human input.\n   Do not leave this to a future round \u2014 there isn\'t one before the human is\n   asked.\n4. For every remaining open question, write it near the top of the file with\n   a **suggested default** \u2014 your best-guess answer, stated plainly, that the\n   human can accept as-is. A question with no suggested default is incomplete.\n5. Leave `.gtd/ARCHITECTURE.md` **uncommitted** \u2014 the human\'s turn (`gtd step`)\n   reads it next.\n<% if (it.context.turnDiff && it.context.turnDiff.trim()) { %>\n<%~ include("@diff", { heading: "Latest human input (answers / sketch / review feedback)", diff: it.context.turnDiff, fenceFor: it.fenceFor }) %>\n\nRead the diff above as **feedback, not finished work**:\n\n- Code changes are suggestions \u2014 fold them into the architecture and\n  re-implement them properly, including test coverage, rather than restoring\n  them verbatim.\n- Code comments are positional feedback about the code at that location.\n- Plan-text changes are global feedback on the architecture (or the reviewed\n  work) as a whole.\n<% } %>\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
+
+// src/prompts/architecting-answers.md
+var architecting_answers_default = '<%~ include("@header") %>\n\n`.gtd/ARCHITECTURE.md` holds the technical plan under development, with open\nquestions written near the top \u2014 each one carrying a suggested default.\n\nThis is a human gate; there is nothing for the agent to do.\n\nTell the user:\n\n- To answer a question, edit `.gtd/ARCHITECTURE.md` in place (replace the\n  question\'s text with your answer, or annotate it), then run `gtd step`.\n- To accept **all** suggested defaults as-is, run `gtd step` with **no\n  edits** \u2014 this converges the architecture and moves on to decomposition.\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
 
 // src/prompts/decompose.md
-var decompose_default = '<%~ include("@header") %>\n\n`.gtd/TODO.md` contains an implementation plan. Decompose it into an ordered set of\nexecutable work packages stored in the `.gtd/` directory. If `.gtd/` already\nholds packages from an earlier turn, immediately abort and raise an error.\n\nSpawn a **planning-model subagent** using model `<%= it.model %>` to perform the\ndecomposition. It creates numbered package directories, each holding numbered\ntask files:\n\n```\n.gtd/\n  01-<package-name>/\n    01-<task-name>.md\n    02-<task-name>.md\n  02-<package-name>/\n    ...\n```\n\n**Rules for the subagent:**\n\n1. **Packages are sequential, in dependency order** \u2014 ordinal-prefixed\n   directories (`01-`, `02-`, \u2026) execute in that order and the set is frozen\n   once written. Order them so each package depends only on lower-numbered ones.\n\n2. **Each package is green on its own** \u2014 the test suite runs after every\n   package. Never split a feature so the tree stays red until a later package\n   lands.\n\n3. **Tasks within a package are parallel and file-disjoint** \u2014 all tasks in a\n   package run simultaneously, each via one subagent, against the same working\n   tree with no isolation. Two tasks that would touch the same file must be\n   **merged** into one. If task B depends on task A, put them in separate\n   packages.\n\n4. **Vertical slices, not horizontal** \u2014 each package is a thin, end-to-end\n   slice that is demoable or verifiable on its own. Prefer many thin packages\n   over few thick ones; never a "set up infrastructure" package.\n\n5. **Task files are self-contained** \u2014 each task `.md` includes a clear\n   description of what to build, acceptance criteria as `- [ ] Criterion`\n   checkboxes, the relevant file paths to examine, and any constraints or edge\n   cases. It is the only context building agents will receive to work on the\n   task.\n\n6. **Specs must never reference `.gtd/` files** \u2014 `.gtd/TODO.md` is consumed\n   and **deleted** the moment decomposition completes, and every other file\n   under `.gtd/` (including these task specs) is machine-managed workflow\n   state. No task description, acceptance criterion, or constraint may require\n   creating, preserving, updating, or checking any `.gtd/` file \u2014 such a\n   criterion can never be satisfied and would derail the workflow.\n\n**DO NOT** commit any changes. This process runs within a larger orchestration\nthat depends on uncommitted changes.\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
+var decompose_default = '<%~ include("@header") %>\n\n`.gtd/ARCHITECTURE.md` contains a converged architecture/technical plan.\nDecompose it into an ordered set of executable work packages stored in the\n`.gtd/` directory. If `.gtd/` already holds packages from an earlier turn,\nimmediately abort and raise an error.\n\nSpawn a **planning-model subagent** using model `<%= it.model %>` to perform the\ndecomposition. It creates numbered package directories, each holding numbered\ntask files:\n\n```\n.gtd/\n  01-<package-name>/\n    01-<task-name>.md\n    02-<task-name>.md\n  02-<package-name>/\n    ...\n```\n\n**Rules for the subagent:**\n\n1. **Packages are sequential, in dependency order** \u2014 ordinal-prefixed\n   directories (`01-`, `02-`, \u2026) execute in that order and the set is frozen\n   once written. Order them so each package depends only on lower-numbered ones.\n\n2. **Each package is green on its own** \u2014 the test suite runs after every\n   package. Never split a feature so the tree stays red until a later package\n   lands.\n\n3. **Tasks within a package are parallel and file-disjoint** \u2014 all tasks in a\n   package run simultaneously, each via one subagent, against the same working\n   tree with no isolation. Two tasks that would touch the same file must be\n   **merged** into one. If task B depends on task A, put them in separate\n   packages.\n\n4. **Vertical slices, not horizontal** \u2014 each package is a thin, end-to-end\n   slice that is demoable or verifiable on its own. Prefer many thin packages\n   over few thick ones; never a "set up infrastructure" package.\n\n5. **Task files are self-contained** \u2014 each task `.md` includes a clear\n   description of what to build, acceptance criteria as `- [ ] Criterion`\n   checkboxes, the relevant file paths to examine, and any constraints or edge\n   cases. It is the only context building agents will receive to work on the\n   task.\n\n6. **Specs must never reference `.gtd/` files** \u2014 `.gtd/ARCHITECTURE.md` is\n   consumed and **deleted** the moment decomposition completes, and every other file\n   under `.gtd/` (including these task specs) is machine-managed workflow\n   state. No task description, acceptance criterion, or constraint may require\n   creating, preserving, updating, or checking any `.gtd/` file \u2014 such a\n   criterion can never be satisfied and would derail the workflow.\n\n**DO NOT** commit any changes. This process runs within a larger orchestration\nthat depends on uncommitted changes.\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
 
 // src/prompts/building.md
 var building_default = '<%~ include("@header") %>\n\nBuild the package described below by orchestrating the execution \u2014 you do not\nimplement the tasks yourself. Spawn **one subagent per task**, all in\n**parallel**, each using model `<%= it.model %>`:\n\n- **Context**: the task content only (it is self-contained).\n- **Fresh context**: each worker starts cold, with no shared history.\n- **Hands off `.gtd/`** (inline rule for workers): never create, edit, or\n  delete anything under `.gtd/` \u2014 it is workflow state owned by the machine.\n  If the task spec mentions a `.gtd/` file, skip that part.\n- **TDD discipline** (inline rules for workers):\n  - Write ONE test \u2192 implement \u2192 pass \u2192 repeat (vertical slices).\n  - **Do NOT** write all tests first then implement (horizontal slicing).\n  - Tests verify behavior through public interfaces, not implementation details\n    \u2014 a good test survives a refactor.\n\nWait for all workers to complete. **If any worker fails** (crash, timeout, error\n\u2014 not a test failure): report which tasks failed and ask the user whether to\nretry the failed tasks, skip and continue, or abort.\n\nLeave all changes uncommitted. An outside process handles that.\n<% if (it.context.packages[0]) { %>\n<%~ include("@package", { pkg: it.context.packages[0], fenceFor: it.fenceFor }) %>\n<% } %>\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
@@ -389414,7 +389613,16 @@ var review_default = '<%~ include("@header") %>\n\nSpawn a **planning-model suba
 var await_review_default = '<%~ include("@header") %>\n\n`.gtd/REVIEW.md` holds the review record for the completed work. This is a human\ngate; there is nothing for the agent to do.\n\nTell the user:\n\n- Read `.gtd/REVIEW.md` (and the underlying work it points at).\n- To **approve**: run `gtd step` with no edits, or only tick checkboxes in\n  `.gtd/REVIEW.md` \u2014 either way ends the review with an approval.\n- To **request changes**: write substantive edits or annotations into\n  `.gtd/REVIEW.md` (or the code) describing what\'s wrong, then run `gtd step` \u2014\n  this sends the feedback back for another round.\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
 
 // src/prompts/squashing.md
-var squashing_default = '<%~ include("@header") %>\n\nThe process is **approved and done**. `.gtd/SQUASH_MSG.md` has already been\ncommitted with a template \u2014 your job is to overwrite it with the real\nconventional-commits squash message and finish your turn.\n\n### Step 1 \u2014 Extract decisions from grilling rounds\n\nScan the git history of recent `gtd: ...` / `gtd(agent): ...` /\n`gtd(human): ...` commits. Look for changes to `.gtd/TODO.md` \u2014 specifically the\n`## Captured input` sections and any edits to plan text. Extract **key\ndecisions, trade-offs, and design choices** made during grilling rounds. These\nwill appear in the commit body so the history is self-documenting.\n\n### Step 2 \u2014 Draft the commit message\n\nDraft ONE conventional-commits message:\n\n```\ntype(scope): subject\n\nbody (explain the why \u2014 motivation, trade-offs, key decisions from grilling)\n```\n\n- **type**: `feat` / `fix` / `refactor` / `chore` / `docs` / `test`\n- **subject**: imperative mood, \u2264 72 characters, lowercase after the colon\n- **body**: include the important decisions / trade-offs from grilling\n  sessions. Omit if there were no meaningful decisions to capture.\n\n### Step 3 \u2014 Overwrite .gtd/SQUASH_MSG.md\n\nReplace the **entire content** of `.gtd/SQUASH_MSG.md` (plain text, no markdown\nwrapper, no leftover template scaffolding) with the message from Step 2, then\nleave it uncommitted and finish your turn \u2014 `gtd step-agent` performs the\nsquash using this file\'s content.\n<% if (it.context.squashDiff && it.context.squashDiff.trim()) { %>\n<%= it.context.squashBase !== undefined ? "\\nSquash base: " + it.context.squashBase + "\\n" : "" %>\n<%~ include("@diff", { heading: "Full-process diff (`git diff " + (it.context.squashBase !== undefined ? it.context.squashBase : "<squashBase>") + " HEAD`)", diff: it.context.squashDiff, fenceFor: it.fenceFor }) %>\n<% } %>\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
+var squashing_default = '<%~ include("@header") %>\n\nThe process is **approved and done**. `.gtd/SQUASH_MSG.md` has already been\ncommitted with a template \u2014 your job is to overwrite it with the real\nconventional-commits squash message and finish your turn.\n\n### Step 1 \u2014 Extract decisions from grilling rounds\n\nScan the git history of recent `gtd: ...` / `gtd(agent): ...` /\n`gtd(human): ...` commits. Look for changes to `.gtd/TODO.md` and\n`.gtd/ARCHITECTURE.md` \u2014 specifically the `## Captured input` sections and any\nedits to plan/architecture text. Extract **key decisions, trade-offs, and\ndesign choices** made during grilling and architecting rounds. These will\nappear in the commit body so the history is self-documenting.\n\n### Step 2 \u2014 Draft the commit message\n\nDraft ONE conventional-commits message:\n\n```\ntype(scope): subject\n\nbody (explain the why \u2014 motivation, trade-offs, key decisions from grilling)\n```\n\n- **type**: `feat` / `fix` / `refactor` / `chore` / `docs` / `test`\n- **subject**: imperative mood, \u2264 72 characters, lowercase after the colon\n- **body**: include the important decisions / trade-offs from grilling\n  sessions. Omit if there were no meaningful decisions to capture.\n\n### Step 3 \u2014 Overwrite .gtd/SQUASH_MSG.md\n\nReplace the **entire content** of `.gtd/SQUASH_MSG.md` (plain text, no markdown\nwrapper, no leftover template scaffolding) with the message from Step 2, then\nleave it uncommitted and finish your turn \u2014 `gtd step-agent` performs the\nsquash using this file\'s content.\n<% if (it.context.squashDiff && it.context.squashDiff.trim()) { %>\n<%= it.context.squashBase !== undefined ? "\\nSquash base: " + it.context.squashBase + "\\n" : "" %>\n<%~ include("@diff", { heading: "Full-process diff (`git diff " + (it.context.squashBase !== undefined ? it.context.squashBase : "<squashBase>") + " HEAD`)", diff: it.context.squashDiff, fenceFor: it.fenceFor }) %>\n<% } %>\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
+
+// src/prompts/learning.md
+var learning_default = '<%~ include("@header") %>\n\nThe process is **approved and done**, and headed for a squash. Before that\nhappens, `.gtd/LEARNINGS.md` has been committed with a template \u2014 your job is\nto overwrite it with the real, distilled learnings from this cycle so they\nsurvive the squash even though the granular history won\'t.\n\n### Step 1 \u2014 Walk the cycle\'s history\n\nScan the git history back to the cycle\'s start (the full-process diff is\ninlined below, and `git log` over the same range shows every `gtd: ...` /\n`gtd(agent): ...` / `gtd(human): ...` commit). Look specifically for:\n\n- **Test failures and fixes** \u2014 each `gtd: errors` round and the fix that\n  followed it. What broke, and what actually made it pass?\n- **Review feedback** \u2014 human `.gtd/REVIEW.md` notes and `gtd: review\n  feedback` detours. What did the human have to correct that the agent got\n  wrong on its own?\n- **Health-check rounds** \u2014 any `gtd: health-check` / `gtd: health-fix`\n  cycles. Environmental or systemic issues surfaced outside normal building?\n- **Grilling decisions** \u2014 `.gtd/TODO.md`\'s "## Captured input" sections and\n  plan edits. Trade-offs or conventions the human specified that a future\n  agent should already know.\n\n### Step 2 \u2014 Distill, don\'t transcribe\n\nFor each thing you found, ask: is this a **durable, generalizable lesson**\n(a convention, a gotcha, a pattern this project wants followed next time), or\na **one-off detail** specific to this change? Keep only the former. A future\nagent reading this should learn something that changes how it works on this\nproject, not a recap of what happened.\n\n### Step 3 \u2014 Overwrite .gtd/LEARNINGS.md\n\nReplace the **entire content** of `.gtd/LEARNINGS.md` with your distilled\nlearnings (plain markdown, no leftover template scaffolding). If nothing\ndurable surfaced this cycle, write a short explicit note saying so \u2014 don\'t\nleave the placeholder text in place. Leave the file uncommitted and finish\nyour turn; a human reviews it next before it\'s integrated into the project\'s\nown memory (CLAUDE.md/AGENTS.md/docs).\n<% if (it.context.squashDiff && it.context.squashDiff.trim()) { %>\n<%= it.context.squashBase !== undefined ? "\\nCycle base: " + it.context.squashBase + "\\n" : "" %>\n<%~ include("@diff", { heading: "Full-process diff (`git diff " + (it.context.squashBase !== undefined ? it.context.squashBase : "<squashBase>") + " HEAD`)", diff: it.context.squashDiff, fenceFor: it.fenceFor }) %>\n<% } %>\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
+
+// src/prompts/await-learning-review.md
+var await_learning_review_default = "<%~ include(\"@header\") %>\n\n`.gtd/LEARNINGS.md` holds the distilled learnings from this cycle, drafted by\nthe agent. This is a human gate; there is nothing for the agent to do.\n\nTell the user:\n\n- Read `.gtd/LEARNINGS.md`.\n- Delete anything not worth keeping, or edit/add anything the draft missed.\n- Run `gtd step` \u2014 with or without edits, either way proceeds: the agent\n  integrates whatever remains into the project's own memory\n  (CLAUDE.md/AGENTS.md/docs) next.\n\nThere is no reject path \u2014 this gate only refines what gets kept, it doesn't\nsend the cycle back for rework.\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n";
+
+// src/prompts/learning-apply.md
+var learning_apply_default = "<%~ include(\"@header\") %>\n\nThe human has approved (and possibly amended) `.gtd/LEARNINGS.md`. Your job is\nto integrate those learnings into the project's own memory, not to touch\n`.gtd/LEARNINGS.md` itself.\n\n1. **Read `.gtd/LEARNINGS.md`.**\n2. **Pick the right home for each point**, using your judgment and this\n   project's existing convention:\n   - An existing `CLAUDE.md` or `AGENTS.md` at the repo root (or a directory\n     closer to what the learning concerns) is usually the right place.\n   - If neither exists and the learnings warrant one, create `AGENTS.md` at\n     the repo root.\n   - A learning about a specific subsystem may fit better in that\n     subsystem's own docs than a root-level file \u2014 use your judgment.\n3. **Integrate, don't just append** \u2014 merge each point into the relevant\n   section of the target file(s); rephrase for clarity, dedupe against what's\n   already documented, and keep the existing document's structure and tone.\n4. **Never delete or edit `.gtd/LEARNINGS.md`** \u2014 the machine removes it once\n   your turn is captured.\n5. **Leave every change uncommitted and finish your turn.**\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n";
 
 // src/prompts/escalate.md
 var escalate_default = '<%~ include("@header") %>\n\nThe agent was not able to fix all errors on its own. The last error report is\nstored in `.gtd/ERRORS.md` for a human to investigate.\n\nNext steps for the human developer:\n\n1. Investigate and fix errors reported in `.gtd/ERRORS.md`\n2. Delete `.gtd/ERRORS.md`\n3. Run `gtd step` when you are ready to continue\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
@@ -389425,6 +389633,7 @@ var idle_default = "The repository is idle \u2014 no work cycle is in progress a
 // src/Prompt.ts
 var PROMPT_STATES = /* @__PURE__ */ new Set([
   "grilling",
+  "architecting",
   "grilled",
   "building",
   "fixing",
@@ -389432,6 +389641,9 @@ var PROMPT_STATES = /* @__PURE__ */ new Set([
   "review",
   "await-review",
   "squashing",
+  "learning",
+  "await-learning-review",
+  "learning-apply",
   "escalate",
   "idle",
   "health-fixing"
@@ -389439,13 +389651,16 @@ var PROMPT_STATES = /* @__PURE__ */ new Set([
 var isPromptState = (state) => PROMPT_STATES.has(state);
 var MODEL_STATE = {
   grilling: "grilling",
+  architecting: "architecting",
   grilled: "decompose",
   building: "building",
   fixing: "fixing",
   "health-fixing": "fixing",
   "agentic-review": "agentic-review",
   review: "clean",
-  squashing: "clean"
+  squashing: "clean",
+  learning: "clean",
+  "learning-apply": "clean"
 };
 var builtinResolveModel = (state) => builtinTierDefault[stateTier[state]];
 var fenceFor = (content) => {
@@ -389461,6 +389676,8 @@ eta.loadTemplate("@package", package_default);
 eta.loadTemplate("@agent-turn", agent_turn_default);
 eta.loadTemplate("@grilling-agent", grilling_agent_default);
 eta.loadTemplate("@grilling-answers", grilling_answers_default);
+eta.loadTemplate("@architecting-agent", architecting_agent_default);
+eta.loadTemplate("@architecting-answers", architecting_answers_default);
 eta.loadTemplate("@decompose", decompose_default);
 eta.loadTemplate("@building", building_default);
 eta.loadTemplate("@fixing", fixing_default);
@@ -389469,6 +389686,9 @@ eta.loadTemplate("@agentic-review", agentic_review_default);
 eta.loadTemplate("@review", review_default);
 eta.loadTemplate("@await-review", await_review_default);
 eta.loadTemplate("@squashing", squashing_default);
+eta.loadTemplate("@learning", learning_default);
+eta.loadTemplate("@await-learning-review", await_learning_review_default);
+eta.loadTemplate("@learning-apply", learning_apply_default);
 eta.loadTemplate("@escalate", escalate_default);
 eta.loadTemplate("@idle", idle_default);
 eta.readFile = null;
@@ -389481,6 +389701,9 @@ var STATE_TEMPLATE = {
   review: "@review",
   "await-review": "@await-review",
   squashing: "@squashing",
+  learning: "@learning",
+  "await-learning-review": "@await-learning-review",
+  "learning-apply": "@learning-apply",
   escalate: "@escalate",
   idle: "@idle",
   "health-fixing": "@health-fixing"
@@ -389497,6 +389720,8 @@ var buildPrompt = (result, resolveModel = builtinResolveModel, output = "plain")
   let templateName;
   if (promptState === "grilling") {
     templateName = result.actor === "human" ? "@grilling-answers" : "@grilling-agent";
+  } else if (promptState === "architecting") {
+    templateName = result.actor === "human" ? "@architecting-answers" : "@architecting-agent";
   } else {
     templateName = STATE_TEMPLATE[promptState];
   }
@@ -389587,11 +389812,15 @@ var edgeActionHandlers = {
   captureTurn: (a5) => `capture the ${a5.actor} turn as "gtd(${a5.actor}): ${a5.gate}"`,
   commitRouting: (a5) => {
     let msg = `commit routing as "${a5.subject}"`;
+    if (a5.seedArchitectureFromTodo) {
+      msg += " (seeding .gtd/ARCHITECTURE.md from .gtd/TODO.md)";
+    }
     const removed = [];
-    if (a5.removeTodo) removed.push(".gtd/TODO.md");
+    if (a5.removeArchitecture) removed.push(".gtd/ARCHITECTURE.md");
     if (a5.removeReview) removed.push(".gtd/REVIEW.md");
     if (a5.removeFeedback) removed.push(".gtd/FEEDBACK.md");
     if (a5.removeHealth) removed.push(".gtd/HEALTH.md");
+    if (a5.removeLearning) removed.push(".gtd/LEARNINGS.md");
     if (removed.length > 0) msg += ` (removing ${removed.join(", ")})`;
     return msg;
   },
@@ -389599,7 +389828,8 @@ var edgeActionHandlers = {
   closePackage: () => "close the active package",
   writeSquashTemplate: () => "write the squash message template",
   squashCommit: (a5) => `squash the cycle onto ${a5.squashBase}`,
-  runHealthCheck: (a5) => `run the health check (attempt ${a5.errorCount + 1}${a5.capReached ? ", cap reached" : ""}${a5.squashAfterGreen ? ", squash after green" : ""})`
+  writeLearningTemplate: () => "write the learnings template",
+  runHealthCheck: (a5) => `run the health check (attempt ${a5.errorCount + 1}${a5.capReached ? ", cap reached" : ""}${a5.chainAfterGreen ? ", chain after green" : ""})`
 };
 var describeEdgeAction = (a5) => edgeActionHandlers[a5.kind](a5);
 var describeStatus = (prediction) => ({