@dv.nghiem/flowdeck 0.3.9 → 0.4.1

package/dist/lib/completion-validator.d.ts

@@ -0,0 +1,51 @@
+import type { PlanningState } from "../tools/planning-state-lib";
+export interface CompletionReadiness {
+    valid: boolean;
+    /** Why it's ready (when valid) */
+    summary?: string;
+    /** Blocking reasons (when not valid) */
+    blockers: string[];
+}
+/**
+ * Validate whether a feature/workflow is in a finishable state.
+ *
+ * Rules:
+ * - STATE.md must exist (caller is responsible for passing state)
+ * - status must not be "planned" (nothing has started)
+ * - plan_confirmed must be true (plan must have been confirmed)
+ * - no active blockers
+ * - if design-first was required, it must be satisfied
+ * - status must be "verified" or "in_progress" (not already "complete")
+ */
+export declare function validateCompletionReadiness(state: PlanningState): CompletionReadiness;
+export interface CompletionMetadata {
+    /** Feature/phase number */
+    phase: number;
+    /** ISO timestamp of completion */
+    completedAt: string;
+    /** Who/what triggered completion */
+    completedBy: string;
+    /** Final status before done was called */
+    priorStatus: string;
+    /** Steps that were complete at time of closing */
+    stepsComplete: number[];
+    /** Whether /fd-verify had been run */
+    wasVerified: boolean;
+    /** Changed files summary from git diff */
+    changedFiles: string[];
+    /** Whether verify was explicitly skipped */
+    verifySkipped: boolean;
+    /** Whether codebase mapping was refreshed */
+    mappingRefreshed: boolean;
+    /** Freshness status of mapping after done */
+    mappingFreshnessStatus: "fresh" | "stale" | "skipped";
+}
+/**
+ * Build a human-readable DONE.md summary artifact for the current phase.
+ */
+export declare function buildCompletionSummary(meta: CompletionMetadata): string;
+/**
+ * Check whether the prior status indicates /fd-verify was run.
+ */
+export declare function wasVerified(status: string): boolean;
+//# sourceMappingURL=completion-validator.d.ts.map

package/dist/lib/completion-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-validator.d.ts","sourceRoot":"","sources":["../../src/lib/completion-validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAEhE,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAA;IACd,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,aAAa,GAAG,mBAAmB,CAoDrF;AAED,MAAM,WAAW,kBAAkB;IACjC,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAA;IACnB,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAA;IACnB,kDAAkD;IAClD,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,sCAAsC;IACtC,WAAW,EAAE,OAAO,CAAA;IACpB,0CAA0C;IAC1C,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,4CAA4C;IAC5C,aAAa,EAAE,OAAO,CAAA;IACtB,6CAA6C;IAC7C,gBAAgB,EAAE,OAAO,CAAA;IACzB,6CAA6C;IAC7C,sBAAsB,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAA;CACtD;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAuCvE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD"}

package/dist/lib/recommended-question.d.ts

@@ -0,0 +1,24 @@
+export interface RecommendedQuestion {
+    question: string;
+    recommendation: string;
+    rationale: string;
+    alternatives?: string[];
+    defaultIfNoResponse: string;
+}
+/**
+ * Render a RecommendedQuestion to a human-readable string format.
+ */
+export declare function formatRecommendedQuestion(q: RecommendedQuestion): string;
+/**
+ * Type guard — returns true only if the value is a valid RecommendedQuestion
+ * with all required fields present and non-empty.
+ *
+ * Also returns false for trivially bare question patterns.
+ */
+export declare function validateRecommendedQuestion(value: unknown): value is RecommendedQuestion;
+/**
+ * Parse a formatted RecommendedQuestion string back into an object.
+ * Returns null if the text does not contain the required fields.
+ */
+export declare function parseQuestionBlocks(text: string): RecommendedQuestion | null;
+//# sourceMappingURL=recommended-question.d.ts.map

package/dist/lib/recommended-question.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommended-question.d.ts","sourceRoot":"","sources":["../../src/lib/recommended-question.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,mBAAmB,EAAE,MAAM,CAAA;CAC5B;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAOxE;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAmCxF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAsC5E"}

