@ikarmic/forge-core 5.0.0 → 5.1.1

package/dist/index.js

@@ -22,13 +22,13 @@ export { checkStale, staleKey } from './memory/stale.js';
 export { MAX_BODY_CHARS } from './tools/memory.js';
 export { buildLlmSummarizer, compactMessages, estimateMessageTokens, estimateTokens, getModelWindowTokens, shouldCompact, } from './context/compaction.js';
 export { defaultModelFor, detectProvider, envVarForProvider, fastDefaultFor, hasProviderKey, readModelConfigFromEnv, resolveApiKey, SUPPORTED_PROVIDERS, } from './config.js';
-export { loadMcpConfig, parseMcpConfig, connectAll, connectOne, closeAll, mcpResultToValue, jsonSchemaToZod, } from './mcp/index.js';
+export { loadMcpConfig, parseMcpConfig, connectAll, connectOne, closeAll, mcpResultToValue, mcpInstructionsBlock, createMcpResourceTools, jsonSchemaToZod, } from './mcp/index.js';
 export { createLanguageModel, formatModelId, pickAvailableProvider, resolveModelFromEnv, resolveModelFromEnvAsync } from './providers.js';
 export { defaultSessionDir, generateSessionId, saveSession, loadSession, deleteSession, listSessions, findLatestSession, formatSessionMarkdown, formatSessionJson, appendedSince, summarizeMessage, watchSession, searchSessions, sessionText, pruneSessions, pruneByRetention, } from './sessions/index.js';
 export { commandDirs, expandCustomCommand, formatCustomCommands, loadCustomCommands, parseCommandFile, } from './commands/custom-commands.js';
 export { BUILTIN_TOOLS, editFileTool, fetchUrlTool, findSymbolTool, listFilesTool, memoryReadTool, memoryForgetTool, memoryWriteTool, readFileTool, runCommandTool, searchFilesTool, subAgentTool, writeFileTool, checkPolicyViolation, globToRegex, mergeToolSandbox, normalizePathPattern, pathMatchesAny, redact, countRedactions, buildRules, ToolResultCache, buildCacheKey, cachedExecute, } from './tools/index.js';
 // Skills system
-export { buildSkillsBlock, composeSkillsPrompt, discoverSkills, fetchSkillsCatalog, installSkillFromCatalog, loadSkillsRegistry, loadSkillsRegistryAsync, parseSkill, parseSkillsDir, resolveSkillRoots, scoreSkill, searchSkills, selectSkills, skillsRegistryFromList, DEFAULT_SKILL_CATALOG_URL, GLOBAL_SKILLS_DIR, LOCAL_SKILLS_DIR, PROJECT_SKILLS_DIR, SKILL_CATALOG_VERSION, } from './skills/index.js';
+export { buildSkillsBlock, builtinSkills, composeSkillsPrompt, discoverSkills, fetchSkillsCatalog, installSkillFromCatalog, loadSkillsRegistry, loadSkillsRegistryAsync, parseSkill, parseSkillsDir, resolveSkillRoots, scoreSkill, searchSkills, selectSkills, skillsRegistryFromList, DEFAULT_SKILL_CATALOG_URL, GLOBAL_SKILLS_DIR, LOCAL_SKILLS_DIR, PROJECT_SKILLS_DIR, SKILL_CATALOG_VERSION, } from './skills/index.js';
 export { cosine, embedderFromEnv, hashingEmbedder, openAiCompatibleEmbedder, } from './semantic/embedder.js';
 export { ensureSemanticFresh, searchSemantic } from './semantic/semantic-index.js';
 export { createCodebaseSearchTool } from './tools/codebase-search.js';
@@ -40,7 +40,10 @@ export { applyCacheHints, supportsCacheHints } from './agent/cache-hints.js';
 // Organization policy, audit log, proxy
 export { PolicyError, applyPolicy, assertProviderAllowed, filterMcpServers, getOrgPolicy, loadOrgPolicy, managedPolicyPath, parsePolicy, resetOrgPolicyCache, } from './policy/policy.js';
 export { createFileAuditSink, defaultAuditFile, scrubArgs } from './policy/audit.js';
