@shrkcrft/context 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/context-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-builder.d.ts","sourceRoot":"","sources":["../src/context-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACrF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG1D,OAAO,EAAE,qBAAqB,EAAqB,MAAM,2BAA2B,CAAC;AASrF,wBAAgB,YAAY,CAC1B,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,OAAO,EAAE,eAAe,GACvB,cAAc,CAiGhB;AAED,OAAO,EAAE,qBAAqB,EAAE,CAAC"}
+{"version":3,"file":"context-builder.d.ts","sourceRoot":"","sources":["../src/context-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACrF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG1D,OAAO,EAAE,qBAAqB,EAAqB,MAAM,2BAA2B,CAAC;AAcrF,wBAAgB,YAAY,CAC1B,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,OAAO,EAAE,eAAe,GACvB,cAAc,CA4GhB;AAED,OAAO,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/context-builder.js

@@ -38,6 +38,18 @@ export function buildContext(allEntries, request) {
     if (r.includeDocs) {
         sectionPlans.push({ title: 'Reference Docs', priority: 10, entries: buckets.docs });
     }
+    // Agent Actions: aggregate action hints (recommended MCP tools / CLI commands
+    // / forbidden actions / verification commands / human-review points) from
+    // every included entry into ONE composite section. Register it in the SAME
+    // priority-sorted pipeline with a HIGH priority so it survives budget pruning
+    // — it is the most agent-actionable section and was previously appended after
+    // the loop with leftover budget, so it was the first thing dropped.
+    const allIncludedEntries = sectionPlans.flatMap((p) => p.entries);
+    const aggregated = aggregateActionHints(allIncludedEntries);
+    const hintsBody = formatAggregatedHints(aggregated, { level: '###', compact: true });
+    if (hintsBody && hintsBody.length > 0) {
+        sectionPlans.push({ title: 'Agent Actions', priority: 92, entries: [], body: hintsBody });
+    }
     sectionPlans.sort((a, b) => b.priority - a.priority);
     const sections = [];
     const omitted = [];
@@ -65,6 +77,13 @@ export function buildContext(allEntries, request) {
             tryAddSection('Project Overview', r.projectOverview.trim(), []);
             continue;
         }
+        // Composite section with a precomputed body (e.g. Agent Actions) — added in
+        // priority order with its contributing-entry ids.
+        if (plan.body !== undefined) {
+            if (plan.body.length > 0)
+                tryAddSection(plan.title, plan.body, aggregated.contributingEntries);
+            continue;
+        }
         if (plan.entries.length === 0)
             continue;
         const body = formatSectionBody(plan.entries, {
@@ -74,14 +93,6 @@ export function buildContext(allEntries, request) {
         const ids = plan.entries.map((e) => e.id);
         tryAddSection(plan.title, body, ids);
     }
-    // Action hints: aggregate from every included entry and emit a single
-    // composite "Agent Actions" section. Skipped when no entry contributes.
-    const allIncludedEntries = sectionPlans.flatMap((p) => p.entries);
-    const aggregated = aggregateActionHints(allIncludedEntries);
-    const hintsBody = formatAggregatedHints(aggregated, { level: '###', compact: true });
-    if (hintsBody && hintsBody.length > 0) {
-        tryAddSection('Agent Actions', hintsBody, aggregated.contributingEntries);
-    }
     const fullBody = sections
         .map((s) => `## ${s.title}${s.truncated ? ' (truncated)' : ''}\n\n${s.body}`)
         .join('\n\n');
@@ -92,6 +103,7 @@ export function buildContext(allEntries, request) {
         maxTokens,
         omittedSections: omitted,
         body: fullBody,
+        actionHints: aggregated,
     };
 }
 export { formatEntryForContext };

package/dist/context-result.d.ts

@@ -1,3 +1,4 @@
+import type { IAggregatedActionHints } from '@shrkcrft/knowledge';
 import type { IContextSection } from './context-section.js';
 import type { IContextRequest } from './context-request.js';
 export interface IContextResult {
@@ -8,5 +9,13 @@ export interface IContextResult {
     omittedSections: readonly string[];
     /** Combined render of all sections (in order). */
     body: string;
+    /**
+     * Aggregated action hints from every included entry — the same structured
+     * bundle `shrk task` exposes (preferredFlow / forbiddenActions /
+     * verificationCommands / writePolicy / …). Also rendered into `body` as the
+     * "Agent Actions" section, but exposed here so JSON consumers don't have to
+     * parse markdown to recover it.
+     */
+    actionHints: IAggregatedActionHints;
 }
 //# sourceMappingURL=context-result.d.ts.map

package/dist/context-result.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-result.d.ts","sourceRoot":"","sources":["../src/context-result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,eAAe,CAAC;IACzB,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;CACd"}
+{"version":3,"file":"context-result.d.ts","sourceRoot":"","sources":["../src/context-result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,eAAe,CAAC;IACzB,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,WAAW,EAAE,sBAAsB,CAAC;CACrC"}

package/dist/derive-applies-when.d.ts

@@ -0,0 +1,2 @@
+export declare function deriveAppliesWhen(task: string): string[];
+//# sourceMappingURL=derive-applies-when.d.ts.map

package/dist/derive-applies-when.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive-applies-when.d.ts","sourceRoot":"","sources":["../src/derive-applies-when.ts"],"names":[],"mappings":"AAqCA,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAWxD"}

package/dist/derive-applies-when.js

@@ -0,0 +1,51 @@
+/**
+ * Derive `appliesWhen` tokens from a free-text task string.
+ *
+ * `shrk context` ranks knowledge entries via a lexical scorer. Foundational
+ * rules (e.g. `architecture.layer-order`) declare an `appliesWhen` like
+ * `generate-code` but share no surface tokens with a task such as "add a new
+ * plugin command" — so without a derived `appliesWhen` signal they earn no
+ * match reason and are dropped before priority is even considered.
+ *
+ * This maps task verbs/domains to the same canonical `appliesWhen` vocabulary
+ * the inspector task-ranker uses, so the rule that *governs* the work surfaces
+ * even when the wording doesn't overlap. Deterministic; no model in the loop.
+ *
+ * NOTE: the verb/domain vocabulary mirrors
+ * `packages/inspector/src/task-ranker.ts`. The context layer cannot import the
+ * higher inspector layer, so the small map is duplicated here on purpose — keep
+ * the two in sync if either grows.
+ */
+const VERB_APPLIES_WHEN = [
+    {
+        regex: /\b(create|add|implement|generate|new|build|introduce|provide)\b/,
+        appliesWhen: ['generate-code', 'generate-service', 'generate-utility', 'generate-template', 'create-feature'],
+    },
+    { regex: /\b(refactor|rewrite|migrate|extract|rename)\b/, appliesWhen: ['refactor'] },
+    { regex: /\b(test|spec|coverage)\b/, appliesWhen: ['generate-test'] },
+    { regex: /\b(fix|bug|broken|crash)\b/, appliesWhen: ['fix-bug'] },
+    { regex: /\b(review|audit|inspect)\b/, appliesWhen: ['review-pr', 'review-code', 'check-boundaries'] },
+];
+const DOMAIN_APPLIES_WHEN = [
+    { token: 'service', appliesWhen: ['generate-service'] },
+    { token: 'utility', appliesWhen: ['generate-utility'] },
+    { token: 'utilities', appliesWhen: ['generate-utility'] },
+    { token: 'pipeline', appliesWhen: ['create-pipeline'] },
+    { token: 'route', appliesWhen: ['generate-route'] },
+];
+export function deriveAppliesWhen(task) {
+    const text = task.toLowerCase();
+    const out = new Set();
+    for (const v of VERB_APPLIES_WHEN) {
+        if (v.regex.test(text))
+            for (const a of v.appliesWhen)
+                out.add(a);
+    }
+    const tokens = new Set(text.split(/[^a-z0-9]+/).filter((t) => t.length >= 3));
+    for (const d of DOMAIN_APPLIES_WHEN) {
+        if (tokens.has(d.token))
+            for (const a of d.appliesWhen)
+                out.add(a);
+    }
+    return [...out].sort();
+}

package/dist/index.d.ts

@@ -4,5 +4,6 @@ export * from './context-section.js';
 export * from './context-builder.js';
 export * from './token-estimator.js';
 export * from './relevance-selector.js';
+export * from './derive-applies-when.js';
 export * from './ai-context-formatter.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC"}

package/dist/index.js

@@ -4,4 +4,5 @@ export * from "./context-section.js";
 export * from "./context-builder.js";
 export * from "./token-estimator.js";
 export * from "./relevance-selector.js";
+export * from "./derive-applies-when.js";
 export * from "./ai-context-formatter.js";

package/dist/relevance-selector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relevance-selector.d.ts","sourceRoot":"","sources":["../src/relevance-selector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,KAAK,EAAE,eAAe,EAAE,CAAC;CAC1B;AAeD,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,OAAO,EAAE,eAAe,EACxB,eAAe,SAAI,GAClB,eAAe,CAuCjB"}
+{"version":3,"file":"relevance-selector.d.ts","sourceRoot":"","sources":["../src/relevance-selector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG5D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,KAAK,EAAE,eAAe,EAAE,CAAC;CAC1B;AAeD,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,OAAO,EAAE,eAAe,EACxB,eAAe,SAAI,GAClB,eAAe,CAgDjB"}

package/dist/relevance-selector.js

@@ -1,4 +1,5 @@
 import { KnowledgeIndex } from '@shrkcrft/knowledge';
+import { deriveAppliesWhen } from "./derive-applies-when.js";
 const TYPE_BUCKETS = {
     rule: 'rules',
     path: 'paths',
@@ -19,11 +20,19 @@ export function selectRelevantEntries(allEntries, request, limitPerSection = 5)
         scope.push(request.framework);
     if (request.area)
         scope.push(request.area);
+    // Merge any explicit appliesWhen with tokens derived from the task verbs /
+    // domain so foundational rules that key on `appliesWhen` (e.g.
+    // architecture.layer-order on 'generate-code') earn a match reason for a task
+    // whose wording doesn't overlap the rule. Without this they score 0 reasons
+    // and are dropped before priority matters.
+    const appliesWhen = [
+        ...new Set([...(request.appliesWhen ?? []), ...deriveAppliesWhen(request.task)]),
+    ];
     const searchAll = index.search({
         query: request.task,
         scope,
         tags,
-        appliesWhen: request.appliesWhen,
+        appliesWhen,
     });
     const buckets = {
         rules: [],

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@shrkcrft/context",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.21",
   "description": "SharkCraft AI context builder: token-budgeted relevance retrieval for tasks.",
   "license": "MIT",
   "author": "SharkCraft contributors",
   "type": "module",
   "main": "./dist/index.js",
-  "types": "./dist/index.d.d.ts",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -44,11 +44,11 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.2",
-    "@shrkcrft/knowledge": "^0.1.0-alpha.2",
-    "@shrkcrft/rules": "^0.1.0-alpha.2",
-    "@shrkcrft/paths": "^0.1.0-alpha.2",
-    "@shrkcrft/templates": "^0.1.0-alpha.2"
+    "@shrkcrft/core": "^0.1.0-alpha.21",
+    "@shrkcrft/knowledge": "^0.1.0-alpha.21",
+    "@shrkcrft/rules": "^0.1.0-alpha.21",
+    "@shrkcrft/paths": "^0.1.0-alpha.21",
+    "@shrkcrft/templates": "^0.1.0-alpha.21"
   },
   "publishConfig": {
     "access": "public"