package/dist/lib/research-gate.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Research Gate — shared research-first enforcement for FlowDeck commands.
+ *
+ * Enforces that major workflow stages (discuss, plan, execute, fix-bug)
+ * perform targeted research BEFORE asking human questions or producing plans.
+ *
+ * Research is scoped to the stage:
+ * - discuss: gather facts and open questions from repo evidence
+ * - plan: gather implementation constraints and design options
+ * - execute: verify actual code paths and impacted files
+ * - fix-bug: inspect bug path, reproduction, and known remedies
+ *
+ * Research results are persisted in shared state so later stages can reuse them.
+ * Freshness metadata determines whether existing research is sufficient or
+ * new research is needed.
+ */
+import { type PlanningState } from "../tools/planning-state-lib";
+export type ResearchScope = "discuss" | "plan" | "execute" | "fix-bug";
+/** Evidence collected during a research pass. */
+export interface ResearchEvidence {
+    /** Which scope this evidence is for. */
+    scope: ResearchScope;
+    /** When this evidence was collected. */
+    collectedAt: string;
+    /** Files that were read/inspected. */
+    filesExplored: string[];
+    /** Key findings from the research. */
+    findings: string[];
+    /** Whether MCP tools were used. */
+    mcpToolsUsed: string[];
+    /** Whether the research gate was satisfied (enough evidence gathered). */
+    gateSatisfied: boolean;
+    /** Whether additional exploration was skipped (fresh evidence existed). */
+    skippedExploration: boolean;
+    /** Summary version when this research was conducted. */
+    summaryVersion: number;
+}
+/** Diagnostics logged during research. */
+export interface ResearchDiagnostics {
+    /** Research scope. */
+    scope: ResearchScope;
+    /** Timestamp of research. */
+    timestamp: string;
+    /** Sources consulted. */
+    sourcesUsed: string[];
+    /** MCP tools invoked. */
+    mcpToolsInvoked: string[];
+    /** Evidence collected. */
+    evidenceCollected: string[];
+    /** Whether gate was satisfied. */
+    gateSatisfied: boolean;
+    /** Whether additional exploration was skipped. */
+    skippedExploration: boolean;
+}
+/**
+ * Check whether existing research in shared state is still fresh enough to reuse.
+ * Research is considered fresh if:
+ * 1. The summaryVersion matches the current state's summaryVersion
+ * 2. The state itself is fresh (within 5 minutes)
+ * 3. The research scope matches
+ */
+export declare function isResearchFresh(state: PlanningState, scope: ResearchScope): boolean;
+/**
+ * Persist research evidence to STATE.md so later stages can reuse it.
+ */
+export declare function persistResearchEvidence(dir: string, scope: ResearchScope, evidence: ResearchEvidence): void;
+/**
+ * Load persisted research evidence for a given scope.
+ */
+export declare function loadResearchEvidence(dir: string, scope: ResearchScope): ResearchEvidence | null;
+/**
+ * Build diagnostics log entry for a research pass.
+ */
+export declare function buildResearchDiagnostics(evidence: ResearchEvidence): ResearchDiagnostics;
+/**
+ * Log research diagnostics to console (for agent visibility).
+ */
+export declare function logResearchDiagnostics(diags: ResearchDiagnostics): void;
+/**
+ * Perform a research pass for a given scope, checking freshness first.
+ *
+ * Returns ResearchEvidence with gateSatisfied=true if enough evidence was gathered.
+ * If existing research is fresh, returns that and sets skippedExploration=true.
+ */
+export declare function runResearchGate(dir: string, scope: ResearchScope, options?: {
+    forceRefresh?: boolean;
+    customEvidence?: Partial<ResearchEvidence>;
+}): Promise<ResearchEvidence>;
+/**
+ * Check if a stage should proceed or block based on research gate.
+ * Returns an error message if the gate is not satisfied and the stage should block.
+ */
+export declare function researchGateStatus(evidence: ResearchEvidence): {
+    satisfied: boolean;
+    blocker?: string;
+};
+//# sourceMappingURL=research-gate.d.ts.map

