@gmickel/gno 1.22.0 → 1.23.0

package/README.md

@@ -17,6 +17,17 @@
 
 GNO is a local knowledge engine for notes, code, PDFs, Office docs, meeting transcripts, and reference material. It gives you fast keyword search, semantic retrieval, grounded answers with citations, wiki-style linking, and a real workspace UI, while keeping the whole stack local by default.
 
+CLI retrieval also uses the current repository/workspace as a transparent soft
+ranking signal. A trusted local cwd or repeatable `--project-root` can add at
+most `+0.03` to matching collection results; `--no-project-affinity` disables
+it, and explicit roots replace cwd inference. It never overrides collection,
+tag, date, exclude, or egress filters. SDK, REST, and MCP `projectHints` are
+opaque, untrusted, limited to 16, and intentionally have zero ranking effect:
+those surfaces never probe caller or server filesystem paths. Trusted local
+diagnose output uses closed `schemaVersion: "1.1"` redacted affinity metadata;
+absent, disabled, and remote/untrusted diagnose requests preserve exact legacy
+v1.0 bytes and omit `affinity`.
+
 Use it when:
 
 - your notes live in more than one folder
@@ -94,12 +105,16 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
 
 <!-- public-truth:current-version -->
 
-> Current release: **v1.22.0** — see [CHANGELOG.md](./CHANGELOG.md)
+> Current release: **v1.23.0** — see [CHANGELOG.md](./CHANGELOG.md)
 
 <!-- /public-truth -->
 
 > Full release history: [CHANGELOG.md](./CHANGELOG.md)
 
+- **Project-aware retrieval affinity**: trusted local CLI searches can use the
+  current workspace or explicit `--project-root` values as a transparent,
+  explainable `+0.03` soft ranking signal. Filters remain hard, and untrusted
+  SDK, REST, MCP, and Web hints never probe paths or affect ranking.
 - **Retrieval-proven activation**: `gno status`, `gno doctor`, REST, and the
   Web/Desktop dashboard now share a per-folder lexical retrieval proof. Local
   semantic readiness remains independent, and installed MCP targets can run an

package/assets/skill/SKILL.md

@@ -108,8 +108,23 @@ Recipe rules:
 --json                JSON output
 --files               URI list output
 --line-numbers        Include line numbers
