feat(harness): compile role-neutral focused briefs

.changeset/focused-project-briefs.md

@@ -0,0 +1,13 @@
+---
+"@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 its separately retryable `briefRefresh` result; 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.

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

@@ -48,11 +48,46 @@ session creation.
 
 ## Reserved focused-brief seam
 
-SAP-3149 reserves append-only brief histories for later focused-context work
-without running a compiler. A brief has a stable logical ID and a neutral focus
+SAP-3149 established append-only brief histories for focused-context work. A
+brief has a stable logical ID and a neutral focus
 scope: either a canonical workstream or an ad-hoc delegation whose parent scope
 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; plan apply and rebase never invoke a compiler or mutate
-brief pointers.
+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.
+
+Trusted hosts attach an overlay by calling `serializeFocusedSessionContext`
+with the exact map, plan, and brief versions, checking its discriminated result,
+and passing the branded `projection` through `TrustedSessionCreateOptions` or
+`TrustedSessionResumeOptions`. Focused context is rejected outside a trusted
+project-agent identity. Ordinary callers cannot construct the branded value,
+and authored data must never be appended to a prompt by another serialization
+path.