package/dist/lib/research-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-gate.d.ts","sourceRoot":"","sources":["../../src/lib/research-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAA0F,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAGxJ,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAA;AAEtE,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,KAAK,EAAE,aAAa,CAAA;IACpB,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAA;IACnB,sCAAsC;IACtC,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,mCAAmC;IACnC,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,0EAA0E;IAC1E,aAAa,EAAE,OAAO,CAAA;IACtB,2EAA2E;IAC3E,kBAAkB,EAAE,OAAO,CAAA;IAC3B,wDAAwD;IACxD,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC,sBAAsB;IACtB,KAAK,EAAE,aAAa,CAAA;IACpB,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAA;IACjB,yBAAyB;IACzB,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,yBAAyB;IACzB,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,0BAA0B;IAC1B,iBAAiB,EAAE,MAAM,EAAE,CAAA;IAC3B,kCAAkC;IAClC,aAAa,EAAE,OAAO,CAAA;IACtB,kDAAkD;IAClD,kBAAkB,EAAE,OAAO,CAAA;CAC5B;AAID;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAInF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CA0B3G;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,gBAAgB,GAAG,IAAI,CAa/F;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,mBAAmB,CAUxF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAUvE;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,aAAa,EACpB,OAAO,CAAC,EAAE;IACR,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;CAC3C,GACA,OAAO,CAAC,gBAAgB,CAAC,CAyH3B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,gBAAgB,GAAG;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAQvG"}

package/dist/lib/research-gate.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=research-gate.test.d.ts.map

package/dist/lib/research-gate.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-gate.test.d.ts","sourceRoot":"","sources":["../../src/lib/research-gate.test.ts"],"names":[],"mappings":""}

package/dist/mcp/index.d.ts

@@ -7,7 +7,10 @@
  *   - grep_app    https://mcp.grep.app           (code search)
  *   - github      https://api.githubcopilot.com/mcp/  (GitHub code search)
  *
