@shrkcrft/context 0.1.0-alpha.22 → 0.1.0-alpha.23

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;AAcrF,wBAAgB,YAAY,CAC1B,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,OAAO,EAAE,eAAe,GACvB,cAAc,CA4GhB;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,CA0IhB;AAED,OAAO,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/context-builder.js

@@ -21,7 +21,13 @@ export function buildContext(allEntries, request) {
     if (r.includeRules) {
         sectionPlans.push({ title: 'Relevant Rules', priority: 90, entries: buckets.rules });
     }
+    // Architecture Decisions rank just above the constraints they justify — a
+    // Decision entry whose appliesWhen matches the task is high-signal context an
+    // agent must not silently lose (previously these were dropped unless
+    // --include-docs was set, then only in the lowest "Reference Docs" bucket).
+    sectionPlans.push({ title: 'Architecture Decisions', priority: 82, entries: buckets.decisions });
     sectionPlans.push({ title: 'Architecture Constraints', priority: 80, entries: buckets.architecture });
+    sectionPlans.push({ title: 'Conventions', priority: 75, entries: buckets.conventions });
     if (r.includePaths) {
         sectionPlans.push({ title: 'Relevant Path Conventions', priority: 70, entries: buckets.paths });
     }
@@ -31,10 +37,17 @@ export function buildContext(allEntries, request) {
     sectionPlans.push({ title: 'Technical Stack', priority: 50, entries: buckets.technical });
     sectionPlans.push({ title: 'Testing Guidelines', priority: 45, entries: buckets.testing });
     sectionPlans.push({ title: 'Security Guidelines', priority: 44, entries: buckets.security });
+    sectionPlans.push({ title: 'Workflows', priority: 42, entries: buckets.workflows });
     if (r.includeCommands) {
         sectionPlans.push({ title: 'Commands', priority: 40, entries: buckets.commands });
     }
     sectionPlans.push({ title: 'Current Tasks', priority: 30, entries: buckets.tasks });
+    // Default "Project Knowledge" — the misc high-signal types. On by default;
+    // suppress with includeKnowledge:false. Distinct from --include-docs, which
+    // only ADDS the lowest-value overflow below.
+    if (r.includeKnowledge !== false) {
+        sectionPlans.push({ title: 'Project Knowledge', priority: 25, entries: buckets.knowledge });
+    }
     if (r.includeDocs) {
         sectionPlans.push({ title: 'Reference Docs', priority: 10, entries: buckets.docs });
     }
@@ -54,34 +67,44 @@ export function buildContext(allEntries, request) {
     const sections = [];
     const omitted = [];
     let used = 0;
-    function tryAddSection(title, body, entryIds) {
+    // Sections at/above this priority degrade by TRUNCATION rather than vanishing
+    // when they don't fit. Plans are processed in descending priority order, so
+    // the current plan is always the highest-priority one still unplaced; a big
+    // critical section (e.g. Agent Actions, 92) must not be dropped whole while a
+    // small low-priority section is kept. Below the threshold, a non-fitting
+    // section is omitted (and a later, smaller one may still fit).
+    const PRUNE_PROTECT_PRIORITY = 80;
+    function tryAddSection(title, body, entryIds, priority) {
         const tokens = estimateTokens(body);
-        if (used + tokens > maxTokens && sections.length > 0) {
-            omitted.push(title);
+        if (used + tokens <= maxTokens) {
+            sections.push({ title, body, entryIds, tokens });
+            used += tokens;
             return;
         }
-        if (used + tokens > maxTokens) {
-            // Still emit, but mark truncated.
-            const ratio = (maxTokens - used) / tokens;
+        const remaining = maxTokens - used;
+        // Truncate-to-fit when this is the first section (nothing emitted yet) or a
+        // protected high-priority one — provided there is any budget left.
+        if (remaining > 0 && (sections.length === 0 || priority >= PRUNE_PROTECT_PRIORITY)) {
+            const ratio = remaining / tokens;
             const truncatedBody = body.slice(0, Math.max(0, Math.floor(body.length * ratio))) + '\n…[truncated]';
             const truncTokens = estimateTokens(truncatedBody);
             sections.push({ title, body: truncatedBody, entryIds, tokens: truncTokens, truncated: true });
             used += truncTokens;
             return;
         }
-        sections.push({ title, body, entryIds, tokens });
-        used += tokens;
+        omitted.push(title);
     }
     for (const plan of sectionPlans) {
         if (plan.title === 'Project Overview' && r.projectOverview) {
-            tryAddSection('Project Overview', r.projectOverview.trim(), []);
+            tryAddSection('Project Overview', r.projectOverview.trim(), [], plan.priority);
             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);
+            if (plan.body.length > 0) {
+                tryAddSection(plan.title, plan.body, aggregated.contributingEntries, plan.priority);
+            }
             continue;
         }
         if (plan.entries.length === 0)
@@ -91,7 +114,7 @@ export function buildContext(allEntries, request) {
             maxContentChars: 1500,
         });
         const ids = plan.entries.map((e) => e.id);
-        tryAddSection(plan.title, body, ids);
+        tryAddSection(plan.title, body, ids, plan.priority);
     }
     const fullBody = sections
         .map((s) => `## ${s.title}${s.truncated ? ' (truncated)' : ''}\n\n${s.body}`)

package/dist/context-request.d.ts

@@ -11,10 +11,27 @@ export interface IContextRequest {
     includeRules?: boolean;
     includePaths?: boolean;
     includeDocs?: boolean;
+    /**
+     * Emit the default "Project Knowledge" section for genuinely-misc high-signal
+     * types (feature / business / decision-adjacent / …). Defaults to `true`; set
+     * `false` to suppress that section without losing the dedicated ones.
+     */
+    includeKnowledge?: boolean;
     includeOverview?: boolean;
     includeWarnings?: boolean;
     includeCommands?: boolean;
     projectOverview?: string;
+    /**
+     * Optional per-entry score boost (e.g. pack search-tuning). Applied as a
+     * stable re-rank of the relevance results so a boosted entry can cross the
+     * per-section cap. Returns a delta (0 = no boost). Kept as a plain structural
+     * callback so the context layer needs no dependency on the inspector.
+     */
+    boostFor?: (entry: {
+        readonly id: string;
+        readonly type?: unknown;
+        readonly tags?: readonly string[];
+    }) => number;
 }
-export declare const DEFAULT_CONTEXT_REQUEST: Required<Pick<IContextRequest, 'maxTokens' | 'includeExamples' | 'includeTemplates' | 'includeRules' | 'includePaths' | 'includeDocs' | 'includeOverview' | 'includeWarnings' | 'includeCommands'>>;
+export declare const DEFAULT_CONTEXT_REQUEST: Required<Pick<IContextRequest, 'maxTokens' | 'includeExamples' | 'includeTemplates' | 'includeRules' | 'includePaths' | 'includeDocs' | 'includeKnowledge' | 'includeOverview' | 'includeWarnings' | 'includeCommands'>>;
 //# sourceMappingURL=context-request.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"context-request.d.ts","sourceRoot":"","sources":["../src/context-request.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAC5C,IAAI,CACF,eAAe,EACb,WAAW,GACX,iBAAiB,GACjB,kBAAkB,GAClB,cAAc,GACd,cAAc,GACd,aAAa,GACb,iBAAiB,GACjB,iBAAiB,GACjB,iBAAiB,CACpB,CAWF,CAAC"}
+{"version":3,"file":"context-request.d.ts","sourceRoot":"","sources":["../src/context-request.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,KAAK,MAAM,CAAC;CACnH;AAED,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAC5C,IAAI,CACF,eAAe,EACb,WAAW,GACX,iBAAiB,GACjB,kBAAkB,GAClB,cAAc,GACd,cAAc,GACd,aAAa,GACb,kBAAkB,GAClB,iBAAiB,GACjB,iBAAiB,GACjB,iBAAiB,CACpB,CAYF,CAAC"}

package/dist/context-request.js

@@ -5,6 +5,7 @@ export const DEFAULT_CONTEXT_REQUEST = {
     includeRules: true,
     includePaths: true,
     includeDocs: false,
+    includeKnowledge: true,
     includeOverview: true,
     includeWarnings: true,
     includeCommands: false,

package/dist/relevance-selector.d.ts

@@ -5,11 +5,21 @@ export interface SelectedEntries {
     paths: IKnowledgeEntry[];
     templates: IKnowledgeEntry[];
     architecture: IKnowledgeEntry[];
+    decisions: IKnowledgeEntry[];
+    conventions: IKnowledgeEntry[];
     technical: IKnowledgeEntry[];
     warnings: IKnowledgeEntry[];
     commands: IKnowledgeEntry[];
+    workflows: IKnowledgeEntry[];
     testing: IKnowledgeEntry[];
     security: IKnowledgeEntry[];
+    /**
+     * Genuinely-misc high-signal types that don't map to a dedicated section
+     * (feature / business / environment / dependency / deployment / integration /
+     * custom / …). Surfaced by default in the "Project Knowledge" section — these
+     * used to be dropped entirely unless `--include-docs` was set.
+     */
+    knowledge: IKnowledgeEntry[];
     docs: IKnowledgeEntry[];
     tasks: IKnowledgeEntry[];
 }

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;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"}
+{"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,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B;;;;;OAKG;IACH,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,KAAK,EAAE,eAAe,EAAE,CAAC;CAC1B;AAkBD,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,OAAO,EAAE,eAAe,EACxB,eAAe,SAAI,GAClB,eAAe,CA0EjB"}

package/dist/relevance-selector.js

@@ -5,9 +5,12 @@ const TYPE_BUCKETS = {
     path: 'paths',
     template: 'templates',
     architecture: 'architecture',
+    decision: 'decisions',
+    convention: 'conventions',
     technical: 'technical',
     warning: 'warnings',
     command: 'commands',
+    workflow: 'workflows',
     testing: 'testing',
     security: 'security',
     task: 'tasks',
@@ -34,29 +37,53 @@ export function selectRelevantEntries(allEntries, request, limitPerSection = 5)
         tags,
         appliesWhen,
     });
+    // Pack search-tuning boost: stable-sort so boosted entries (delta > 0) bubble
+    // ahead of unboosted ones (delta = 0) while preserving the relevance order
+    // among equal boosts. Lets a boosted rule/knowledge entry cross the
+    // per-section cap, mirroring how the task ranker applies the same tuning.
+    const boostFor = request.boostFor;
+    const ranked = boostFor
+        ? [...searchAll].sort((a, b) => {
+            const sa = a.score + (boostFor(a.entry) ?? 0);
+            const sb = b.score + (boostFor(b.entry) ?? 0);
+            return sb - sa || a.entry.id.localeCompare(b.entry.id);
+        })
+        : searchAll;
     const buckets = {
         rules: [],
         paths: [],
         templates: [],
         architecture: [],
+        decisions: [],
+        conventions: [],
         technical: [],
         warnings: [],
         commands: [],
+        workflows: [],
         testing: [],
         security: [],
+        knowledge: [],
         docs: [],
         tasks: [],
     };
-    for (const r of searchAll) {
+    for (const r of ranked) {
         const typeKey = String(r.entry.type).toLowerCase();
         const bucketKey = TYPE_BUCKETS[typeKey];
         if (bucketKey) {
             if (buckets[bucketKey].length < limitPerSection)
                 buckets[bucketKey].push(r.entry);
+            continue;
         }
-        else if (request.includeDocs) {
-            if (buckets.docs.length < limitPerSection)
-                buckets.docs.push(r.entry);
+        // Unmapped type. Route to the default "Project Knowledge" bucket so a
+        // high-signal entry (e.g. a Decision/Feature whose appliesWhen matches the
+        // task) reaches the agent by default. `--include-docs` only ADDS the
+        // lowest-value overflow into "Reference Docs" — it no longer gates ALL
+        // unmapped types behind an off-by-default flag.
+        if (buckets.knowledge.length < limitPerSection) {
+            buckets.knowledge.push(r.entry);
+        }
+        else if (request.includeDocs && buckets.docs.length < limitPerSection) {
+            buckets.docs.push(r.entry);
         }
     }
     return buckets;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/context",
-  "version": "0.1.0-alpha.22",
+  "version": "0.1.0-alpha.23",
   "description": "SharkCraft AI context builder: token-budgeted relevance retrieval for tasks.",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -44,11 +44,11 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.22",
-    "@shrkcrft/knowledge": "^0.1.0-alpha.22",
-    "@shrkcrft/rules": "^0.1.0-alpha.22",
-    "@shrkcrft/paths": "^0.1.0-alpha.22",
-    "@shrkcrft/templates": "^0.1.0-alpha.22"
+    "@shrkcrft/core": "^0.1.0-alpha.23",
+    "@shrkcrft/knowledge": "^0.1.0-alpha.23",
+    "@shrkcrft/rules": "^0.1.0-alpha.23",
+    "@shrkcrft/paths": "^0.1.0-alpha.23",
+    "@shrkcrft/templates": "^0.1.0-alpha.23"
   },
   "publishConfig": {
     "access": "public"