+--project-root <path> Trusted local root; repeatable and replaces cwd affinity
+--no-project-affinity Disable trusted local project-aware ranking
 ```
 
+CLI searches use the current repository/worktree as a soft signal by default.
+A matching collection can receive at most `+0.03`; roots never stack, all
+auxiliary signals share `±0.08`, and collection/tag/date/exclude/egress filters
+stay hard. Use `--project-root` for explicit trusted roots or
+`--no-project-affinity` to disable it.
+
+Do not treat MCP/SDK/REST `projectHints` as paths. They are opaque, untrusted,
+limited to 16, never trigger filesystem probing, and currently produce zero
+affinity. Explain uses redacted aliases only. Diagnose preserves exact closed
+v1.0 bytes and omits `affinity` for absent, disabled, and remote/untrusted
+inputs; trusted local diagnose uses closed v1.1 redacted metadata, including an
+explicit unmatched state. The Web UI does not infer a browser project root.
+
 ## Advanced: Structured Query Modes (query/ask only)
 
 Use `--query-mode` to combine multiple retrieval strategies in one query (repeatable):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",

package/spec/cli.md

@@ -749,22 +749,24 @@ gno search <query> [-n <num>] [--min-score <num>] [-c <collection>] [--since <da
 
 **Options:**
 
-| Option             | Type    | Default                   | Description                                                                                   |
-| ------------------ | ------- | ------------------------- | --------------------------------------------------------------------------------------------- |
-| `-n`               | integer | 5 (20 for --json/--files) | Max results                                                                                   |
-| `--min-score`      | number  | 0                         | Minimum score threshold                                                                       |
-| `-c, --collection` | string  | all                       | Filter to collection                                                                          |
-| `--since`          | string  | none                      | Modified-at lower bound (ISO date/time or relative token)                                     |
-| `--until`          | string  | none                      | Modified-at upper bound (ISO date/time or relative token)                                     |
-| `--category`       | string  | none                      | Filter to docs with matching category/content type (comma-separated)                          |
-| `--author`         | string  | none                      | Filter to docs where author contains value (case-insensitive)                                 |
-| `--intent`         | string  | none                      | Disambiguating context for ambiguous queries; steers snippets without being searched directly |
-| `--exclude`        | string  | none                      | Hard-prune docs containing any comma-separated term in title/path/body                        |
-| `--tags-all`       | string  | none                      | Filter to docs with ALL tags (comma-separated)                                                |
-| `--tags-any`       | string  | none                      | Filter to docs with ANY tag (comma-separated)                                                 |
-| `--full`           | boolean | false                     | Include full mirror content instead of snippet                                                |
-| `--line-numbers`   | boolean | false                     | Include line numbers in output                                                                |
-| `--lang`           | string  | auto                      | Language filter/hint (BCP-47)                                                                 |
+| Option                  | Type     | Default                   | Description                                                                                   |
+| ----------------------- | -------- | ------------------------- | --------------------------------------------------------------------------------------------- |
+| `-n`                    | integer  | 5 (20 for --json/--files) | Max results                                                                                   |
+| `--min-score`           | number   | 0                         | Minimum score threshold                                                                       |
+| `-c, --collection`      | string   | all                       | Filter to collection                                                                          |
+| `--since`               | string   | none                      | Modified-at lower bound (ISO date/time or relative token)                                     |
+| `--until`               | string   | none                      | Modified-at upper bound (ISO date/time or relative token)                                     |
+| `--category`            | string   | none                      | Filter to docs with matching category/content type (comma-separated)                          |
+| `--author`              | string   | none                      | Filter to docs where author contains value (case-insensitive)                                 |
+| `--intent`              | string   | none                      | Disambiguating context for ambiguous queries; steers snippets without being searched directly |
+| `--exclude`             | string   | none                      | Hard-prune docs containing any comma-separated term in title/path/body                        |
+| `--tags-all`            | string   | none                      | Filter to docs with ALL tags (comma-separated)                                                |
+| `--tags-any`            | string   | none                      | Filter to docs with ANY tag (comma-separated)                                                 |
+| `--project-root`        | string[] | cwd                       | Trusted project root; repeatable, replaces default cwd/repository affinity                    |
+| `--no-project-affinity` | boolean  | false                     | Disable project-aware soft ranking; invalid with `--project-root`                             |
+| `--full`                | boolean  | false                     | Include full mirror content instead of snippet                                                |
+| `--line-numbers`        | boolean  | false                     | Include line numbers in output                                                                |
+| `--lang`                | string   | auto                      | Language filter/hint (BCP-47)                                                                 |
 
 **Scoring:**
 
@@ -824,7 +826,8 @@ Vector semantic search over indexed documents.
 gno vsearch <query> [-n <num>] [--min-score <num>] [-c <collection>] [--since <date>] [--until <date>] [--category <values>] [--author <text>] [--intent <text>] [--exclude <values>] [--tags-all <tags>] [--tags-any <tags>] [--full] [--line-numbers] [--lang <bcp47>] [--json|--files|--csv|--md|--xml]
 ```
 
-**Options:** Same as `gno search` (including temporal/category/author and tag filters)
+**Options:** Same as `gno search` (including temporal/category/author, tag, and
+project-affinity controls).
 
 **Scoring:**
 