-export { hasProxy, installProxy, proxyFromEnv } from './policy/proxy.js';
+export { hasProxy, installProxy, installedFetch, proxyFromEnv } from './policy/proxy.js';
+export { readCaCertificates } from './policy/ca-certs.js';
+export { BackgroundAgents, MAX_RUNNING_BACKGROUND, backgroundResultsBlock } from './agent/background.js';
+export { applyClaudeImport, planClaudeImport } from './import/claude-code.js';
 // Hooks system
 export { AGENT_HOOK_TOOLS, createAgentHookRunner, DEFAULT_AGENT_HOOK_TIMEOUT_MS, DEFAULT_HOOK_TIMEOUT_MS, HooksBus, eventFilePath, eventToEnv, eventToolName, globalSettingsPath, hooksBusFromConfig, loadHooksConfig, matcherMatches, projectSettingsPath, runHook, validateHooksConfig, HOOK_EVENT_NAMES, shouldIgnoreWatchPath, FileChangeCoalescer, watchFilesystem, } from './hooks/index.js';
 // MCP marketplace
@@ -50,7 +53,7 @@ export { MARKETPLACE_CATALOG_VERSION } from './mcp/marketplace-types.js';
 // Checkpoint system
 export { CheckpointStore } from './checkpoints/index.js';
 // Specs system (spec-driven planning mode)
-export { SpecStore, isSafeSpecId, runKey, slugifyTaskForSpecId, SPEC_READONLY_TOOLS, splitSpecSections, convertToCheckboxes, parseTasks, setTaskDone, changedSince, changeSize, keepDoneTasks, referencedPaths, specDrift, syncSpecTask } from './specs/index.js';
+export { SpecStore, isSafeSpecId, runKey, slugifyTaskForSpecId, SPEC_READONLY_TOOLS, splitRequirementsDesign, splitSpecSections, splitTasksSection, convertToCheckboxes, parseTasks, setTaskDone, changedSince, changeSize, keepDoneTasks, referencedPaths, specDrift, syncSpecTask } from './specs/index.js';
 // Orchestrator system
 export { BUILTIN_SPECIALISTS, defaultConfigPath, effectiveToolsFor, BOARD_TOOL_NAMES, createBoardTools, DEFAULT_BOARD_CAP, getRegisteredSpecialist, getSpecialist, MessageBoard, listSpecialists, loadSpecialistsFromConfig, parseRouterOutput, registerSpecialist, resolveEffectiveModel, ROUTER_SYSTEM_PROMPT, runOrchestrator, runRouter, saveSpecialistsToConfig, unregisterSpecialist, validateSpecialistConfig, _resetSpecialistsForTests, _customSpecialistCount, } from './orchestrator/index.js';
 // Diff utilities (line-level unified diff)
