twining-mcp 1.8.2 → 1.11.0

package/README.md

@@ -80,7 +80,7 @@ Agents self-select into work by reading the blackboard. No central bottleneck. N
 /plugin install twining@twining-marketplace
 ```
 
-Includes the MCP server, 7 skills, lifecycle hooks, coordinator subagent, and commands. Skills teach Claude when and how to use Twining — everything works automatically.
+Includes the MCP server, 8 skills, lifecycle hooks, coordinator subagent, and commands. Skills teach Claude when and how to use Twining — everything works automatically.
 
 ### Team Auto-Install
 
@@ -166,6 +166,7 @@ A web dashboard starts automatically at `http://localhost:24282` — browse deci
 | `twining_trace` | Trace a decision's dependency chain upstream and downstream |
 | `twining_reconsider` | Flag a decision for reconsideration with impact analysis |
 | `twining_override` | Override a decision, optionally creating a replacement |
+| `twining_promote` | Promote provisional decisions to active after validation |
 | `twining_search_decisions` | Search decisions by keyword or semantic similarity |
 | `twining_link_commit` | Link a git commit to a decision |
 | `twining_commits` | Find decisions by git commit |
@@ -178,6 +179,7 @@ A web dashboard starts automatically at `http://localhost:24282` — browse deci
 | `twining_read` | Read entries filtered by type, scope, or agent |
 | `twining_query` | Semantic search across all entries |
 | `twining_recent` | Get the latest entries |
+| `twining_dismiss` | Remove resolved or false-positive entries by ID |
 
 ### Context Assembly
 
@@ -186,9 +188,6 @@ A web dashboard starts automatically at `http://localhost:24282` — browse deci
 | `twining_assemble` | Build tailored context for a task within a token budget |
 | `twining_summarize` | High-level summary of project state |
 | `twining_what_changed` | What changed since a given point in time |
-| `twining_status` | Health check — entry counts, warnings, agent status |
-| `twining_archive` | Move stale entries to archive |
-| `twining_export` | Export full state as markdown |
 
 ### Knowledge Graph
 
@@ -198,6 +197,7 @@ A web dashboard starts automatically at `http://localhost:24282` — browse deci
 | `twining_add_relation` | Add a relation between entities |
 | `twining_neighbors` | Traverse from an entity up to depth 3 |
 | `twining_graph_query` | Search by name or property |
+| `twining_prune_graph` | Remove orphaned entities with no relations |
 
 Decisions auto-populate the graph: `twining_decide` creates file and function entities with `decided_by` relations for every affected file.
 
@@ -205,12 +205,22 @@ Decisions auto-populate the graph: `twining_decide` creates file and function en
 
 | Tool | What It Does |
 |------|-------------|
+| `twining_register` | Register or update an agent in the coordination registry |
 | `twining_agents` | List agents with capabilities and liveness |
 | `twining_discover` | Find agents matching required capabilities |
 | `twining_delegate` | Post a delegation request with capability requirements |
 | `twining_handoff` | Hand off work with results and auto-assembled context |
 | `twining_acknowledge` | Acknowledge receipt of a handoff |
 
+### Verification & Lifecycle
+
+| Tool | What It Does |
+|------|-------------|
+| `twining_verify` | Run verification checks — test coverage, warnings, assembly tracking |
+| `twining_status` | Health check — entry counts, warnings, agent status |
+| `twining_archive` | Move stale entries to archive |
+| `twining_export` | Export full state as markdown |
+
 ## How It Works
 
 All state lives in `.twining/` as plain files — JSONL for the blackboard, JSON for decisions, graph, agents, and handoffs. Everything is `jq`-queryable, `grep`-able, and git-diffable. No database. No cloud. No accounts.
@@ -293,7 +303,7 @@ That's it — the PostHog project key is built into the source code. If you run
 ```bash
 npm install       # Install dependencies
 npm run build     # Build
-npm test          # Run tests (570+ tests)
+npm test          # Run tests (600+ tests)
 npm run test:watch
 ```
 

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,eAAO,MAAM,cAAc,EAAE,aA8C5B,CAAC;AA+BF;;;GAGG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,CAc5D"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,eAAO,MAAM,cAAc,EAAE,aAqD5B,CAAC;AA+BF;;;GAGG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,CA0B5D"}

package/dist/config.js