@@ -870,6 +873,9 @@ gno query diagnose <query> --target <doc> [-n <num>] [--min-score <num>] [-c <co
 | `--explain` | boolean | Print retrieval explanation to stderr |
 | `--target` | ref | Required for `query diagnose`; target document to diagnose |
 
+`query diagnose` accepts the same `--project-root` and
+`--no-project-affinity` controls as `query`.
+
 **Compatibility / Migration:**
 
 - Legacy query invocations remain valid (`gno query "<text>"`, `--fast`, `--thorough`, `--no-expand`, `--no-rerank`).
@@ -882,8 +888,12 @@ gno query diagnose <query> --target <doc> [-n <num>] [--min-score <num>] [-c <co
 **Diagnose Output:**
 
 `gno query diagnose` wraps the shared `diagnoseQueryTarget()` core and emits
-`query-diagnose.schema.json` for `--json`. The payload requires
-`schemaVersion: "1.0"`, resolves the target first, reports `target.status`
+`query-diagnose.schema.json` for `--json`. No trusted affinity input preserves
+the exact closed `schemaVersion: "1.0"` payload and omits `affinity`; the legacy
+contract remains in `query-diagnose-v1.schema.json`. A resolved trusted CLI cwd
+or explicit project root emits `schemaVersion: "1.1"` and requires closed,
+redacted `affinity` metadata, including unmatched state. The payload resolves
+the target first, reports `target.status`
 (`not_found|inactive|no_indexed_content|filtered_out|diagnosed`), and only runs
 stage tracing for `diagnosed` targets. Stages report
 `present`, `rank`, `score`, `survived`, `dropReason`, `status`, and
@@ -992,6 +1002,8 @@ gno ask <query> [-n <num>] [-c <collection>] [--lang <bcp47>] [--since <date>] [
 | `--no-expand`             | boolean  | false   | Disable query expansion                                                            |
 | `--no-rerank`             | boolean  | false   | Disable cross-encoder reranking                                                    |
 | `--show-sources`          | boolean  | false   | Show all retrieved sources (not just cited)                                        |
+| `--project-root`          | string[] | cwd     | Trusted project root; repeatable, replaces default cwd/repository affinity         |
+| `--no-project-affinity`   | boolean  | false   | Disable project-aware soft ranking; invalid with `--project-root`                  |
 
 **Output (JSON):**
 See [Output Schemas](./output-schemas/ask.schema.json)
@@ -1315,7 +1327,7 @@ written to stderr.
 **Synopsis:**
 
 ```bash
-gno context build "<goal>" --budget <tokens> [--collection <name>] [--fast|--thorough] [--json|--md] [--output <file>]
+gno context build "<goal>" --budget <tokens> [--collection <name>] [--project-root <path>]... [--no-project-affinity] [--fast|--thorough] [--json|--md] [--output <file>]
 ```
 
 `--budget` is the global token ceiling. `--bytes` optionally sets a separate
@@ -1328,6 +1340,10 @@ repeatable. Tag filters are NFC-normalized, lowercased, deduplicated, and
 validated before retrieval. Result and candidate limits are global across
 repeated collections: the merged result pool is capped once, while candidate
 work is distributed deterministically in canonical collection order.
+Project affinity defaults to the trusted process cwd/repository. Repeatable
+`--project-root` values replace that default, are normalized/deduplicated, and
+are capped at 16. `--no-project-affinity` disables the soft signal and cannot
+be combined with explicit roots.
 
 JSON is the canonical V1 payload. Markdown is a readable projection of that
 same payload and hard-delimits each untrusted evidence passage. Passage,

package/spec/evals-agentic.md

@@ -22,6 +22,10 @@ evals/agentic/
   fixture-db.ts
   scoring.ts
   promotion.ts
+  project-affinity-contract.ts
+  project-affinity-outcome.ts
+  project-affinity-promotion.ts
+  project-affinity-runtime.ts
   verified-ask-outcome.ts
   verified-ask-promotion.ts
   demos/context-capsule.ts
@@ -68,6 +72,37 @@ evals/fixtures/agentic-retrieval/
     context-capsule.md
 ```
 
+## Separate project-affinity promotion
+
+`project-affinity-cases.json` defines two controlled vector-distance pairs over
+the existing `t456ef70` (`c015`/`c115`) and `t567f081`
+(`c016`/`c116`) task/corpus/oracle identities. The separate closed
+`project-affinity-promotion@1.0` artifact hash-binds those manifest identities;
+it does not add tasks to the authoritative 24-task, 144-receipt matrix or
+change `BenchmarkReport@1`.
+
+The target collection starts `0.02` behind, then receives one trusted local
+`+0.03` contribution. Promotion requires correct top-1 to strictly improve to
+`2/2`, exact required evidence to remain retained, zero URI-rank/required
+evidence-coverage loss across all 24 hard-collection tasks, and zero loss for
+`t012ab3c`, `t123bc4d`, `te8f901a`, and `tf901a2b`. It also gates hard-filter
+isolation, absent/disabled/unavailable/untrusted exact zero lanes, shared
+auxiliary cap receipts, and structural store-call/candidate bounds. Structural
+receipts record the complete closed StorePort method map, reject unexpected
+methods, enforce per-method maxima, require candidate requests and returns to
+stay within `3×` the output limit, and require returned candidates not to exceed
+requested candidates. Latency is not a gate.
+
+The committed artifacts are
+`baseline/fixture-agent/project-affinity-promotion.json` and `.md`. They contain
+only GNO evidence URIs, hashes, scores, raw filter/regression/zero/auxiliary/
+structural receipts, implementation provenance, and redacted aliases—never
+temporary roots, raw project hints, or absolute paths. An independent validator
+rebinds fixture identities, recomputes summaries/gates/fingerprint from those
+receipts, and compares the committed artifact with a fresh deterministic
+production run. The controlled synthetic lane isolates the score seam and makes
+no general workload superiority claim.
+
 The first fixture version contains 24 original synthetic tasks and 34 Markdown
 documents under the MIT license. It covers exact identifiers, ambiguity,
 multi-document comparisons, meeting decisions, temporal questions, typed

package/spec/evals.md

@@ -27,6 +27,12 @@ Agent-level evidence sufficiency, exact citation coverage, stopping behavior,
 and Context Capsule promotion use the separate deterministic
 [Agentic Retrieval Evaluation Contract](evals-agentic.md).
 
+That contract also owns a separate closed project-affinity promotion artifact.
+It reuses the immutable 24-task fixture identities while leaving the main task
+inventory and report schema unchanged. The gate records measured top-1,
+evidence, multilingual, hard-filter, zero-lane, score-cap, and structural-call
+outcomes; it does not use a wall-clock threshold.
+
 ## Dependencies
 
 ```json

package/spec/mcp.md

@@ -218,6 +218,10 @@ Optional fields are `collection`, `limit` (default 5), `minScore`, `lang`,
 `since`, `until`, `categories`, `author`, `graph`, `noGraph`, `noRerank`,
 `maxAnswerTokens`, `contextBudgetTokens`, and `contextBudgetBytes`. Input
 objects are closed.
+`projectHints` is an optional array of at most 16 non-empty caller hints. Hints
+are normalized and deduplicated as opaque values, never resolved against or
+reflected from the MCP server filesystem, and therefore have zero ranking
+effect on the remote channel.
 
 `structuredContent` uses the
 [`ask`](./output-schemas/ask.schema.json) contract. Its `verification` object
@@ -273,6 +277,9 @@ validated before retrieval. `limit` and `candidateLimit` are global across all
 requested collections: result admission is capped after merging, and
 rerank/graph candidate work is distributed deterministically in canonical
 collection order.
+`projectHints` is also accepted as an optional array of at most 16 opaque
+caller hints. It follows the same remote zero-affinity, non-probing, and
+non-reflection contract as all MCP retrieval tools.
 
 `structuredContent` is the complete canonical Context Capsule object for
 application clients. Model-visible text is always one deterministic
@@ -338,6 +345,13 @@ evidence reads. `structuredContent` is the canonical verification receipt.
 
 BM25 keyword search over indexed documents.
 
+All retrieval input schemas (`gno_search`, `gno_vsearch`, `gno_query`, and
+`gno_query_diagnose`) additionally accept optional `projectHints: string[]`
+(maximum 16). Values are trimmed, NFC-normalized, deduplicated, and treated as
+opaque remote hints. The server never stats, realpaths, discovers repositories,
+or infers its cwd from them; remote hints produce redacted zero-affinity
+metadata and no ranking change.
+
 **Input Schema:**
 
 ```json
@@ -745,6 +759,10 @@ Structured content includes `schemaVersion`, normalized `query`, `target`
 metadata/status (`not_found`, `inactive`, `no_indexed_content`,
 `filtered_out`, or `diagnosed`), `stages` for BM25/vector/fusion/graph/rerank,
 the selected target `chunk`, and retrieval `meta`.
+MCP inputs are remote and untrusted, so this tool preserves exact v1.0 bytes
+and omits `affinity`, even when `projectHints` are supplied. The shared current
+validation schema is `gno://schemas/query-diagnose@1.1`; its affinity-bearing
+v1.1 branch is reserved for trusted local CLI diagnose requests.
 
 Use when an expected target is missing from `gno_query`, when filters may have
 excluded it, or when an agent needs evidence before raising `candidateLimit`,

package/spec/output-schemas/query-diagnose-v1.schema.json

@@ -0,0 +1,123 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/query-diagnose@1.0",
+  "title": "GNO Query Diagnose",
+  "type": "object",
+  "required": ["schemaVersion", "query", "target", "stages", "chunk", "meta"],
+  "properties": {
+    "schemaVersion": { "type": "string", "const": "1.0" },
+    "query": { "type": "string" },
+    "target": {
+      "type": "object",
+      "required": [
+        "ref",
+        "status",
+        "docid",
+        "uri",
+        "title",
+        "contentType",
+        "contentTypeSource",
+        "categories",
+        "graphHints",
+        "contentTypeRulesFingerprint",
+        "contentTypeFingerprintMatches",
+        "mirrorHash",
+        "chunkCount",
+        "filterReasons"
+      ],
+      "properties": {
+        "ref": { "type": "string" },
+        "status": {
+          "type": "string",
+          "enum": [
+            "not_found",
+            "inactive",
+            "no_indexed_content",
+            "filtered_out",
+            "diagnosed"
+          ]
+        },
+        "docid": { "type": ["string", "null"], "pattern": "^#[a-f0-9]{6,}$" },
+        "uri": { "type": ["string", "null"], "format": "uri" },
+        "title": { "type": ["string", "null"] },
+        "contentType": { "type": ["string", "null"] },
+        "contentTypeSource": { "type": ["string", "null"] },
+        "categories": { "type": "array", "items": { "type": "string" } },
+        "graphHints": { "type": "array", "items": { "type": "string" } },
+        "contentTypeRulesFingerprint": { "type": ["string", "null"] },
+        "contentTypeFingerprintMatches": { "type": ["boolean", "null"] },
+        "mirrorHash": { "type": ["string", "null"] },
+        "chunkCount": { "type": "integer", "minimum": 0 },
+        "filterReasons": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "stages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "status",
+          "sourceCount",
+          "present",
+          "rank",
+          "score",
+          "survived",
+          "dropReason"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "enum": ["bm25", "vector", "fusion", "graph", "rerank"]
+          },
+          "status": { "type": "string", "enum": ["active", "skipped"] },
+          "sourceCount": { "type": "integer", "minimum": 0 },
+          "present": { "type": "boolean" },
+          "rank": { "type": ["integer", "null"], "minimum": 1 },
+          "score": { "type": ["number", "null"] },
+          "survived": { "type": "boolean" },
+          "dropReason": {
+            "type": ["string", "null"],
+            "enum": ["not_in_candidate_set", "below_cutoff", "skipped", null]
+          },
+          "reason": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "chunk": {
+      "type": "object",
+      "required": ["seq", "startLine", "endLine", "language"],
+      "properties": {
+        "seq": { "type": ["integer", "null"], "minimum": 0 },
+        "startLine": { "type": ["integer", "null"], "minimum": 1 },
+        "endLine": { "type": ["integer", "null"], "minimum": 1 },
+        "language": { "type": ["string", "null"] }
+      },
+      "additionalProperties": false
+    },
+    "meta": {
+      "type": "object",
+      "required": ["mode", "vectorsUsed", "reranked", "totalResults"],
+      "properties": {
+        "mode": { "type": "string", "enum": ["bm25_only", "hybrid"] },
+        "vectorsUsed": { "type": "boolean" },
+        "reranked": { "type": "boolean" },
+        "totalResults": { "type": "integer", "minimum": 0 },
+        "queryModes": {
+          "type": "object",
+          "required": ["term", "intent", "hyde"],
+          "properties": {
+            "term": { "type": "integer", "minimum": 0 },
+            "intent": { "type": "integer", "minimum": 0 },
+            "hyde": { "type": "boolean" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/spec/output-schemas/query-diagnose.schema.json

@@ -1,11 +1,11 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "gno://schemas/query-diagnose@1.0",
+  "$id": "gno://schemas/query-diagnose@1.1",
   "title": "GNO Query Diagnose",
   "type": "object",
   "required": ["schemaVersion", "query", "target", "stages", "chunk", "meta"],
   "properties": {
-    "schemaVersion": { "type": "string", "const": "1.0" },
+    "schemaVersion": { "type": "string", "enum": ["1.0", "1.1"] },
     "query": { "type": "string" },
     "target": {
       "type": "object",
@@ -86,6 +86,74 @@
         "additionalProperties": false
       }
     },
+    "affinity": {
+      "type": "object",
+      "required": [
+        "affinityAdjustedScore",
+        "affinityApplied",
+        "affinityRequested",
+        "affinityWeight",
+        "baseScore",
+        "collectionAlias",
+        "combinedAuxiliaryApplied",
+        "combinedAuxiliaryCap",
+        "combinedAuxiliaryRequested",
+        "finalBlendedScore",
+        "finalScore",
+        "matched",
+        "rawScore",
+        "rawScoreKind",
+        "rootAlias",
+        "source"
+      ],
+      "properties": {
+        "affinityAdjustedScore": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "affinityApplied": { "type": "number" },
+        "affinityRequested": { "type": "number" },
+        "affinityWeight": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 0.03
+        },
+        "baseScore": { "type": "number", "minimum": 0, "maximum": 1 },
+        "collectionAlias": {
+          "type": ["string", "null"],
+          "pattern": "^collection_[a-f0-9]{12}$"
+        },
+        "combinedAuxiliaryApplied": {
+          "type": "number",
+          "minimum": -0.08,
+          "maximum": 0.08
+        },
+        "combinedAuxiliaryCap": { "type": "number", "const": 0.08 },
+        "combinedAuxiliaryRequested": { "type": "number" },
+        "finalBlendedScore": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "finalScore": { "type": "number", "minimum": 0, "maximum": 1 },
+        "matched": { "type": "boolean" },
+        "rawScore": { "type": "number" },
+        "rawScoreKind": {
+          "type": "string",
+          "enum": ["bm25", "hybrid_blended", "normalized", "vector_distance"]
+        },
+        "rootAlias": {
+          "type": ["string", "null"],
+          "pattern": "^root_[a-f0-9]{12}$"
+        },
+        "source": {
+          "type": ["string", "null"],
+          "enum": ["cli_cwd", "cli_explicit", "cli_worktree", null]
+        }
+      },
+      "additionalProperties": false
+    },
     "chunk": {
       "type": "object",
       "required": ["seq", "startLine", "endLine", "language"],
@@ -119,5 +187,24 @@
       "additionalProperties": false
     }
   },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "schemaVersion": { "const": "1.0" } },
+        "required": ["schemaVersion"]
+      },
+      "then": { "properties": { "affinity": false } }
+    },
+    {
+      "if": {
+        "properties": { "schemaVersion": { "const": "1.1" } },
+        "required": ["schemaVersion"]
+      },
+      "then": {
+        "properties": { "affinity": {} },
+        "required": ["affinity"]
+      }
+    }
+  ],
   "additionalProperties": false
 }

package/src/app/context-runtime-types.ts

@@ -4,6 +4,7 @@ import type { ContextEvidenceCompilerDeps } from "../core/context-evidence";
 import type { ContextVerifierDeps } from "../core/context-verifier";
 import type { RetrievalTraceSession } from "../core/retrieval-trace-session";
 import type { EmbeddingPort, RerankPort } from "../llm/types";
+import type { ProjectAffinityScoringInput } from "../pipeline/project-affinity";
 import type { QueryModeInput } from "../pipeline/types";
 import type { StorePort } from "../store/types";
 import type { VectorIndexPort } from "../store/vector";
@@ -50,6 +51,8 @@ export interface ContextCapsuleRuntimeDeps {
   countTokens?: (accountingJson: string) => number;
   tokenizerFingerprint?: string | null;
   resolveCurrentRanks?: ContextVerifierDeps["resolveCurrentRanks"];
+  /** Trusted, already-resolved project affinity; never accepts raw inputs. */
+  projectAffinity?: ProjectAffinityScoringInput;
   /** Optional non-canonical receipt session owned by the calling surface. */
   traceSession?: RetrievalTraceSession;
 }

package/src/app/context-runtime.ts

@@ -96,6 +96,7 @@ export const buildContextCapsule = async (
           {
             ...request,
             noRerank: requestNoRerank,
+            projectAffinity: deps.projectAffinity,
             traceSession: deps.traceSession,
           }
         );

package/src/app/context-surface.ts

@@ -44,6 +44,7 @@ export const contextBuildSurfaceSchema = z
     safetyMarginTokens: nonnegativeInteger.optional(),
     safetyMarginBytes: nonnegativeInteger.optional(),
     depthPolicy: z.enum(["fast", "balanced", "thorough"]).optional(),
+    projectHints: z.array(z.string()).max(16).optional(),
     format: z.enum(["json", "md"]).optional(),
   })
   .strict();
@@ -60,6 +61,7 @@ export type ContextSurfaceFormat = "json" | "md";
 export interface ParsedContextBuildSurfaceInput {
   input: ContextCapsuleBuildInput;
   format: ContextSurfaceFormat;
+  projectHints?: string[];
 }
 
 export interface ParsedContextVerifySurfaceInput {
@@ -117,8 +119,8 @@ export const parseContextBuildSurfaceInput = (
 ): ParsedContextBuildSurfaceInput => {
   const parsed = contextBuildSurfaceSchema.safeParse(value);
   if (!parsed.success) throw invalidInput(parsed.error);
-  const { format = "json", ...input } = parsed.data;
-  return { input: { ...input, indexName }, format };
+  const { format = "json", projectHints, ...input } = parsed.data;
+  return { input: { ...input, indexName }, format, projectHints };
 };
 
 export const parseContextVerifySurfaceInput = (