@agentshouse/kit 0.1.0-alpha.25 → 0.1.0-alpha.27

package/src/google/oauth.js

@@ -1,8 +1,10 @@
 import { createHash, randomBytes, randomInt } from "node:crypto";
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { readFile, rm } from "node:fs/promises";
 import { KitRefusal } from "../refusal.js";
-import { writeNote } from "../state.js";
+import { notePath, writeNote } from "../state.js";
+import { exclusively } from "../tasks.js";
+
+export const GOOGLE_SOURCES = "google";
 
 export const GOOGLE_SCOPES = Object.freeze({
   gmail: "https://www.googleapis.com/auth/gmail.readonly",
@@ -12,26 +14,30 @@ export const GOOGLE_SCOPES = Object.freeze({
 
 const AUTHORIZATION_ENDPOINT = "https://accounts.google.com/o/oauth2/v2/auth";
 const TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+const REVOCATION_ENDPOINT = "https://oauth2.googleapis.com/revoke";
 const REFRESH_MARGIN_MS = 60_000;
 const LOOPBACK_PORT_FLOOR = 49152;
 const LOOPBACK_PORT_SPAN = 16384;
 
-function credentialPath(directory, instance) {
-  return join(directory, "state", instance, "credentials", "google.json");
+function credentialPath(directory, account) {
+  return notePath(directory, GOOGLE_SOURCES, account, "credentials");
 }
 
-async function rawAuthorization(directory, instance) {
-  const path = credentialPath(directory, instance);
+async function rawAccount(directory, account) {
+  const path = credentialPath(directory, account);
   let document;
   try {
     document = JSON.parse(await readFile(path, "utf8"));
   } catch (error) {
     if (error.code === "ENOENT") return null;
-    throw new KitRefusal("google_authorization_unreadable", instance);
+    throw new KitRefusal("google_authorization_unreadable", account);
   }
   if (
     typeof document !== "object" ||
     document === null ||
+    typeof document.client?.id !== "string" ||
+    typeof document.client.secret !== "string" ||
+    (document.email !== null && typeof document.email !== "string") ||
     !Array.isArray(document.grants) ||
     document.grants.some(
       (grant) =>
@@ -46,21 +52,27 @@ async function rawAuthorization(directory, instance) {
         grant.scopes.some((scope) => typeof scope !== "string"),
     )
   ) {
-    throw new KitRefusal("google_authorization_unreadable", instance);
+    throw new KitRefusal("google_authorization_unreadable", account);
   }
   return document;
 }
 
-async function writeAuthorization(directory, instance, authorization) {
-  await writeNote(credentialPath(directory, instance), authorization);
+function updateAccount(directory, account, change) {
+  return exclusively(credentialPath(directory, account), async () => {
+    const stored = await rawAccount(directory, account);
+    const changed = change(stored);
+    if (changed !== null) await writeNote(credentialPath(directory, account), changed);
+  });
 }
 
-export async function googleAuthorization(directory, instance) {
-  const authorization = await rawAuthorization(directory, instance);
-  if (authorization === null || authorization.grants.length === 0) return null;
+export async function googleAccount(directory, account) {
+  const stored = await rawAccount(directory, account);
+  if (stored === null) return null;
   return {
-    scopes: [...new Set(authorization.grants.flatMap((grant) => grant.scopes))].sort(),
-    grants: authorization.grants.map((grant) => ({
+    client: { id: stored.client.id, secret: stored.client.secret },
+    email: stored.email,
+    scopes: [...new Set(stored.grants.flatMap((grant) => grant.scopes))].sort(),
+    grants: stored.grants.map((grant) => ({
       accessToken: grant.access_token,
       refreshToken: grant.refresh_token,
       expiresAt: grant.expires_at,
@@ -69,6 +81,15 @@ export async function googleAuthorization(directory, instance) {
   };
 }
 
+export async function googleSignedIn(directory, account, service) {
+  const stored = await rawAccount(directory, account);
+  return stored?.grants.some((grant) => grant.scopes.includes(GOOGLE_SCOPES[service])) === true;
+}
+
+export function recordGoogleEmail(directory, account, email) {
+  return updateAccount(directory, account, (stored) => (stored === null ? null : { ...stored, email }));
+}
+
 function requiredScopesOf(value) {
   if (
     !Array.isArray(value) ||
@@ -80,19 +101,51 @@ function requiredScopesOf(value) {
   return value;
 }
 
-export async function revokeGoogleAuthorization(directory, instance, scopes) {
+export async function revokeGoogleAuthorization(directory, account, scopes) {
   const requiredScopes = requiredScopesOf(scopes);
-  const authorization = await rawAuthorization(directory, instance);
-  if (authorization !== null) {
-    await writeAuthorization(directory, instance, {
-      grants: authorization.grants
-        .map((grant) => ({
-          ...grant,
-          scopes: grant.scopes.filter((scope) => !requiredScopes.includes(scope)),
-        }))
-        .filter((grant) => grant.scopes.length > 0),
+  await updateAccount(directory, account, (stored) =>
+    stored === null
+      ? null
+      : {
+          ...stored,
+          grants: stored.grants
+            .map((grant) => ({
+              ...grant,
+              scopes: grant.scopes.filter((scope) => !requiredScopes.includes(scope)),
+            }))
+            .filter((grant) => grant.scopes.length > 0),
+        },
+  );
+}
+
+async function revokedAtProvider(fetcher, token) {
+  let response;
+  try {
+    response = await fetcher(REVOCATION_ENDPOINT, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ token }).toString(),
     });
+  } catch {
+    throw new KitRefusal("google_provider_unavailable");
   }
+  if (response.status !== 200 && response.status !== 400) {
+    throw new KitRefusal("google_provider_unavailable");
+  }
+}
+
+export async function forgetGoogleAccount(directory, account, kept, dependencies = {}) {
+  const stored = await rawAccount(directory, account);
+  if (stored === null) return;
+  const others = await Promise.all(kept.map((other) => rawAccount(directory, other)));
+  if (stored.email === null || !others.some((held) => held?.email === stored.email)) {
+    for (const grant of stored.grants) {
+      await revokedAtProvider(dependencies.fetch ?? fetch, grant.refresh_token);
+    }
+  }
+  await exclusively(credentialPath(directory, account), () =>
+    rm(credentialPath(directory, account), { force: true }),
+  );
 }
 
 function oauthValue() {
@@ -167,26 +220,9 @@ async function tokenRequest(fetcher, body) {
   return answer;
 }
 
-function configuredClient(client) {
-  if (
-    typeof client?.id !== "string" ||
-    client.id.length === 0 ||
-    typeof client.secret !== "string" ||
-    client.secret.length === 0
-  ) {
-    throw new KitRefusal("google_oauth_client_unconfigured");
-  }
-  return client;
-}
-
 export async function authorizeGoogle(options, dependencies = {}) {
-  const client = configuredClient(options.client);
-  const stored = await rawAuthorization(options.directory, options.instance);
+  const { client } = options;
   const scopes = [...new Set(options.scopes)];
-  const covered = stored?.grants.some((grant) =>
-    scopes.every((scope) => grant.scopes.includes(scope)),
-  );
-  if (covered === true) return { status: "skipped", requestedScopes: [] };
   const verifier = oauthValue();
   const state = oauthValue();
   const redirectUri = loopbackRedirect(dependencies.loopbackPort);
@@ -215,10 +251,11 @@ export async function authorizeGoogle(options, dependencies = {}) {
   }
   const grantedScopes = [...new Set(returnedScopes.length === 0 ? scopes : returnedScopes)].sort();
   const key = grantedScopes.join("\n");
-  const grants = (stored?.grants ?? []).filter((grant) => [...grant.scopes].sort().join("\n") !== key);
-  await writeAuthorization(options.directory, options.instance, {
+  await updateAccount(options.directory, options.account, (stored) => ({
+    client: { id: client.id, secret: client.secret },
+    email: stored?.email ?? null,
     grants: [
-      ...grants,
+      ...(stored?.grants ?? []).filter((grant) => [...grant.scopes].sort().join("\n") !== key),
       {
         access_token: token.access_token,
         refresh_token: refreshToken,
@@ -226,48 +263,51 @@ export async function authorizeGoogle(options, dependencies = {}) {
         scopes: grantedScopes,
       },
     ],
-  });
-  return { status: "ready", requestedScopes: scopes };
+  }));
 }
 
 export async function googleAccessToken(options, dependencies = {}) {
-  const stored = await rawAuthorization(options.directory, options.instance);
+  const stored = await rawAccount(options.directory, options.account);
   const requiredScopes = requiredScopesOf(options.requiredScopes);
   const grant = stored?.grants
     .filter((candidate) => requiredScopes.every((scope) => candidate.scopes.includes(scope)))
     .sort((left, right) => left.scopes.length - right.scopes.length)[0];
   if (grant === undefined) {
-    throw new KitRefusal("google_authorization_required", options.instance);
+    throw new KitRefusal("google_authorization_required", options.account);
   }
   const now = dependencies.now?.() ?? new Date();
   if (options.forceRefresh !== true && Date.parse(grant.expires_at) - now.getTime() > REFRESH_MARGIN_MS) {
     return grant.access_token;
   }
-  const client = configuredClient(options.client);
   let token;
   try {
     token = await tokenRequest(dependencies.fetch ?? fetch, {
-      client_id: client.id,
-      client_secret: client.secret,
+      client_id: stored.client.id,
+      client_secret: stored.client.secret,
       refresh_token: grant.refresh_token,
       grant_type: "refresh_token",
     });
   } catch (error) {
     if (error instanceof KitRefusal && error.code === "google_authority_revoked") {
-      await revokeGoogleAuthorization(options.directory, options.instance, grant.scopes);
+      await revokeGoogleAuthorization(options.directory, options.account, grant.scopes);
     }
     throw error;
   }
-  await writeAuthorization(options.directory, options.instance, {
-    grants: stored.grants.map((candidate) =>
-      candidate === grant
-        ? {
-            ...candidate,
-            access_token: token.access_token,
-            expires_at: new Date(now.getTime() + token.expires_in * 1000).toISOString(),
-          }
-        : candidate,
-    ),
-  });
+  await updateAccount(options.directory, options.account, (current) =>
+    current === null
+      ? null
+      : {
+          ...current,
+          grants: current.grants.map((candidate) =>
+            candidate.refresh_token === grant.refresh_token
+              ? {
+                  ...candidate,
+                  access_token: token.access_token,
+                  expires_at: new Date(now.getTime() + token.expires_in * 1000).toISOString(),
+                }
+              : candidate,
+          ),
+        },
+  );
   return token.access_token;
 }

package/src/google/source.js

@@ -1,25 +1,23 @@
-import { KitRefusal } from "../refusal.js";
-import { gmailPage } from "./gmail.js";
-import { calendarPage } from "./calendar.js";
-import { drivePage } from "./drive.js";
-import { declaredPage } from "./declared.js";
+import { calendarEmail, calendarPage } from "./calendar.js";
+import { driveEmail, drivePage } from "./drive.js";
+import { gmailEmail, gmailPage } from "./gmail.js";
+import { googleAccount, recordGoogleEmail } from "./oauth.js";
 
-export async function googlePage(options, dependencies = {}) {
-  const common = {
-    directory: options.directory,
-    instance: options.instance,
-    client: options.client,
-    selection: options.service.selection,
-    cursor: options.cursor,
-    limit: options.limit,
-    backfillFloor: options.backfillFloor,
-    signal: options.signal,
-  };
-  if (options.service.service === "gmail") return gmailPage(common, dependencies);
-  if (options.service.service === "calendar") return calendarPage(common, dependencies);
-  if (options.service.service === "drive") return drivePage(common, dependencies);
-  if (options.service.declaration !== null) {
-    return declaredPage({ ...common, service: options.service }, dependencies);
-  }
-  throw new KitRefusal("google_service_unsupported", options.service.service);
+const SERVICES = {
+  gmail: { page: gmailPage, email: gmailEmail },
+  calendar: { page: calendarPage, email: calendarEmail },
+  drive: { page: drivePage, email: driveEmail },
+};
+
+export function googlePage(options, dependencies = {}) {
+  return SERVICES[options.service].page(options, dependencies);
+}
+
+export async function recordAccountEmail(context, google) {
+  if ((await googleAccount(context.directory, google.account))?.email !== null) return;
+  const email = await SERVICES[google.service].email(
+    { directory: context.directory, account: google.account, signal: context.signal },
+    context.dependencies,
+  );
+  await recordGoogleEmail(context.directory, google.account, email);
 }

package/src/house.js

@@ -24,6 +24,8 @@ import {
   KIT_SESSIONS_REPORT_PATH,
   KIT_SETUP_ACQUIRE_PATH,
   KIT_SETUP_REPORT_PATH,
+  KIT_SOURCES_DESIRED_PATH,
+  KIT_SOURCES_REPORT_PATH,
   KIT_WORKSPACES_ACQUIRE_PATH,
   LEASE_RENEWAL_MARGIN_MS,
   MCP_PROTOCOL_VERSION,
@@ -172,7 +174,7 @@ async function residentRelay(session, request, signal, draining) {
   }
 }
 
-export async function serveResident(session, directory, signal, drain, push) {
+export async function serveResident(session, directory, signal, drain, push, capture) {
   const socket = residentSocket(directory);
   await mkdir(dirname(socket), { recursive: true, mode: 0o700 });
   await rm(socket, { force: true });
@@ -231,9 +233,14 @@ export async function serveResident(session, directory, signal, drain, push) {
         relayed.set(request.id, cancelled);
         const relaySignal = AbortSignal.any([signal, cancelled.signal]);
         const answered =
-          request.push === undefined
-            ? residentRelay(session, request, relaySignal, draining)
-            : push(request.push, relaySignal).then((pushed) => ({ pushed }));
+          request.push !== undefined
+            ? push(request.push, relaySignal).then((pushed) => ({ pushed }))
+            : request.capture !== undefined
+              ? capture(request.capture, relaySignal).then(
+                  (captured) => ({ captured }),
+                  (error) => ({ refused: error?.code ?? "kit_resident_unavailable" }),
+                )
+              : residentRelay(session, request, relaySignal, draining);
         void answered.then((answer) => {
           relayed.delete(request.id);
           if (!connection.destroyed) writeFrame(connection, { id: request.id, ...answer });
@@ -330,6 +337,12 @@ async function residentDelegation(directory, fetcher) {
     if (answer.pushed === undefined) throw new KitRefusal("kit_resident_unavailable");
     return answer.pushed;
   }
+  async function capture(source, signal) {
+    const answer = await exchange({ capture: source }, signal);
+    if (answer.refused !== undefined) throw new KitRefusal(answer.refused);
+    if (answer.captured === undefined) throw new KitRefusal("kit_resident_unavailable");
+    return answer.captured;
+  }
   async function delegated(url, init = {}) {
     const { authorization, ...headers } = init.headers ?? {};
     if (authorization !== RESIDENT) return fetcher(url, init);
@@ -352,7 +365,7 @@ async function residentDelegation(directory, fetcher) {
       headers: answer.type === null ? {} : { "content-type": answer.type },
     });
   }
-  return { connection, fetch: delegated, push };
+  return { connection, fetch: delegated, push, capture };
 }
 
 export async function openSession(options, dependencies = {}) {
@@ -372,6 +385,7 @@ export async function openSession(options, dependencies = {}) {
   if (resident !== null) {
     session.resident = resident.connection;
     session.push = resident.push;
+    session.capture = resident.capture;
     session.dependencies = { ...dependencies, fetch: resident.fetch };
     return session;
   }
@@ -695,6 +709,30 @@ export async function desiredAgents(session, signal = session.signal) {
   return answer.agents;
 }
 
+export async function desiredSources(session, signal = session.signal) {
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    KIT_SOURCES_DESIRED_PATH,
+    {},
+    session.dependencies,
+    signal,
+  );
+  if (!Array.isArray(answer?.sources)) throw new KitRefusal("kit_sources_rejected");
+  return answer.sources;
+}
+
+export async function reportSources(session, sources, signal = session.signal) {
+  return houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    KIT_SOURCES_REPORT_PATH,
+    { sources },
+    session.dependencies,
+    signal,
+  );
+}
+
 const HOUSE_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 export async function acquireSetup(session, signal = session.signal) {

package/src/how-we-work.md

@@ -0,0 +1,25 @@
+# How we work
+
+A Room is where information people share is kept; it is not the place for
+private information. Work goes into the Room it belongs to, or the First Room
+when none is named. Read and write Rooms with the `house` CLI.
+
+The skills are already set up; never run `setup-matt-pocock-skills`.
+
+## Where skill output goes
+
+- Glossary (`CONTEXT.md`): `library/glossary.md`
+- Decisions (ADRs): `library/decisions/NNNN-<slug>.md`
+- Plan (spec): `library/projects/<name>/plan.md`
+- Tasks (tickets): `library/projects/<name>/tasks/NN-<slug>.md`, with a
+  `Status:` line (`needs-triage`, `needs-info`, `ready-for-agent`,
+  `ready-for-human`, `wontfix`), a `Blocked by:` line and comments under
+  `## Comments`
+- Map (Wayfinding): `library/projects/<name>/map.md`, its tasks under
+  `tasks/` with `Type:`, `Status: claimed|resolved` and `Blocked by:` lines
+- Research: `library/research/<slug>.md`
+- Questionnaires: `library/questionnaires/<slug>.md`
+- Learning: `library/learning/<topic>/`
+- Files a person should open, such as HTML pages, are uploaded to the Room and
+  linked from the document they belong to; a prototype is one HTML file with
+  every variant on one page.

package/src/kit-work-stream.js

@@ -5,7 +5,7 @@ import { heldControl } from "./house.js";
 import { KitRefusal } from "./refusal.js";
 
 const PROTOCOL = "house.kit.stream.1";
-const WATCHED_SUBJECTS = ["agents", "working_copy"];
+const WATCHED_SUBJECTS = ["agents", "working_copy", "sources"];
 
 function streamAddress(house) {
   const url = new URL("/kit/stream", house);

package/src/launcher.js

@@ -1,5 +1,9 @@
 import { randomUUID } from "node:crypto";
-import { commandHouseHowWeWork, commandHouseInstructions } from "./adapter-mcp.js";
+import {
+  commandHouseCreateHowWeWork,
+  commandHouseHowWeWork,
+  commandHouseInstructions,
+} from "./adapter-mcp.js";
 import {
   compiledContract,
   initializeCommandAdapter,
@@ -129,8 +133,11 @@ async function configureSession(acp, contract, sessionId, adapter) {
   }
 }
 
-async function sessionOpening(bridge, baseInstructions) {
-  const parts = [HOUSE_CLI_LINE, baseInstructions, await commandHouseHowWeWork(bridge)];
+async function sessionOpening(channel, bridge, start) {
+  if (start.create_how_we_work === true && (await commandHouseCreateHowWeWork(bridge))) {
+    channel.send({ type: "how_we_work" });
+  }
+  const parts = [HOUSE_CLI_LINE, start.base_instructions, await commandHouseHowWeWork(bridge)];
   return [{ type: "text", text: parts.filter((part) => part.trim() !== "").join("\n\n") }];
 }
 
@@ -185,7 +192,7 @@ async function runTurn(channel, start, bridge, turn) {
     const instructions = await commandHouseInstructions(bridge);
     let providerSessionId = start.provider_session ?? null;
     const opening =
-      providerSessionId === null ? await sessionOpening(bridge, start.base_instructions) : [];
+      providerSessionId === null ? await sessionOpening(channel, bridge, start) : [];
     const setup = { cwd: start.working_directory, mcpServers: [] };
     if (providerSessionId === null) {
       providerSessionId = openedSession(await acp.request("session/new", setup));

package/src/mcp.js

@@ -82,3 +82,8 @@ export function answerYaml(text) {
     return null;
   }
 }
+
+export function editRefusal(text) {
+  const conflicts = answerYaml(text.slice(text.indexOf("\n") + 1))?.conflicts;
+  return { code: text.split(":")[0].trim(), conflicts: Array.isArray(conflicts) ? conflicts : null };
+}

package/src/setup.js

@@ -6,7 +6,7 @@ import {
   updateDeclaredAgent,
 } from "./agents.js";
 import { readConfiguration } from "./configuration.js";
-import { connectorLogin } from "./connector-login.js";
+import { customAuthorizationStatus } from "./custom/authorization.js";
 import { GUIDED_LOGIN_TIMEOUT_MS } from "./contract.js";
 import { launchBase, prepareLaunchBase } from "./directory.js";
 import {
@@ -45,24 +45,14 @@ function agentModule(context, kind) {
 }
 
 function connectorModule(context, instance) {
-  const gateway = connectorLogin(instance, context.dependencies);
   return {
     category: "connector",
     name: instance.id,
     login: { integration: instance.preset, instance: instance.id, service: instance.id },
     install: null,
     signedIn: () =>
-      gateway.status(instance, { directory: context.directory, signal: context.signal }),
-    guided:
-      gateway.guided === undefined
-        ? null
-        : ({ present, signal }) =>
-            gateway.guided(instance, {
-              directory: context.directory,
-              dependencies: context.dependencies,
-              present,
-              signal,
-            }),
+      customAuthorizationStatus(instance, { directory: context.directory, signal: context.signal }),
+    guided: null,
   };
 }
 
@@ -144,8 +134,12 @@ async function setUpModule(context, module, install = true) {
   return summary("ready");
 }
 
+export function signInModule(context, module) {
+  return setUpModule(context, module, false);
+}
+
 export function signInWantedAgent(context, kind) {
-  return setUpModule(context, agentModule(context, kind), false);
+  return signInModule(context, agentModule(context, kind));
 }
 
 export async function runSetup(context, request) {

package/src/skill-set/ask-matt/PHASE-BOUNDARIES.md

@@ -0,0 +1,55 @@
+# Phase boundaries
+
+A **phase** is a chunk of work inside a session: the grilling, the implementation, the QA. The definition is fuzzy on purpose: a phase ends when you think *"ok, we're done with that"*.
+
+The **phase boundary** is the gap between two phases, and it is the only place this decision belongs. Mid-phase there is no decision to make: continue, or split the work that's left into subagents. Compacting mid-phase makes the agent lose the thread.
+
+## The five options
+
+| Option       | What it does                                                    |
+| ------------ | --------------------------------------------------------------- |
+| **Continue** | Stay in the session. No context switch at all.                    |
+| **`/clear`** | Empty the context window and start from nothing.                  |
+| **`/handoff`** | Write a portable markdown file and seed a session anywhere with it. |
+| **Subagent** | Send the task to its own context window and get a report back.     |
+| **`/compact`** | Compress this context and seed a fresh session with the summary.  |
+
+## The tree
+
+Work top to bottom at the boundary. The first **yes** wins.
+
+**1. Can you continue in this session?** Two things make the answer yes: the next phase needs this phase as a **primary source**, or you have enough [smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone) left (~150k tokens) for the next phase to fit. Grilling → implementation is the standard yes: the implementation wants the reasoning verbatim, not a summary of it. Continue costs nothing and loses nothing, so rule it out before anything else.
+
+**2. Is the context irrelevant to what comes next?** Is everything in this session (the exploration, the decisions, the dead ends) disposable? If so, **`/clear`**. It is the cheapest move on the board: it takes no time and hands back the whole window. `/clear` also isn't terminal: the old session stays resumable.
+
+The cost of getting this wrong is one-way. Clear a *relevant* context and you lose the **why** behind what you built, and no amount of reading the diff back gets it returned.
+
+**3. Do you need to hand off?** `/handoff` is narrow. You need it only when you are:
+
+- swapping to a **new harness** (Claude → Codex),
+- moving to a **new directory** or repo,
+- sending the work to a **colleague**,
+- or forking a side task you found **mid-phase** without derailing what you're doing.
+
+That list is the whole clause. What `/handoff` buys is **portability**: a file that travels. If nothing is travelling, you don't need it.
+
+**4. Can the task be done AFK?** Is it scoped tightly enough to run with you away from the keyboard, no steering? Then send it to a **subagent** and leave this session untouched. Automated review is the standard case: the agent reads the diff and reports, and you aren't needed while it does.
+
+**5. Otherwise, `/compact`.** Relevant context, same harness, same directory, and you need to stay in the loop: this is where the tree lands, and it lands here often. Pass it an instruction (`/compact we're going to QA this area`) so the summary keeps what the next phase needs.
+
+`/compact` is the **default, not the first reach**. It sits at the bottom because the four questions above it are all cheaper or more precise. The failure mode when people start here is a fresh session that is confidently wrong about a decision the summary flattened.
+
+## Primary and secondary sources
+
+Every move except **Continue** turns a **primary source** into a **secondary source**: the session as it happened, replaced by a summary of it. The trade is always the same shape:
+
+| Source                            | Information | Noise | Room to move |
+| --------------------------------- | ----------- | ----- | ------------ |
+| Primary (Continue)                | Full        | Lots  | Little       |
+| Secondary (`/compact`, `/handoff`) | Lossy       | Less  | Lots         |
+
+This is why question 1 comes first. You only pay the lossiness when staying costs more than it saves.
+
+## These are judgement calls
+
+The questions are not objective: each has taste in it, and the same boundary can go two ways on two days. The value is in asking them **in order**, at the boundary rather than in the middle of the work.