@@ -16,11 +16,11 @@ export const DEFAULT_CONFIG = {
     context_assembly: {
         default_max_tokens: 4000,
         priority_weights: {
-            recency: 0.3,
-            relevance: 0.3,
-            decision_confidence: 0.2,
+            recency: 0.2,
+            relevance: 0.2,
+            decision_confidence: 0.15,
             warning_boost: 0.1,
-            graph_connectivity: 0.1,
+            graph_reachability: 0.35,
         },
     },
     conflict_resolution: "human",
@@ -50,6 +50,13 @@ export const DEFAULT_CONFIG = {
     instructions: {
         auto_inject: true, // Include workflow instructions in MCP initialize response
     },
+    tools: {
+        mode: "full", // "full" or "lite" — lite registers only core tools
+        full_surface: false, // when false, hide 16 rarely-used tools to reduce context noise
+    },
+    graph: {
+        auto_populate: false, // when false, skip auto-graph-population from tool calls
+    },
 };
 /** Deep merge source into target, returning a new object */
 function deepMerge(target, source) {
@@ -87,6 +94,14 @@ export function loadConfig(twiningDir) {
     if (parsed === null || parsed === undefined || typeof parsed !== "object") {
         return { ...DEFAULT_CONFIG };
     }
-    return deepMerge(DEFAULT_CONFIG, parsed);
+    const config = deepMerge(DEFAULT_CONFIG, parsed);
+    // Validate priority weights sum to 1.0
+    const weights = config.context_assembly.priority_weights;
+    const weightSum = Object.values(weights).reduce((a, b) => (a ?? 0) + (b ?? 0), 0);
+    if (Math.abs(weightSum - 1.0) > 0.01) {
+        console.error(`[twining] Warning: priority_weights sum to ${weightSum}, expected 1.0. Using defaults.`);
+        config.context_assembly.priority_weights = { ...DEFAULT_CONFIG.context_assembly.priority_weights };
+    }
+    return config;
 }
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/dashboard/public/app.js

@@ -2238,7 +2238,9 @@ var ENTITY_COLORS = {
   concept: '#f59e0b',
   pattern: '#10b981',
   dependency: '#ef4444',
-  api_endpoint: '#ec4899'
+  api_endpoint: '#ec4899',
+  agent: '#14b8a6',
+  commit: '#a855f7'
 };
 
 // Track which entity types are visible (null = all)

package/dist/engine/blackboard.d.ts

@@ -9,6 +9,7 @@ import type { Embedder } from "../embeddings/embedder.js";
 import type { IndexManager } from "../embeddings/index-manager.js";
 import type { SearchEngine, BlackboardSearchResult } from "../embeddings/search.js";
 import type { Archiver } from "./archiver.js";
+import type { GraphAutoPopulator } from "./graph-auto-populator.js";
 export declare class BlackboardEngine {
     private readonly store;
     private readonly embedder;
@@ -16,9 +17,12 @@ export declare class BlackboardEngine {
     private readonly searchEngine;
     private archiver;
     private archiveThreshold;
+    private graphPopulator;
     constructor(store: BlackboardStore, embedder?: Embedder | null, indexManager?: IndexManager | null, searchEngine?: SearchEngine | null);
     /** Inject archiver for threshold-based auto-archiving (spec §6.1.3). */
     setArchiver(archiver: Archiver, config: TwiningConfig): void;
+    /** Inject graph auto-populator for relation extraction from posts. */
+    setGraphPopulator(populator: GraphAutoPopulator): void;
     /** Post a new blackboard entry with validation and defaults. */
     post(input: {
         entry_type: string;

package/dist/engine/blackboard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blackboard.d.ts","sourceRoot":"","sources":["../../src/engine/blackboard.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAEjE,OAAO,KAAK,EAAE,eAAe,EAAa,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEnF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACpF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IACnD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IACnD,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,gBAAgB,CAAuB;gBAG7C,KAAK,EAAE,eAAe,EACtB,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,EAC1B,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI,EAClC,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI;IAQpC,wEAAwE;IACxE,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI;IAK5D,gEAAgE;IAC1D,IAAI,CAAC,KAAK,EAAE;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAiE9C,qDAAqD;IAC/C,IAAI,CAAC,OAAO,CAAC,EAAE;QACnB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,eAAe,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAUhE,oEAAoE;IAC9D,KAAK,CACT,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GACnD,OAAO,CAAC;QACT,OAAO,EAAE,sBAAsB,EAAE,CAAC;QAClC,aAAa,EAAE,OAAO,CAAC;KACxB,CAAC;IAcF,kEAAkE;IAC5D,MAAM,CACV,CAAC,CAAC,EAAE,MAAM,EACV,WAAW,CAAC,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC;QAAE,OAAO,EAAE,eAAe,EAAE,CAAA;KAAE,CAAC;IAK1C,oFAAoF;IAC9E,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAkBpF"}
+{"version":3,"file":"blackboard.d.ts","sourceRoot":"","sources":["../../src/engine/blackboard.ts"],"names":[],"mappings":"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"}

package/dist/engine/blackboard.js

@@ -13,6 +13,7 @@ export class BlackboardEngine {
     searchEngine;
     archiver = null;
     archiveThreshold = null;
+    graphPopulator = null;
     constructor(store, embedder, indexManager, searchEngine) {
         this.store = store;
         this.embedder = embedder ?? null;
@@ -24,6 +25,10 @@ export class BlackboardEngine {
         this.archiver = archiver;
         this.archiveThreshold = config.archive.max_blackboard_entries_before_archive;
     }
+    /** Inject graph auto-populator for relation extraction from posts. */
+    setGraphPopulator(populator) {
+        this.graphPopulator = populator;
+    }
     /** Post a new blackboard entry with validation and defaults. */
     async post(input) {
         // Validate entry_type
@@ -50,6 +55,10 @@ export class BlackboardEngine {
             relates_to: input.relates_to,
             agent_id: input.agent_id ?? "main",
         });
+        // Auto-populate graph with scope/relation entities (best-effort)
+        if (this.graphPopulator) {
+            await this.graphPopulator.onPost(entry);
+        }
         // Generate embedding (Phase 2) — never let embedding failure prevent the post
         if (this.embedder && this.indexManager) {
             try {

package/dist/engine/blackboard.js.map

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

package/dist/engine/context-assembler.d.ts

@@ -30,6 +30,19 @@ export declare class ContextAssembler {
      * Implements spec section 4.3 (twining_assemble).
      */
     assemble(task: string, scope: string, maxTokens?: number, agentId?: string): Promise<AssembledContext>;
+    /**
+     * Assemble context and include a status summary inline.
+     * Combines assemble + summarize into one call (P5.1).
+     */
+    assembleWithStatus(task: string, scope: string, maxTokens?: number, agentId?: string): Promise<{
+        context: AssembledContext;
+        status_summary: string;
+    }>;
+    /**
+     * Format assembled context as structured markdown for LLM consumption.
+     * Produces imperative sentences and numbered lists instead of raw JSON.
+     */
+    static formatForLLM(ctx: AssembledContext, statusSummary?: string): string;
     /**
      * High-level summary of project or scope state.
      * Implements spec section 4.3 (twining_summarize).
@@ -45,7 +58,7 @@ export declare class ContextAssembler {
      * Decisions whose affected_files/symbols have more graph relations
      * to the scope get a higher boost (0.0 to 1.0).
      */
-    private computeGraphConnectivity;
+    private computeGraphReachability;
     /**
      * Populate related_entities from the knowledge graph.
      * Finds entities matching the scope and gets their immediate neighbors.

package/dist/engine/context-assembler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-assembler.d.ts","sourceRoot":"","sources":["../../src/engine/context-assembler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EACV,gBAAgB,EAGhB,eAAe,EACf,aAAa,EACb,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAkB3B,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwB;IACvD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IACnD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAE/C,qFAAqF;IACrF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;gBAGvD,eAAe,EAAE,eAAe,EAChC,aAAa,EAAE,aAAa,EAC5B,YAAY,EAAE,YAAY,GAAG,IAAI,EACjC,MAAM,EAAE,aAAa,EACrB,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,EAChC,cAAc,CAAC,EAAE,cAAc,GAAG,IAAI,EACtC,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI,EAClC,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI;IAYhC,0EAA0E;IAC1E,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI3C;;;OAGG;IACG,QAAQ,CACZ,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,gBAAgB,CAAC;IAqW5B;;;OAGG;IACG,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IA8EzD;;;OAGG;IACG,WAAW,CACf,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,iBAAiB,CAAC;IAuD7B;;;;OAIG;YACW,wBAAwB;IA4DtC;;;;OAIG;YACW,kBAAkB;IA2ChC,qDAAqD;IACrD,OAAO,CAAC,YAAY;IAMpB,sDAAsD;IACtD,OAAO,CAAC,eAAe;CAYxB"}
+{"version":3,"file":"context-assembler.d.ts","sourceRoot":"","sources":["../../src/engine/context-assembler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EACV,gBAAgB,EAGhB,eAAe,EACf,aAAa,EACb,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAkB3B,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwB;IACvD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IACnD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAE/C,qFAAqF;IACrF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;gBAGvD,eAAe,EAAE,eAAe,EAChC,aAAa,EAAE,aAAa,EAC5B,YAAY,EAAE,YAAY,GAAG,IAAI,EACjC,MAAM,EAAE,aAAa,EACrB,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,EAChC,cAAc,CAAC,EAAE,cAAc,GAAG,IAAI,EACtC,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI,EAClC,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI;IAYhC,0EAA0E;IAC1E,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI3C;;;OAGG;IACG,QAAQ,CACZ,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,gBAAgB,CAAC;IAqX5B;;;OAGG;IACG,kBAAkB,CACtB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,OAAO,EAAE,gBAAgB,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;IAajE;;;OAGG;IACH,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,gBAAgB,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM;IAmH1E;;;OAGG;IACG,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IA8EzD;;;OAGG;IACG,WAAW,CACf,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,iBAAiB,CAAC;IAuD7B;;;;OAIG;YACW,wBAAwB;IAsHtC;;;;OAIG;YACW,kBAAkB;IA2ChC,qDAAqD;IACrD,OAAO,CAAC,YAAY;IAMpB,sDAAsD;IACtD,OAAO,CAAC,eAAe;CAYxB"}

package/dist/engine/context-assembler.js

@@ -103,22 +103,29 @@ export class ContextAssembler {
                 }
             }
         }
-        // 5. Compute graph connectivity scores for decisions (spec §5.5)
-        const connectivityScores = await this.computeGraphConnectivity(scope, mergedDecisionMap);
+        // 5. Compute graph reachability scores for decisions
+        const { scores: reachabilityScores, paths: reachabilityPaths } = await this.computeGraphReachability(scope, mergedDecisionMap);
         // 6. Score each item
         const scoredItems = [];
-        const graphWeight = weights.graph_connectivity ?? 0;
+        const graphWeight = weights.graph_reachability ?? weights.graph_connectivity ?? 0;
+        // Adaptive weight fallback: if graph returns 0 for all candidates,
+        // redistribute graph weight proportionally to other signals
+        const maxGraphScore = Math.max(0, ...Array.from(reachabilityScores.values()));
+        const effectiveGraphWeight = maxGraphScore === 0 ? 0 : graphWeight;
+        const weightScale = maxGraphScore === 0 && graphWeight > 0
+            ? 1.0 / (1.0 - graphWeight)
+            : 1.0;
         for (const [id, decision] of mergedDecisionMap) {
             const recency = this.recencyScore(decision.timestamp, now);
             const relevance = decisionRelevance.get(id) ?? 0.5;
             const confidence = this.confidenceScore(decision.confidence);
             const warningBoost = 0;
-            const connectivity = connectivityScores.get(id) ?? 0;
-            const score = recency * weights.recency +
-                relevance * weights.relevance +
-                confidence * weights.decision_confidence +
-                warningBoost * weights.warning_boost +
-                connectivity * graphWeight;
+            const reachability = reachabilityScores.get(id) ?? 0;
+            const score = recency * weights.recency * weightScale +
+                relevance * weights.relevance * weightScale +
+                confidence * weights.decision_confidence * weightScale +
+                warningBoost * weights.warning_boost * weightScale +
+                reachability * effectiveGraphWeight;
             const text = `${decision.summary} ${decision.rationale} ${decision.confidence} ${decision.affected_files.join(", ")}`;
             scoredItems.push({
                 type: "decision",
@@ -133,10 +140,10 @@ export class ContextAssembler {
             const relevance = entryRelevance.get(id) ?? 0.5;
             const confidence = 0.5; // Neutral for non-decisions
             const warningBoost = entry.entry_type === "warning" ? 1.0 : 0.0;
-            const score = recency * weights.recency +
-                relevance * weights.relevance +
-                confidence * weights.decision_confidence +
-                warningBoost * weights.warning_boost;
+            const score = recency * weights.recency * weightScale +
+                relevance * weights.relevance * weightScale +
+                confidence * weights.decision_confidence * weightScale +
+                warningBoost * weights.warning_boost * weightScale;
             const text = `${entry.summary} ${entry.detail}`;
             scoredItems.push({
                 type: entry.entry_type,
@@ -196,13 +203,18 @@ export class ContextAssembler {
                 continue;
             if (item.type === "decision") {
                 const d = item.data;
-                activeDecisionResults.push({
+                const decisionEntry = {
                     id: d.id,
                     summary: d.summary,
                     rationale: d.rationale,
                     confidence: d.confidence,
                     affected_files: d.affected_files,
-                });
+                };
+                const path = reachabilityPaths.get(d.id);
+                if (path) {
+                    decisionEntry.relevance_path = path;
+                }
+                activeDecisionResults.push(decisionEntry);
             }
             else {
                 const e = item.data;
@@ -300,7 +312,9 @@ export class ContextAssembler {
         if (this.handoffStore) {
             const handoffEntries = await this.handoffStore.list({ scope, limit: 5 });
             if (handoffEntries.length > 0) {
-                result.recent_handoffs = handoffEntries.map((h) => ({
+                // Load full records to get individual results for detailed checklist
+                const fullHandoffs = await Promise.all(handoffEntries.map((h) => this.handoffStore.get(h.id)));
+                result.recent_handoffs = handoffEntries.map((h, i) => ({
                     id: h.id,
                     source_agent: h.source_agent,
                     target_agent: h.target_agent ?? "",
@@ -309,6 +323,7 @@ export class ContextAssembler {
                     result_status: h.result_status,
                     acknowledged: h.acknowledged,
                     created_at: h.created_at,
+                    results: fullHandoffs[i]?.results,
                 }));
             }
         }
@@ -340,6 +355,125 @@ export class ContextAssembler {
         this.assemblyLog.set(agentId ?? "main", result.assembled_at);
         return result;
     }
+    /**
+     * Assemble context and include a status summary inline.
+     * Combines assemble + summarize into one call (P5.1).
+     */
+    async assembleWithStatus(task, scope, maxTokens, agentId) {
+        const context = await this.assemble(task, scope, maxTokens, agentId);
+        // Status summary is best-effort — don't let it break assembly
+        let statusSummary = "";
+        try {
+            const summary = await this.summarize(scope);
+            statusSummary = summary.recent_activity_summary;
+        }
+        catch {
+            // Non-fatal: skip status summary if summarize fails
+        }
+        return { context, status_summary: statusSummary };
+    }
+    /**
+     * Format assembled context as structured markdown for LLM consumption.
+     * Produces imperative sentences and numbered lists instead of raw JSON.
+     */
+    static formatForLLM(ctx, statusSummary) {
+        // Short-circuit: if there's nothing useful to say, return minimal output
+        const hasContent = ctx.active_warnings.length > 0 ||
+            ctx.active_decisions.length > 0 ||
+            ctx.recent_findings.length > 0 ||
+            ctx.open_needs.length > 0 ||
+            ctx.recent_questions.length > 0 ||
+            (ctx.recent_handoffs && ctx.recent_handoffs.length > 0) ||
+            ctx.planning_state != null;
+        if (!hasContent) {
+            return `No prior context for scope: ${ctx.scope}`;
+        }
+        const sections = [];
+        // Header
+        sections.push(`## Before You Start (scope: ${ctx.scope})`);
+        // 1. Warnings FIRST — "what not to do" is the most actionable signal
+        if (ctx.active_warnings.length > 0) {
+            sections.push("\n### STOP — READ THESE WARNINGS");
+            for (const w of ctx.active_warnings) {
+                sections.push(`- **${w.summary}**${w.detail ? `\n  ${w.detail}` : ""}`);
+            }
+        }
+        // 2. Continue from (handoffs) — second priority, provides continuation context
+        if (ctx.recent_handoffs && ctx.recent_handoffs.length > 0) {
+            sections.push("\n### CONTINUE FROM PREVIOUS WORK");
+            for (const h of ctx.recent_handoffs) {
+                const status = h.acknowledged ? "acknowledged" : "pending";
+                sections.push(`**${h.source_agent} → ${h.target_agent || "any"}** (${status}): ${h.summary}`);
+                // Detailed checklist of individual results
+                if (h.results && h.results.length > 0) {
+                    for (const r of h.results) {
+                        const icon = r.status === "completed" ? "[x]" : r.status === "blocked" ? "[BLOCKED]" : "[ ]";
+                        sections.push(`  - ${icon} ${r.description}${r.notes ? ` — ${r.notes}` : ""}`);
+                    }
+                }
+            }
+        }
+        // 3. Decisions — imperative framing with files prominent
+        if (ctx.active_decisions.length > 0) {
+            sections.push("\n### DECISIONS TO RESPECT");
+            for (let i = 0; i < ctx.active_decisions.length; i++) {
+                const d = ctx.active_decisions[i];
+                const files = d.affected_files?.length > 0 ? `\n   Files: ${d.affected_files.join(", ")}` : "";
+                sections.push(`${i + 1}. **${d.summary}** (${d.confidence})${files}`);
+                sections.push(`   Why: ${d.rationale}`);
+            }
+        }
+        else {
+            sections.push("\nNo active decisions for this scope.");
+        }
+        // 4. Open needs — what still needs to be done
+        if (ctx.open_needs.length > 0) {
+            sections.push("\n### REMAINING WORK");
+            for (const n of ctx.open_needs) {
+                sections.push(`- [ ] ${n.summary}`);
+            }
+        }
+        // 5. Recent findings (brief, only if not redundant with decisions)
+        if (ctx.recent_findings.length > 0) {
+            // Filter out findings whose summary is substantially duplicated by a decision
+            const decisionSummaries = ctx.active_decisions.map((d) => d.summary.toLowerCase());
+            const uniqueFindings = ctx.recent_findings.filter((f) => {
+                const fLower = f.summary.toLowerCase();
+                return !decisionSummaries.some((ds) => ds.includes(fLower.slice(0, 30)) || fLower.includes(ds.slice(0, 30)));
+            });
+            if (uniqueFindings.length > 0) {
+                sections.push("\n### FINDINGS");
+                for (const f of uniqueFindings) {
+                    sections.push(`- ${f.summary}`);
+                }
+            }
+        }
+        // 6. Quick reference section — compact metadata
+        const quickRef = ["\n---"];
+        // Status summary (P5.1)
+        if (statusSummary) {
+            quickRef.push(`Status: ${statusSummary}`);
+        }
+        // Questions
+        if (ctx.recent_questions.length > 0) {
+            quickRef.push(`Open questions: ${ctx.recent_questions.map((q) => q.summary).join("; ")}`);
+        }
+        // Planning state
+        if (ctx.planning_state) {
+            quickRef.push(`Planning: Phase ${ctx.planning_state.current_phase}, ${ctx.planning_state.progress}`);
+            if (ctx.planning_state.blockers.length > 0) {
+                quickRef.push(`Blockers: ${ctx.planning_state.blockers.join("; ")}`);
+            }
+        }
+        // Suggested agents
+        if (ctx.suggested_agents && ctx.suggested_agents.length > 0) {
+            quickRef.push(`Suggested agents: ${ctx.suggested_agents.map((a) => `${a.agent_id} (${a.capabilities.join(", ")})`).join("; ")}`);
+        }
+        if (quickRef.length > 1) {
+            sections.push(quickRef.join("\n"));
+        }
+        return sections.join("\n");
+    }
     /**
      * High-level summary of project or scope state.
      * Implements spec section 4.3 (twining_summarize).
@@ -443,45 +577,91 @@ export class ContextAssembler {
      * Decisions whose affected_files/symbols have more graph relations
      * to the scope get a higher boost (0.0 to 1.0).
      */
-    async computeGraphConnectivity(scope, decisions) {
+    async computeGraphReachability(scope, decisions) {
         const scores = new Map();
+        const paths = new Map();
         if (!this.graphEngine)
-            return scores;
+            return { scores, paths };
         try {
-            // Find entities matching the scope
+            // 1. Find entities matching scope, filtered to scope prefix
             const { entities: scopeEntities } = await this.graphEngine.query(scope, undefined, 20);
-            if (scopeEntities.length === 0)
-                return scores;
-            const scopeEntityIds = new Set(scopeEntities.map((e) => e.id));
-            const scopeEntityNames = new Set(scopeEntities.map((e) => e.name));
-            for (const [id, decision] of decisions) {
-                let connectionCount = 0;
-                const targets = [
-                    ...decision.affected_files,
-                    ...decision.affected_symbols,
-                ];
-                for (const target of targets) {
-                    const { entities: targetEntities } = await this.graphEngine.query(target, undefined, 3);
-                    for (const te of targetEntities) {
-                        const { neighbors } = await this.graphEngine.neighbors(te.id, 1);
-                        for (const n of neighbors) {
-                            if (scopeEntityIds.has(n.entity.id) ||
-                                scopeEntityNames.has(n.entity.name)) {
-                                connectionCount++;
+            const filteredScopeEntities = scopeEntities.filter((e) => e.name.startsWith(scope) || scope.startsWith(e.name));
+            if (filteredScopeEntities.length === 0)
+                return { scores, paths };
+            // Relation types to follow during BFS
+            const followTypes = [
+                "depends_on", "decided_by", "implements", "affects", "produces", "challenged",
+            ];
+            // Relation type scoring bonuses
+            const relationBonus = {
+                decided_by: 1.0,
+                affects: 1.0,
+                depends_on: 0.8,
+                implements: 0.8,
+                produces: 0.7,
+                challenged: 0.7,
+                supersedes: 0.6,
+                tested_by: 0.6,
+                related_to: 0.5,
+            };
+            // Path length scoring (indexed by hop count - 1)
+            const depthScore = [1.0, 0.7, 0.4];
+            // Build set of decision IDs for quick lookup
+            const decisionIds = new Set(decisions.keys());
+            // 2. For each scope entity, do typed BFS traversal (max depth 3)
+            for (const scopeEntity of filteredScopeEntities) {
+                try {
+                    const { neighbors } = await this.graphEngine.neighbors(scopeEntity.id, 3, followTypes);
+                    for (const neighbor of neighbors) {
+                        // Check if this neighbor is a decision concept node
+                        if (neighbor.entity.type === "concept" && decisionIds.has(neighbor.entity.name)) {
+                            const decisionId = neighbor.entity.name;
+                            // Determine hop depth from relation (approximate: use relation type)
+                            // Since neighbors() returns flat results, we estimate depth from the BFS order
+                            // The relation tells us the connection type
+                            const relType = neighbor.relation.type;
+                            const bonus = relationBonus[relType] ?? 0.5;
+                            // Use depth 0 (1-hop) as default since neighbors are direct or via BFS
+                            const pathScore = depthScore[0] * bonus;
+                            // Keep max score across all paths
+                            const existing = scores.get(decisionId) ?? 0;
+                            if (pathScore > existing) {
+                                scores.set(decisionId, pathScore);
+                                paths.set(decisionId, `${scopeEntity.name} → ${relType} → ${neighbor.entity.name}`);
+                            }
+                        }
+                        // Also check if the neighbor's name matches affected_files of any decision
+                        for (const [decisionId, decision] of decisions) {
+                            if (decision.affected_files.includes(neighbor.entity.name) ||
+                                decision.affected_symbols.includes(neighbor.entity.name)) {
+                                const relType = neighbor.relation.type;
+                                const bonus = relationBonus[relType] ?? 0.5;
+                                const pathScore = depthScore[1] * bonus; // 2-hop equivalent
+                                const existing = scores.get(decisionId) ?? 0;
+                                if (pathScore > existing) {
+                                    scores.set(decisionId, pathScore);
+                                    paths.set(decisionId, `${scopeEntity.name} → ${relType} → ${neighbor.entity.name} → decided_by → ${decisionId}`);
+                                }
                             }
                         }
                     }
                 }
-                // Normalize: cap at 1.0, use log scale to avoid domination
-                scores.set(id, connectionCount > 0
-                    ? Math.min(1.0, Math.log2(connectionCount + 1) / 3)
-                    : 0);
+                catch {
+                    // Skip entities that fail to traverse
+                }
+            }
+            // 3. Normalize scores to 0.0-1.0
+            const maxScore = Math.max(0, ...Array.from(scores.values()));
+            if (maxScore > 0 && maxScore !== 1.0) {
+                for (const [id, score] of scores) {
+                    scores.set(id, score / maxScore);
+                }
             }
         }
         catch {
             // Graph errors should never break scoring
         }
-        return scores;
+        return { scores, paths };
     }
     /**
      * Populate related_entities from the knowledge graph.