@@ -70,11 +73,22 @@ export { defaultRetryPrompt, formatZodError, isStructuredOutputError, loadSchema
 export { branchChangedFiles, branchDiff, commitAllInWorktree, compareWorktreeContexts, deleteBranch, mergeBranch, snapshotWorktreeContext, WorktreeError, WorktreeManager, } from './worktree/index.js';
 // Steering files (SP3a)
 export { formatSteeringLine, isSafeSteeringName, loadSteering, overrideFilePath, parseSteering, pathMatchesGlob, readOverride, selectAtStart, selectOnToolTouch, setSteeringDisabled, stripSteering, wrapSteering, } from './steering/index.js';
+export { CONFIG_KEY_COVERAGE, FORGE_CONFIG_SCHEMA } from './config-schema.js';
+export { FILE_WRITE_TOOL_NAMES, filesTouchedBy } from './tools/write-tools.js';
+export { shellEnv } from './tools/shell-env.js';
+export { previewPatch } from './tools/apply-patch.js';
+export { applyPatchTool, parsePatch, patchedPaths } from './tools/apply-patch.js';
+export { buildEmbedder } from './semantic/embedder.js';
+export { parseExtensions } from './semantic/semantic-index.js';
+export { cleanDigest, generateSessionDigest, shouldDigest } from './memory/session-digest.js';
+export { buildExtraInstructionsBlock } from './steering/extra-instructions.js';
 export { buildProjectInstructionsBlock, PROJECT_INSTRUCTION_FILES } from './steering/project-instructions.js';
 // AI comments (Aider parity E).
 export { aiCommentTask, findAiComments, triggerOf } from './ai-comments/index.js';
 // Git workflow: dirty-work commit before a run, drafted commit after, /undo.
 export * from './git/index.js';
+// Guided journey: the two-tier trigger, the LLM-free survey, stages and gates.
+export * from './journey/index.js';
 // Context: ranked repo map in the system prompt; auto-lint of edited files.
 export * from './repomap/index.js';
 export * from './lint/index.js';
@@ -85,8 +99,17 @@ export * from './lsp/index.js';
 export * from './plugins/index.js';
 // Tools that are approved without a prompt by default (read-only).
 export { READ_ONLY_TOOLS, resolveAutoApprove } from './tools/read-only.js';
+export { compilePermissionRules, evaluatePermission, isSensitiveFile, permissionFor, splitShellCommands, touchesOutsideCwd } from './tools/permission-rules.js';
 // Project check detection (typecheck / lint / test commands) for verify-by-default.
 export { autoRunCommands, autoRunFingerprint, detectProjectChecks, formatProjectCommandsBlock, projectScriptsFingerprint } from './verify/index.js';
 export { isAlwaysAllowable, isListedCommand, needsScriptFingerprint, normalizeCommand } from './tools/command-allow.js';
 // Git-style ignore rules (.gitignore, .forgeignore) used by the file tools and indexes.
 export { IgnoreRules, IGNORE_FILE_NAMES, findGitRoot } from './tools/ignore-rules.js';
+export { MAX_OBJECTIVE_CHARS, applyTurnOutcome, createGoalReportTool, goalPrompt, pauseGoal, resumeGoal, startGoal } from './agent/goal.js';
+export { loadMergedForgeConfig, projectConfigPath } from './config-merge.js';
+export { PROVIDER_PRESETS, apiModelId, customProviderProblems, filterModels, knownProviderIds, modelFilterFor, registerCustomProviders, registerModelFilters, registeredCustomProviders, resolveProviderEndpoint, } from './custom-providers.js';
+export { withTimeouts } from './timed-fetch.js';
+export { createEndpointModel } from './providers.js';
+export { agentToSpecialist, loadAgentFiles, parseAgentFile, registerAgentDefs, registeredAgent, registeredAgents } from './agents/agent-files.js';
+export { applyResolved } from './model-alias.js';
+export { getModelOverride, overridesFromProviders, registerModelOverrides } from './model-overrides.js';

package/dist/journey/answers-block.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The interview answers, rendered for the system prompt.
+ *
+ * Why the system prompt and not a turn: `compactMessages` keeps the system
+ * message and the most recent turns verbatim and summarises everything in
+ * between, so an answer sitting in a middle turn is forgotten on a long
+ * journey — the person says "Postgres, no invoicing" and forty turns later the
+ * model scaffolds MySQL with invoicing. In the system message it cannot be
+ * forgotten.
+ *
+ * Why the interview must finish before the first agent run:
+ * `buildInitialMessages` assembles the blocks only when no history is passed
+ * (`agent.ts:231`), so this block enters the prompt once, on a session's first
+ * turn, and rides inside `history[0]` from then on.
+ */
+import type { Answer } from './types.js';
+export declare function renderAnswersBlock(answers: readonly Answer[]): string;

package/dist/journey/answers-block.js

@@ -0,0 +1,15 @@
+export function renderAnswersBlock(answers) {
+    // A dismissed question comes back with an empty answer. Rendering it under
+    // "these are decisions" would present an open question as settled, which
+    // invites the model to invent the very thing the person declined to choose.
+    const answered = answers.filter((a) => a.answer.trim() !== '');
+    if (answered.length === 0)
+        return '';
+    const lines = answered.map((a) => `- ${a.question}: ${a.answer.replace(/<\/journey-answers>/gi, '')}`);
+    return [
+        '<journey-answers>',
+        'The person answered these before work started. They are decisions, not suggestions:',
+        ...lines,
+        '</journey-answers>',
+    ].join('\n');
+}

package/dist/journey/index.d.ts

@@ -0,0 +1,9 @@
+/** The guided journey: trigger, survey, interview questions, offer, stages and state. */
+export { renderAnswersBlock } from './answers-block.js';
+export { abandon, advance, startJourney, stepDown } from './journey.js';
+export { decideOffer } from './offer.js';
+export { answeredBySurvey, gapQuestions } from './questions.js';
+export { NO_TOOLS_SENTINEL, stageById, STAGES } from './stages.js';
+export { MAX_SURVEY_FILES, surveyWorkspace } from './survey.js';
+export { shouldSurvey } from './trigger.js';
+export type { Answer, InterviewQuestion, JourneyOffer, JourneyState, Stage, StageId, SurveyFacts, TriggerVerdict, } from './types.js';

package/dist/journey/index.js

@@ -0,0 +1,8 @@
+/** The guided journey: trigger, survey, interview questions, offer, stages and state. */
+export { renderAnswersBlock } from './answers-block.js';
+export { abandon, advance, startJourney, stepDown } from './journey.js';
+export { decideOffer } from './offer.js';
+export { answeredBySurvey, gapQuestions } from './questions.js';
+export { NO_TOOLS_SENTINEL, stageById, STAGES } from './stages.js';
+export { MAX_SURVEY_FILES, surveyWorkspace } from './survey.js';
+export { shouldSurvey } from './trigger.js';

package/dist/journey/journey.d.ts

@@ -0,0 +1,13 @@
+import type { Answer, JourneyState } from './types.js';
+export declare function startJourney(answers: readonly Answer[]): JourneyState;
+/**
+ * The next stage, or `'done'` after the last one. An unrecognised stage — a
+ * session saved by a different version of Forge — ends the journey rather than
+ * throwing, so an unknown id cannot trap the person in a stage they cannot
+ * leave (spec anti-goal 5).
+ */
+export declare function advance(state: JourneyState): JourneyState;
+/** The previous stage. Already at the first stage, it stays there. */
+export declare function stepDown(state: JourneyState): JourneyState;
+/** Leave the journey. Always available, from any stage. */
+export declare function abandon(state: JourneyState): JourneyState;

package/dist/journey/journey.js

@@ -0,0 +1,40 @@
+/**
+ * The journey state machine.
+ *
+ * Every transition is an explicit call. Nothing advances because a stage
+ * finished or because the model said it was done — crossing a gate is a
+ * person's click, and a machine that can advance itself is a gate that can be
+ * crossed without one.
+ *
+ * Transitions return a new state and never mutate their input, so a surface can
+ * hold the previous state while a gate is open.
+ */
+import { STAGES } from './stages.js';
+const ORDER = STAGES.map((s) => s.id);
+export function startJourney(answers) {
+    return { current: ORDER[0], answers: [...answers], taskCursor: 0 };
+}
+/**
+ * The next stage, or `'done'` after the last one. An unrecognised stage — a
+ * session saved by a different version of Forge — ends the journey rather than
+ * throwing, so an unknown id cannot trap the person in a stage they cannot
+ * leave (spec anti-goal 5).
+ */
+export function advance(state) {
+    const at = ORDER.indexOf(state.current);
+    if (at === -1)
+        return { ...state, current: 'done' };
+    const next = ORDER[at + 1];
+    return { ...state, current: next ?? 'done' };
+}
+/** The previous stage. Already at the first stage, it stays there. */
+export function stepDown(state) {
+    const at = ORDER.indexOf(state.current);
+    if (at === -1)
+        return { ...state, current: 'done' };
+    return { ...state, current: ORDER[Math.max(0, at - 1)] };
+}
+/** Leave the journey. Always available, from any stage. */
+export function abandon(state) {
+    return { ...state, current: 'done' };
+}

package/dist/journey/offer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tier 2: the real trigger.
+ *
+ * Tier 1 only decided whether looking was worth it. This decides whether to
+ * put a card in front of the person, and it does so from what the Survey
+ * actually read. That ordering is the whole defence against spec anti-goal 1:
+ * a card that arrives with evidence ("touches auth and billing") reads as
+ * earned, where a card triggered by the word "build" reads as nagging.
+ *
+ * Every string in `evidence` is a count or a name the Survey produced. Nothing
+ * here hedges or infers, because the card is the one place a wrong guess is
+ * visible to the person.
+ */
+import type { JourneyOffer, SurveyFacts, TriggerVerdict } from './types.js';
+/**
+ * Decide whether to put the card in front of the person.
+ *
+ * The key case, and the one this got wrong first time: **nothing matching the
+ * request is the strongest evidence for a journey, not against it.** A request
+ * that names a subsystem the repo does not have ("add a reporting module", or
+ * anything at all in an empty folder) is new work, and new work is what the
+ * journey is for. Only a request that lands inside a *single* existing area is
+ * the repo telling us the change is scoped.
+ */
+export declare function decideOffer(facts: SurveyFacts, verdict: TriggerVerdict): JourneyOffer;

package/dist/journey/offer.js

@@ -0,0 +1,48 @@
+/** Below this many distinct areas, an existing codebase is telling us the change is scoped. */
+const MIN_AREAS = 2;
+/** Everything a request matched sits at the repo root, so there are no areas to count. */
+const ROOT_AREA = '(root)';
+/** The area of a repo-relative path: the coarsest grouping that means "part of the system". */
+function areaOf(rel) {
+    const parts = rel.split(/[\\/]/).filter((p) => p.length > 0 && p !== '.');
+    // `src/auth/session.ts` is the auth area, not the src area.
+    if (parts.length > 2 && (parts[0] === 'src' || parts[0] === 'packages' || parts[0] === 'lib'))
+        return parts[1];
+    // A file directly in the root is not an area; calling it one would both over-offer
+    // and show the person a filename labelled as a subsystem.
+    if (parts.length < 2)
+        return ROOT_AREA;
+    return parts[0];
+}
+/**
+ * Decide whether to put the card in front of the person.
+ *
+ * The key case, and the one this got wrong first time: **nothing matching the
+ * request is the strongest evidence for a journey, not against it.** A request
+ * that names a subsystem the repo does not have ("add a reporting module", or
+ * anything at all in an empty folder) is new work, and new work is what the
+ * journey is for. Only a request that lands inside a *single* existing area is
+ * the repo telling us the change is scoped.
+ */
+export function decideOffer(facts, verdict) {
+    if (!verdict.survey)
+        return { offer: false, evidence: [] };
+    const areas = [...new Set(facts.relatedSymbols.map(areaOf))];
+    if (facts.relatedSymbols.length === 0) {
+        const where = facts.sourceFileCount === 0
+            ? 'no source files here yet'
+            : `nothing among ${facts.sourceFileCount} surveyed files is named for this request`;
+        return { offer: true, evidence: [`${where}: this is new work`, ...verdict.reasons] };
+    }
+    if (areas.length < MIN_AREAS)
+        return { offer: false, evidence: [] };
+    const evidence = [
+        `touches ${areas.length} areas: ${areas.join(', ')}`,
+        `${facts.relatedSymbols.length} related files of ${facts.sourceFileCount} surveyed`,
+    ];
+    if (facts.checks.length > 0)
+        evidence.push(`checks available: ${facts.checks.map((c) => c.kind).join(', ')}`);
+    if (facts.conventionFiles.length > 0)
+        evidence.push(`conventions in ${facts.conventionFiles.join(', ')}`);
+    return { offer: true, evidence };
+}

package/dist/journey/questions.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The interview question catalogue, and the gap analysis that decides which of
+ * them survive the Survey.
+ *
+ * This file is where spec decision 13 lives: nothing branches on "greenfield"
+ * or "brownfield". Each question carries a precondition against the facts, and
+ * the number of questions a request earns is a *consequence* of what the
+ * workspace could answer, not a tier anyone has to tune. An empty folder is not
+ * a special case — it is a survey that found nothing, so every precondition
+ * comes back unanswered and all four are asked.
+ */
+import type { InterviewQuestion, SurveyFacts } from './types.js';
+/**
+ * The questions this request still needs, capped at `max` (spec decision 8's
+ * budget, which `ask_user` also enforces mechanically so prompt text cannot
+ * talk past it).
+ */
+export declare function gapQuestions(facts: SurveyFacts, max?: number): InterviewQuestion[];
+/** What the Survey already answered, for the record shown beside the interview. */
+export declare function answeredBySurvey(facts: SurveyFacts): Array<{
+    id: string;
+    fact: string;
+}>;

package/dist/journey/questions.js

@@ -0,0 +1,49 @@
+/** Paths that mean this codebase already has an auth story. */
+const AUTH_PATH = /auth|session|login|oauth|permission/i;
+/**
+ * In priority order: the first `max` unanswered questions are the ones asked.
+ * `deploy` is last because it is the one a repo can least often answer, so it
+ * survives into mature-repo journeys where the others do not.
+ */
+const CATALOGUE = [
+    {
+        id: 'stack',
+        question: 'Which stack should this use?',
+        options: ['Next.js + Postgres', 'Django + Postgres', 'Rails + Postgres', 'Express + SQLite'],
+        answeredBy: (f) => f.manifest ? `${f.manifest.path}${f.manifest.packageManager ? ` (${f.manifest.packageManager})` : ''}` : undefined,
+    },
+    {
+        id: 'modules',
+        question: 'Which parts should it cover?',
+        options: ['Tasks', 'Boards', 'Time tracking', 'Invoicing', 'Reporting', 'Notifications'],
+        multiSelect: true,
+        answeredBy: (f) => (f.sourceFileCount > 0 ? `${f.sourceFileCount} existing source files` : undefined),
+    },
+    {
+        id: 'authScale',
+        question: 'Who signs in, and roughly how many of them?',
+        options: ['One team, internal', 'Many organisations, each isolated', 'Public sign-up'],
+        answeredBy: (f) => f.relatedSymbols.find((p) => AUTH_PATH.test(p)),
+    },
+    {
+        id: 'deploy',
+        question: 'Where will this run?',
+        options: ['Vercel or similar', 'A container somewhere', 'A VM we manage', 'Not decided yet'],
+        answeredBy: () => undefined,
+    },
+];
+/**
+ * The questions this request still needs, capped at `max` (spec decision 8's
+ * budget, which `ask_user` also enforces mechanically so prompt text cannot
+ * talk past it).
+ */
+export function gapQuestions(facts, max = 4) {
+    return CATALOGUE.filter((q) => q.answeredBy(facts) === undefined).slice(0, max);
+}
+/** What the Survey already answered, for the record shown beside the interview. */
+export function answeredBySurvey(facts) {
+    return CATALOGUE.flatMap((q) => {
+        const fact = q.answeredBy(facts);
+        return fact === undefined ? [] : [{ id: q.id, fact }];
+    });
+}

package/dist/journey/stages.d.ts

@@ -0,0 +1,13 @@
+import type { Stage, StageId } from './types.js';
+/**
+ * "This stage runs no tools."
+ *
+ * It cannot be `[]`: `applySandbox` treats an empty `allowTools` as *no
+ * whitelist at all*, so an empty list would hand a host-driven stage every
+ * tool, writes included. `vscode/src/chat/modes.ts` already learned this and
+ * carries its own copy of the same trick; this one lives in core so a surface
+ * wiring stages into a sandbox gets the safe value without rediscovering it.
+ */
+export declare const NO_TOOLS_SENTINEL = "__forge_no_tools__";
+export declare const STAGES: readonly Stage[];
+export declare function stageById(id: StageId): Stage | undefined;

package/dist/journey/stages.js

@@ -0,0 +1,107 @@
+/**
+ * The six stages of a guided journey.
+ *
+ * A stage is a prompt suffix plus a tool set, which is the point: gating reuses
+ * the sandbox the agent already applies, so "implementation cannot start yet"
+ * is the write tools being absent from the list rather than an instruction the
+ * model may decline. That is the one enforcement mechanism in this design that
+ * a model cannot talk past.
+ *
+ * `allowTools` takes its write-tool names from `FILE_WRITE_TOOL_NAMES` rather
+ * than retyping them: a tool added to that list and missed here would be a
+ * write the Build gate does not cover (RB-13).
+ */
+import { FILE_WRITE_TOOL_NAMES } from '../tools/write-tools.js';
+const READ_TOOLS = ['read_file', 'list_files', 'search_files', 'find_symbol', 'list_symbols', 'find_references'];
+/**
+ * "This stage runs no tools."
+ *
+ * It cannot be `[]`: `applySandbox` treats an empty `allowTools` as *no
+ * whitelist at all*, so an empty list would hand a host-driven stage every
+ * tool, writes included. `vscode/src/chat/modes.ts` already learned this and
+ * carries its own copy of the same trick; this one lives in core so a surface
+ * wiring stages into a sandbox gets the safe value without rediscovering it.
+ */
+export const NO_TOOLS_SENTINEL = '__forge_no_tools__';
+export const STAGES = [
+    {
+        id: 'survey',
+        usesModel: false,
+        promptSuffix: '',
+        allowTools: [NO_TOOLS_SENTINEL],
+        artefact: 'survey facts',
+        gateOptions: [],
+    },
+    {
+        id: 'interview',
+        usesModel: false,
+        promptSuffix: '',
+        allowTools: [NO_TOOLS_SENTINEL],
+        artefact: 'interview answers',
+        gateOptions: [],
+    },
+    {
+        id: 'plan',
+        usesModel: true,
+        promptSuffix: [
+            '',
+            'PLAN STAGE — state the plan and stop.',
+            '- Produce a short numbered plan of the work, grounded in what you can read.',
+            '- You cannot ask questions at this stage: the interview is over. Where something',
+            '  is genuinely undecided, state it as an assumption in the plan.',
+            '- Do not write or change any file.',
+        ].join('\n'),
+        allowTools: [...READ_TOOLS],
+        artefact: 'a plan, in chat',
+        gateOptions: ['Approve the plan', 'Revise it', 'Skip to the spec'],
+    },
+    {
+        id: 'spec',
+        usesModel: true,
+        promptSuffix: [
+            '',
+            'SPEC STAGE — produce exactly two sections and stop.',
+            '- `## requirements.md` then `## design.md`, each starting with its own heading line.',
+            '- Inside a section use `###` or deeper for headings: any `##` line ends the section.',
+            '- Requirements: user stories with EARS-syntax acceptance criteria, e.g. "WHEN <trigger> THE SYSTEM SHALL <response>".',
+            '  Number each requirement (1, 2, 3, ...) and its criteria (1.1, 1.2, ...) so the implementation plan can cite them.',
+            '- Design: ground it in what you read: data flow, schemas, interfaces, API endpoints, and the existing patterns to follow.',
+            '- The implementation plan is a separate stage: do not write tasks here.',
+            '- You cannot write files at this stage. Reply with the sections as text, with no preamble and no closing summary.',
+        ].join('\n'),
+        allowTools: [...READ_TOOLS],
+        artefact: 'requirements.md, design.md',
+        gateOptions: ['Approve the spec', 'Revise it'],
+    },
+    {
+        id: 'implPlan',
+        usesModel: true,
+        promptSuffix: [
+            '',
+            'IMPLEMENTATION PLAN STAGE — produce `## tasks.md` and stop.',
+            '- A markdown checklist: "- [ ] 1. Title", subtasks indented as "  - [ ] 1.1 Title".',
+            '- Under each task add a line like "_Requirements: 2.1, 3.2_", citing the requirement numbers you were given.',
+            '- One checkbox per line, never two on a line.',
+            '- You cannot write files at this stage. Reply with the document as text, with no preamble and no closing summary.',
+        ].join('\n'),
+        allowTools: [...READ_TOOLS],
+        artefact: 'tasks.md',
+        gateOptions: ['Approve the tasks', 'Revise them'],
+    },
+    {
+        id: 'build',
+        usesModel: true,
+        promptSuffix: [
+            '',
+            'BUILD STAGE — do the task you were given and stop at it.',
+            '- Work only on the current task; the next one is gated on the person.',
+            '- Run the project\'s own check when the change could break something.',
+        ].join('\n'),
+        allowTools: [...READ_TOOLS, ...FILE_WRITE_TOOL_NAMES, 'run_command'],
+        artefact: 'ticked tasks',
+        gateOptions: ['Continue to the next task', 'Retry this one', 'Skip it', 'Stop', 'Run the rest without asking'],
+    },
+];
+export function stageById(id) {
+    return STAGES.find((s) => s.id === id);
+}

package/dist/journey/survey.d.ts

@@ -0,0 +1,10 @@
+import type { SurveyFacts } from './types.js';
+/** Ceiling on the tree walk, so a monorepo costs the same as a small repo. */
+export declare const MAX_SURVEY_FILES = 400;
+/** Second ceiling: a tree of mostly empty or non-source directories is bounded too. */
+export declare const MAX_SURVEY_DIRS = 2000;
+/**
+ * Read what this workspace already says about itself. Never throws: a fact that
+ * cannot be read is absent.
+ */
+export declare function surveyWorkspace(cwd: string, request: string): Promise<SurveyFacts>;