- * Disable individual MCPs with: FLOWDECK_DISABLE_MCP=context7,websearch,grep_app,github
+ * Local stdio MCPs (when installed):
+ *   - codegraph   codegraph serve --mcp          (code knowledge graph — symbol search, call graphs, impact analysis)
+ *
+ * Disable individual MCPs with: FLOWDECK_DISABLE_MCP=context7,websearch,grep_app,github,codegraph
  */
 type RemoteMcp = {
     type: "remote";
@@ -16,6 +19,13 @@ type RemoteMcp = {
     headers?: Record<string, string>;
     oauth?: false;
 };
-export declare function createFlowDeckMcps(): Record<string, RemoteMcp>;
+type LocalMcp = {
+    type: "local";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    enabled: boolean;
+};
+export declare function createFlowDeckMcps(): Record<string, RemoteMcp | LocalMcp>;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,KAAK,SAAS,GAAG;IACf,IAAI,EAAE,QAAQ,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,KAAK,CAAC,EAAE,KAAK,CAAA;CACd,CAAA;AAOD,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAmD9D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,KAAK,SAAS,GAAG;IACf,IAAI,EAAE,QAAQ,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,KAAK,CAAC,EAAE,KAAK,CAAA;CACd,CAAA;AAED,KAAK,QAAQ,GAAG;IACd,IAAI,EAAE,OAAO,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAOD,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC,CAgEzE"}

package/dist/services/codegraph.d.ts

@@ -0,0 +1,36 @@
+export interface CodegraphMeta {
+    installed: boolean;
+    indexed: boolean;
+    lastIndexedAt: string;
+    lastIndexedRevision: string;
+    lastIndexedBy: string;
+    freshnessStatus: "fresh" | "stale" | "unknown";
+    installLog: string;
+    indexLog: string;
+}
+export declare function isCodegraphInstalled(): boolean;
+export declare function isCodegraphIndexed(dir: string): boolean;
+export declare function readCodegraphMeta(dir: string): CodegraphMeta;
+export declare function writeCodegraphMeta(dir: string, meta: CodegraphMeta): void;
+export declare function isCodegraphFresh(dir: string, maxAgeMs?: number): boolean;
+export declare function getCurrentRevision(dir: string): string;
+export declare function getChangedFilesSince(dir: string, revision: string): string[];
+export declare function hasChangedSinceLastIndex(dir: string): boolean;
+export interface InstallResult {
+    success: boolean;
+    alreadyInstalled: boolean;
+    log: string;
+    error?: string;
+}
+export declare function installCodegraph(): InstallResult;
+export interface IndexResult {
+    success: boolean;
+    full: boolean;
+    log: string;
+    changedFiles: string[];
+    error?: string;
+}
+export declare function initCodegraphIndex(dir: string, agent: string): IndexResult;
+export declare function refreshCodegraphIndex(dir: string, agent: string): IndexResult;
+export declare function markCodegraphStale(dir: string): void;
+//# sourceMappingURL=codegraph.d.ts.map

package/dist/services/codegraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegraph.d.ts","sourceRoot":"","sources":["../../src/services/codegraph.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,OAAO,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;IAChB,aAAa,EAAE,MAAM,CAAA;IACrB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,aAAa,EAAE,MAAM,CAAA;IACrB,eAAe,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAA;IAC9C,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAMD,wBAAgB,oBAAoB,IAAI,OAAO,CAW9C;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CA6B5D;AAkDD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAgBzE;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAmB,GAAG,OAAO,CAOlF;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAYtD;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAc5E;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAK7D;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAA;IAChB,gBAAgB,EAAE,OAAO,CAAA;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAmChD;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,OAAO,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CA8E1E;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CA+D7E;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAGpD"}

package/dist/services/codegraph.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=codegraph.test.d.ts.map

package/dist/services/codegraph.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegraph.test.d.ts","sourceRoot":"","sources":["../../src/services/codegraph.test.ts"],"names":[],"mappings":""}

package/dist/services/question-guard.d.ts

@@ -27,6 +27,10 @@ export interface CheckResult {
     answeredByEvidence?: boolean;
     /** Whether the block was due to a duplicate question */
     duplicate?: boolean;
+    /** Field names missing from the question block (when allow=false due to missing recommendation) */
+    missingRecommendationFields?: string[];
+    /** Hint for how to rewrite a bare question into a recommended question */
+    rewriteHint?: string;
 }
 export interface QuestionGuard {
     /**

package/dist/services/question-guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"question-guard.d.ts","sourceRoot":"","sources":["../../src/services/question-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAG7D,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,KAAK,EAAE,OAAO,CAAA;IACd,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,wDAAwD;IACxD,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,WAAW,CAAA;IAC3E;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,4DAA4D;IAC5D,QAAQ,IAAI,MAAM,EAAE,CAAA;IACpB,6CAA6C;IAC7C,KAAK,IAAI,IAAI,CAAA;CACd;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,GAAE,MAAM,EAAO,GAAG,aAAa,CA0ChF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAAE,EACpB,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,iBAAiB,GAAG,IAAI,GACpC,MAAM,EAAE,CASV;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,MAAM,EAAE,EACnB,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,iBAAiB,GAAG,IAAI,GACpC,OAAO,CAGT;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,UAAU,EAAE,OAAO,CAAA;IACnB,oEAAoE;IACpE,YAAY,EAAE,OAAO,CAAA;IACrB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,iBAAiB,GAC7B,mBAAmB,CAmBrB"}
+{"version":3,"file":"question-guard.d.ts","sourceRoot":"","sources":["../../src/services/question-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAK7D,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,KAAK,EAAE,OAAO,CAAA;IACd,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,wDAAwD;IACxD,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,mGAAmG;IACnG,2BAA2B,CAAC,EAAE,MAAM,EAAE,CAAA;IACtC,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,WAAW,CAAA;IAC3E;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,4DAA4D;IAC5D,QAAQ,IAAI,MAAM,EAAE,CAAA;IACpB,6CAA6C;IAC7C,KAAK,IAAI,IAAI,CAAA;CACd;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,GAAE,MAAM,EAAO,GAAG,aAAa,CAuFhF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAAE,EACpB,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,iBAAiB,GAAG,IAAI,GACpC,MAAM,EAAE,CASV;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,MAAM,EAAE,EACnB,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,iBAAiB,GAAG,IAAI,GACpC,OAAO,CAGT;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,UAAU,EAAE,OAAO,CAAA;IACnB,oEAAoE;IACpE,YAAY,EAAE,OAAO,CAAA;IACrB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,iBAAiB,GAC7B,mBAAmB,CAmBrB"}

package/dist/services/recommended-question.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=recommended-question.test.d.ts.map

package/dist/services/recommended-question.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommended-question.test.d.ts","sourceRoot":"","sources":["../../src/services/recommended-question.test.ts"],"names":[],"mappings":""}

package/dist/services/supervisor-binding.d.ts

@@ -51,6 +51,8 @@ export interface SupervisorDecision {
     confidenceScore: number;
     /** Whether this was a preflight or post-stage review */
     reviewPhase: SupervisorReviewPhase;
+    /** Present when decision is 'escalate' — a recommended question for the human */
+    clarificationQuestion?: string;
     /** ISO timestamp */
     timestamp: string;
 }
@@ -104,7 +106,7 @@ export declare function isRegisteredTarget(name: string): {
  * not exist, it returns decision="block" with exists=false and explains that
  * the requested target is not registered.
  */
-export declare function runSupervisorReview(directory: string, targetName: string, ctx?: SupervisorContext): SupervisorDecision;
+export declare function runSupervisorReview(directory: string, targetName: string, ctx?: SupervisorContext, clarificationQuestion?: string): SupervisorDecision;
 /**
  * Shorthand: should execution proceed given a decision and the current config mode?
  * In "advisory" mode, only "block" with a missing-existence check is hard-stopped.

package/dist/services/supervisor-binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"supervisor-binding.d.ts","sourceRoot":"","sources":["../../src/services/supervisor-binding.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"supervisor-binding.d.ts","sourceRoot":"","sources":["../../src/services/supervisor-binding.ts"],"names":[],"mappings":"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"}

package/dist/tools/codebase-index.d.ts

@@ -0,0 +1,30 @@
+export interface FileSnapshot {
+    lastModifiedAt: string;
+    lastModifiedBy: string;
+    changeType: "added" | "modified" | "deleted";
+    sourceStage: string;
+}
+export interface ExplorationEntry {
+    stage: string;
+    timestamp: string;
+    filesExplored: string[];
+    reason: string;
+}
+export interface CodebaseIndex {
+    exists: boolean;
+    lastUpdatedAt: string;
+    lastUpdatedBy: string;
+    sourceStage: string;
+    changedFiles: string[];
+    fileSnapshots: Record<string, FileSnapshot>;
+    explorationHistory: ExplorationEntry[];
+    summaryVersion: number;
+    freshnessStatus: "fresh" | "stale" | "unknown";
+}
+export declare function readCodebaseIndex(dir: string): CodebaseIndex;
+export declare function isCodebaseIndexFresh(dir: string, maxAgeMs?: number): boolean;
+export declare function writeCodebaseIndex(dir: string, index: Omit<CodebaseIndex, "exists">): void;
+export declare function appendChangedFiles(dir: string, agent: string, stage: string, files: string[]): void;
+export declare function recordExploration(dir: string, stage: string, filesExplored: string[], reason: string): void;
+export declare function getFileSnapshot(dir: string, filePath: string): FileSnapshot | null;
+//# sourceMappingURL=codebase-index.d.ts.map

package/dist/tools/codebase-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codebase-index.d.ts","sourceRoot":"","sources":["../../src/tools/codebase-index.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,MAAM,CAAA;IACtB,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAAA;IAC5C,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,CAAA;IACf,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IAC3C,kBAAkB,EAAE,gBAAgB,EAAE,CAAA;IACtC,cAAc,EAAE,MAAM,CAAA;IACtB,eAAe,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAA;CAC/C;AAMD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CA+B5D;AAkED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAgB,GAAG,OAAO,CAOnF;AAOD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,GAAG,IAAI,CAyB1F;AAED,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EAAE,GACd,IAAI,CAgCN;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,EAAE,EACvB,MAAM,EAAE,MAAM,GACb,IAAI,CAuBN;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAGlF"}

package/dist/tools/codebase-index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=codebase-index.test.d.ts.map

package/dist/tools/codebase-index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codebase-index.test.d.ts","sourceRoot":"","sources":["../../src/tools/codebase-index.test.ts"],"names":[],"mappings":""}

package/dist/tools/codegraph-tool.d.ts

@@ -0,0 +1,3 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+export declare const codegraphTool: ToolDefinition;
+//# sourceMappingURL=codegraph-tool.d.ts.map

package/dist/tools/codegraph-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegraph-tool.d.ts","sourceRoot":"","sources":["../../src/tools/codegraph-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAa/D,eAAO,MAAM,aAAa,EAAE,cA6G1B,CAAA"}

package/dist/tools/planning-state-lib.d.ts

@@ -49,6 +49,16 @@ export interface PlanningState {
     blockers: string[];
     /** TDD workflow state (undefined when TDD not active) */
     tdd: TDDState | undefined;
+    /** When this state was last updated */
+    lastUpdatedAt: string;
+    /** Which agent last updated the state */
+    lastUpdatedBy: string;
+    /** Phase when state was last updated */
+    lastUpdatedPhase: number;
+    /** Monotonically increasing version number */
+    summaryVersion: number;
+    /** Whether the state is still considered fresh enough to use */
+    freshnessStatus: "fresh" | "stale" | "unknown";
 }
 /** Extended PlanningState with TDD state for internal use */
 export type PlanningStateWithTDD = PlanningState & {
@@ -57,6 +67,19 @@ export type PlanningStateWithTDD = PlanningState & {
 export declare function getTDDState(state: PlanningState): TDDState | undefined;
 export declare function parseState(content: string): Record<string, unknown>;
 export declare function timestamp(): string;
+/**
+ * Returns true if state was updated within maxAgeMs milliseconds.
+ * Defaults to 5 minutes.
+ */
+export declare function isStateFresh(state: PlanningState, maxAgeMs?: number): boolean;
+/**
+ * Mark the state as stale by updating freshnessStatus and appending to history.
+ */
+export declare function markStateStale(dir: string): void;
+/**
+ * Publish a state update with fresh metadata. Called after any significant change.
+ */
+export declare function publishStateUpdate(dir: string, agent: string, phase: number): void;
 export declare function appendHistory(stateContent: string, action: string): string;
 export declare function readPlanningState(dir: string): PlanningState;
 export declare function hasDesignGateSatisfied(state: PlanningState): boolean;

package/dist/tools/planning-state-lib.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"planning-state-lib.d.ts","sourceRoot":"","sources":["../../src/tools/planning-state-lib.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"planning-state-lib.d.ts","sourceRoot":"","sources":["../../src/tools/planning-state-lib.ts"],"names":[],"mappings":"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"}

package/docs/agents/index.md

@@ -0,0 +1,154 @@
+# Agents
+
+FlowDeck runs a 27-agent system coordinated by an orchestrator. Each agent has a specific capability contract and specialized model configuration. The orchestrator selects specialists based on context and delegates work through the `delegate` tool.
+
+## Delegation Model
+
+The orchestrator holds the user session, decomposes requests, and dispatches to specialist agents via the `delegate` tool. Each specialist operates in its own context window and reports results back to the orchestrator. Agents are classified by mode:
+
+- **primary**: visible and selectable from the user interface
+- **subagent**: internal only, invoked programmatically by other agents
+- **all**: works in both primary and subagent contexts
+
+```
+user → @orchestrator → @planner
+                  → @backend-coder
+                  → @frontend-coder
+                  → @reviewer
+                  → @security-auditor
+                  → ...
+```
+
+All agent configurations are in `src/agents/`. Agent definitions use YAML frontmatter (description, mode, model, temperature, steps, permission).
+
+---
+
+## Orchestration
+
+### @orchestrator
+
+The central coordinator. Delegates to specialist agents, coordinates wave-structured task execution, and routes tool calls through the supervisor guard for pre-flight and post-execution review. The orchestrator holds the user session context and is the only agent visible as the default agent.
+
+---
+
+## Planning
+
+### @architect
+
+System design and boundary decisions. Produces architecture diagrams, evaluates technical choices, and enforces architectural constraints. Works upstream of implementation to establish clear boundaries before coding starts.
+
+### @planner
+
+Wave-structured task planning. Takes feature requests and produces phased implementation plans with dependency graphs, file-level scope assignments, and observable success criteria per step. The output of `@planner` feeds directly into `@backend-coder` and `@frontend-coder`.
+
+### @discusser
+
+Structured pre-planning Q&A. Asks clarifying questions in a systematic order to surface ambiguities before `@planner` produces a plan. Prevents the wrong plan from being built by ensuring the problem is fully understood first.
+
+### @plan-checker
+
+Reviews PLAN.md files for quality before execution. Checks completeness, feasibility, and testability. Returns PASS or FAIL with specific recommendations.
+
+---
+
+## Implementation
+
+### @backend-coder
+
+Implements server-side logic using TDD. Specializes in TypeScript/Node.js services, database integrations, API route handlers, and background workers. Uses `tdd-workflow` skill by default — writes failing tests first, then minimum implementation.
+
+### @frontend-coder
+
+Implements UI and client-side interactions using TDD. Specializes in React/Vue components, state management, API client calls, and responsive styling. Uses the same TDD discipline as `@backend-coder` but adapted for the frontend context.
+
+### @devops
+
+Infrastructure and deployment automation. Handles Docker, Kubernetes, CI/CD pipelines, cloud provisioning, and environment configuration. Ensures the system is deployable and monitorable before any feature is considered complete.
+
+### @tester
+
+Test strategy and gap detection. Analyzes modified files, identifies coverage gaps, and suggests the minimum viable test set to close them. Uses `test-gap-detector` and `test-coverage` skills to drive coverage enforcement.
+
+### @debug-specialist
+
+Systematic bug diagnosis and repair. Follows a structured root-cause analysis workflow: isolate the failure mode, confirm the reproduction case, identify the root cause, apply a targeted fix, then verify with a regression test.
+
+### @build-error-resolver
+
+Diagnoses and fixes build errors, compilation failures, and dependency issues. Use immediately when a build fails, types error out, or dependencies are broken.
+
+---
+
+## Review
+
+### @reviewer
+
+Post-commit code review. Reviews only changed code, applies the security checklist first, then quality checks. Reports findings severity-ranked with specific remediation steps and a clear pass/fail verdict.
+
+### @security-auditor
+
+Security vulnerability detection. Scans for OWASP Top 10 issues: SQL injection, XSS, authentication bypass, path traversal, hardcoded credentials, and insecure deserialization. Requires a separate review pass before merging any security-sensitive change.
+
+### @risk-analyst
+
+Failure mode analysis. Identifies what can break from a given change, estimates blast radius, and ranks risks by likelihood and impact. Produces a risk register with specific mitigations for each identified failure mode.
+
+---
+
+## Governance
+
+### @policy-enforcer
+
+Governance rule enforcement. Validates that agent actions comply with configured policies: guard rails, permission scopes, architectural constraints, and coding standards. Escalates violations with a specific policy citation.
+
+### @supervisor
+
+Pre-flight and post-execution review of tool calls. Intercepts and validates agent actions against configured policies before execution, and audits decisions after completion for compliance tracking.
+
+---
+
+## Utility
+
+### @writer
+
+Documentation generation. Reads code structure and produces documentation: API docs from route definitions, component docs from props, README from package manifest. Follows the project conventions in `docs/`.
+
+### @doc-updater
+
+Updates existing documentation to reflect code changes. Tracks which docs need updating when files are modified and keeps documentation in sync with implementation.
+
+### @mapper
+
+Codebase indexing. Builds and maintains a searchable index of the codebase: file purposes, dependency graph, API surface, and ownership. Used by `@planner` and `@discusser` for context before planning.
+
+### @code-explorer
+
+Explores unfamiliar code quickly. Analyzes file structure, traces dependencies, and produces summaries that help other agents understand a new module or codebase area without reading every line.
+
+### @researcher
+
+API docs and library research. Reads documentation, extracts relevant patterns, and answers questions about libraries, frameworks, and tools used in the project.
+
+### @performance-optimizer
+
+Identifies and fixes performance bottlenecks using data. Profiles code, detects N+1 queries, analyzes bundle size, and optimizes React render performance. Measures before and after to verify improvements.
+
+### @refactor-guide
+
+Guides safe refactoring of existing code without changing behavior. Provides step-by-step transformation guidance, ensures tests stay green, and helps extract functions or restructure modules.
+
+### @auto-learner
+
+Continuously learns from project patterns and agent decisions. Improves future recommendations by analyzing what worked well in similar past tasks.
+
+### @design
+
+Design-first workflow coordinator. Produces wireframes, component specs, and design token decisions. Runs before `@frontend-coder` starts implementation to ensure UI consistency and user experience quality.
+
+### @task-splitter
+
+Decomposes complex tasks into parallel workstreams. Analyzes dependencies, groups independent work into waves, and produces a plan for multi-agent execution.
+
+### @architect (already listed in Planning)
+
+System design and boundary decisions. See Planning section above.