feat(harness): compile focused context [Agent Map 11/15]

.changeset/focused-project-briefs.md

@@ -0,0 +1,15 @@
+---
+"@sapiom/harness": minor
+---
+
+Add deterministic role-neutral focused brief compilation, categorized impact,
+immutable scope-keyed lifecycle refresh, and bounded prompt-safe context
+projection for canonical and ad-hoc project work. Build-plan apply and rebase
+now perform a best-effort brief-history refresh after committing the plan and
+return separate `briefRefresh` recovery guidance; the universal
+`build_plan_brief_refresh` tool retries the exact source independently. Brief
+refresh receipts use bounded retention, while durable history exhaustion is
+reported as terminal manual intervention rather than an endlessly retryable
+storage failure.
+
+Publish the compiler functions and `DeterministicAgentBriefCompiler`, `AgentBriefService`, impact evaluator, and `serializeFocusedSessionContext` with its discriminated result and branded projection type. These helpers support exact-version offline compilation and safe context composition; Studio attaches projections through its internal session manager. Automatic refresh uses a trusted receipt namespace that caller map, plan and brief request IDs cannot occupy.

packages/harness/docs/shared-build-plan.md

@@ -55,3 +55,51 @@ may identify nested delegation. Each scope has an explicit active or retired
 pointer. Retirement preserves history, and reactivation appends the next
 version against that retained history. New and migrated aggregates start with
 empty brief histories.
+
+## Focused brief compilation and refresh
+
+`build_plan_brief_refresh` deterministically joins one exact current map version
+and one exact current plan version. It compiles either the canonical top-level
+workstreams or explicit ad-hoc/nested delegation scopes, appends only changed
+brief versions, and retains explicit retired pointers and immutable history.
+Plan apply and rebase commit before their best-effort canonical refresh, so a
+bounded compiler diagnostic never rolls back accepted plan intent; the refresh
+tool can be retried independently and idempotently.
+
+Each logical brief retains at most 1,024 immutable versions; exhausting that
+history returns terminal `quota_exceeded` with `manual_intervention` recovery.
+The newest 256 brief-refresh receipts remain replayable, while older receipts
+expire into tombstones and return `request_id_expired`, requiring a new request
+ID instead of replaying the original result.
+
+Brief fingerprints separate owned nodes, relevant nodes, input/output
+contracts, relationships, resources, milestones, shared plan content, and
+assignment content. Impact and freshness are diagnostic only. They never
+change tools, session writability, or implementation authority.
+
+The optional focused-session prompt overlay is an allowlisted, deterministic,
+size-bounded projection. Authored strings are delimited as untrusted data,
+delimiter-shaped and Unicode format characters are escaped, sensitive/path-like
+values are redacted, and oversized collections are truncated with a diagnostic.
+A project session without an overlay receives the common project-agent prompt
+byte-for-byte unchanged and keeps the same tool surface.
+
+The package exports `compileCanonicalWorkstreamBriefs`, `projectFocusedBriefs`
+(and its supported `compileAgentBriefs` alias), `DeterministicAgentBriefCompiler`,
+`evaluateAgentBriefImpact`, and `serializeFocusedSessionContext` for exact-version
+compilation, impact inspection, and safe context composition. Check the serializer's
+discriminated result before using its branded `projection`. The exported
+`AgentBriefService` runs the same refresh and projection pipeline when supplied a
+compatible planning store.
+
+Studio attaches this projection through its internal `SessionManager` and trusted
+create/resume options. Those session controls are not package exports; external
+hosts use `startServer` to run Studio's complete session and MCP surface. Focused
+context is rejected outside a trusted project-agent identity.
+
+Automatic post-write refresh uses a trusted `harness-internal:brief:` receipt
+namespace. Caller-supplied map, plan and explicit brief request IDs cannot use that
+prefix; existing `brief-planv_*` caller IDs remain valid. Automatic failure results
+use the same recovery advice as explicit refresh: correct input, reread sources,
+use a new explicit refresh request, retry transient storage, or request manual
+intervention for permanent limits.