@prodero/curator 0.0.0-stage → 0.1.0

package/docs/APPLICABILITY.md

@@ -0,0 +1,151 @@
+# Applicability and task context
+
+## 1. Previous scope model audit
+
+The audit preceded implementation. The existing scope mechanism is extended; canonical knowledge, catalog, context engine and authority boundary remain the same.
+
+| Area | Previous behavior and distinction | Implementation reference |
+| --- | --- | --- |
+| Markdown | `scope` (`global`, `module`, `task`), nullable `scope_ref` and optional `scope_kind` persisted. The public `project`/`path` names were adapters, not additional canonical scopes. | `src/core/memory.ts:29` |
+| Paths | `scope_kind: path` made even a bare name such as `docs` a path. An untagged module reference containing `/` or `.` was interpreted as a path. Other module references were topics. Exact/descendant matching used relative paths; a bare directory in prose was not path evidence. | `src/core/path-scope.ts:4` |
+| Required | Global was always applicable. Module topics used exact/prefix query matching; task scopes used token overlap. Paths used the path matcher. Policy, not category, already selected required records after explicit context policy was introduced. | `src/core/bootstrap.ts:18`; historical behavior now in `applicability.ts:123` |
+| Relevant | Non-path scope used lexical ranking; path mismatch excluded records. Thus Required and Relevant did not have identical scope semantics. | `src/core/context.ts:108` |
+| Remember | Public project/global both mapped to canonical global, but used priority to distinguish topic retrieval from global guidance. Path mapped to module + explicit path kind. | `src/core/project.ts:519` |
+| Observations / Sync | Scope hints and section defaults supplied candidate boundaries. Deterministic consolidation, assisted validation and catalog neighbor discovery compared legacy scope fields. | `src/core/sessions.ts:165`, `consolidation.ts`, `knowledge-engine.ts:35`, `memory-index.ts` |
+| Other writers | Imports mapped source scope; transformations and replacements inherited source metadata; publication copied canonical records. Maintenance exposed legacy scope fields. Their authority ceiling came from the knowledge authority transaction gate. | `imports.ts:100`, `knowledge-lifecycle.ts:167`, `promotion.ts`, `knowledge-management.ts`, `knowledge-write-policy.ts` |
+| Presentation / cache | Catalog summaries carried scope fields. Prepare snapshots retained the result, Open had its own bootstrap selector, UI/text showed scope labels. | `memory-index.ts`, `context-snapshot.ts`, `bootstrap.ts:90`, `src/presentation.ts`, `src/ui/main.ts` |
+
+The hidden conventions were path-shaped references, task token matching, topic matching that differed by retrieval bucket, and the public project/global priority mapping. `scope_kind` was optional canonical metadata, not evidence of user authorization.
+
+## 2. Final canonical model and version decision
+
+Knowledge Schema **3**, project schema **8** (see `prodero.release.json`). Knowledge applicability was introduced with the schema-6 migration foundation. The bump is necessary: a v2 reader/writer cannot preserve or enforce structured applicability. The existing Migration Foundation provides the compatibility barrier, planner, approval, staging, backup, validation, history and recovery. No parallel migration path exists.
+
+The independent dimensions are:
+
+- category: the kind of knowledge;
+- context_policy: required or relevance-driven delivery;
+- authority: provenance classification, not a capability;
+- applicability: the conditions under which this knowledge applies;
+- priority: importance, independent of scope;
+- relevance: runtime task usefulness, not persisted policy.
+
+Canonical frontmatter example:
+
+```yaml
+version: 3
+context_policy: required
+authority: legacy_inherited
+applicability: {"kind":"scoped","subsystems":["ExampleAPI"],"taskKinds":["testing"]}
+scope: module
+scope_ref: ExampleAPI
+scope_kind: topic
+```
+
+Supported applicability forms:
+
+| Form | Meaning |
+| --- | --- |
+| `{kind: "project"}` | Applies throughout the project. |
+| `{kind: "scoped", paths?, subsystems?, taskKinds?}` | At least one non-empty restriction. |
+| `{kind: "unresolved"}` | Insufficient evidence to assign a work boundary. Ordinary relevant knowledge remains retrievable. No invented global assertion. Valid only for relevant records; required records must state a boundary. |
+| `{kind: "legacy"}` | Preserve the exact existing scope/ref/kind behavior, including the old difference between Required and Relevant. Used by mechanical migration and compatibility adapters. |
+
+For structured forms, scope/ref/kind are a deterministic compatibility projection, validated on read. They are not an independent second applicability source. Project projects to global; scoped uses its first path, otherwise first subsystem, otherwise task kinds. Legacy retains the original fields verbatim. Empty scoped metadata, missing v3 applicability, invalid paths or conflicting projection fail validation.
+
+## 3. Combination and path semantics
+
+Dimensions combine with **AND**; alternatives inside each array combine with **OR**. ExampleAPI + testing means both conditions, not either one. Multiple paths provide explicit alternative targets. Task kinds are implementation, testing, migration, deployment, documentation, review and debugging.
+
+Paths are case-sensitive repository-relative exact/descendant boundaries. An optional terminal `/**` is supported; arbitrary wildcard expressions, absolute paths and parent traversal are not. There are no nested boolean expressions, negation or general policy language. Topics are case-insensitive subsystem labels.
+
+## 4. Task Context and evidence
+
+`buildTaskContext` runs once per context resolution. It carries task text, paths, subsystems, task kinds, a documentation-only focus and signal provenance. Optional MCP/Core `taskContext` accepts paths, subsystems, taskKinds and explicitTopics; agents supply these when known, not through user forms.
+
+Evidence includes explicit arguments, quoted/path-shaped references, activity wording, known canonical subsystem labels, and technical identifiers. A known bare path supplied as the whole task is recognized. An incidental unfamiliar CamelCase identifier is only a hint: it cannot by itself prove that a different subsystem is excluded. An explicit or known-vocabulary subsystem can establish a different task focus. README/documentation wording does not count as implementation merely because it says “update”.
+
+Prepare stores this context in its session. Observations may supply stronger work signals later. Explicitly retrying Prepare with the same session refreshes the context for future observations; already returned context snapshots are not mutated. No filesystem watcher, automatic repository-wide scan or hidden mid-turn context delivery is introduced.
+
+## 5. Tri-state applicability and unknown required policies
+
+The evaluator returns `applicable`, `not_applicable` or `unknown`, with reasons and matched dimensions. A known mismatch makes an AND expression not applicable; otherwise an unresolved dimension makes it unknown.
+
+Required selection is policy → applicability → existing ranking/budget selection. Relevance cannot make a known applicable required policy optional. Existing token budgets, overflow behavior and item ceilings are unchanged.
+
+For **structured required** knowledge:
+
+- applicable enters Required candidates;
+- not applicable is excluded from both delivery buckets;
+- unknown does not silently disappear or become global. It produces `policyReadiness: {state: "context-needed", blocking: true}` and bounded diagnostic metadata. The agent enriches taskContext from actual work evidence and retries Prepare, preferably with the same session ID.
+
+This readiness interruption is **not policy review or an approval request**. Required bodies are not all loaded to resolve uncertainty. If evidence genuinely remains unavailable, Core does not claim that work is ready; a host cannot safely guarantee automatic continuation. Unknown disputed required records receive the same protection. Explicit required conflicts keep the distinct existing `review-required` state.
+
+Legacy records retain their old bucket behavior. In particular, a legacy scoped instruction that did not enter Required can still be retrieved through the historical relevant path. The migration does not reinterpret that behavior.
+
+## 6. Relevant retrieval and explainability
+
+Known unrelated paths/subsystems/activity exclude structured records. Matching dimensions contribute a relevance signal. Unknown relevant records can still match lexical evidence; a graph edge alone cannot admit unknown *restricted* scope with no lexical match. Unresolved ordinary knowledge can use normal lexical/graph retrieval because no specific boundary was asserted.
+
+Selection metadata and snapshots retain applicability decisions. Knowledge Details can evaluate a supplied task. UI View Context and text Details show the human label and decision reasons: matched subsystem/task kind, paths outside a boundary, or missing signals with the expected boundary. Diagnostics are bounded; records outside that window remain inspectable through paginated Knowledge details. No permanent scope-management section was added to Open.
+
+Open without a task loads project-wide required records and legacy global records. Scoped policies remain available to Prepare; bootstrap metrics include their count, without dumping their bodies or adding recurring controls.
+
+## 7. Automatic creation and authority ceiling
+
+Remember and ordinary session observations infer applicability from their content and producing task context. Paths and subsystem identifiers take precedence when present; otherwise session activity/context is used. With no justified restriction, relevant knowledge gets unresolved applicability. Explicit project/global input is still supported but no longer sets priority. Explicit path input produces structured path applicability.
+
+The in-process invocation-local grant binds an exact operation; it does not authenticate a person. The current chat adapter can create that grant from model-supplied `required:true`, `kind:rule` and `userInstruction`, and the App adapter from validated review state. These are workflow safeguards under the [v0.1 trust model](PRIVACY.md). Ordinary inferred observations cannot directly set protected policy. Ambiguous inferred rules remain relevant/inferred.
+
+Legacy scope hints on existing clients/observations remain compatibility inputs. They are not permission to widen protected knowledge. Global instruction candidates remain pending, and skill candidates keep their separate existing scope model.
+
+`evaluateKnowledgeTransition` remains the central gate. Applicable boundary identity is now part of its trusted operation binding, protected-clause equivalence, source ceilings and replacement checks:
+
+- inferred relevant records can narrow to a provable subset with existing provenance;
+- path → project, subsystem → project, dropping a task restriction, or changing an authoritative boundary cannot happen through inference;
+- authoritative narrowing is also protected against accidental de-escalation;
+- invalid/ambiguous mutations preserve the original and use the existing safe-fallback/deferred-review behavior;
+- a new inferred replacement cannot union incomparable source boundaries, and an uncovered source is not retired.
+
+The subset proof is structural, not a claim that an LLM proved semantic equivalence. No new authorization mechanism or automatic promotions are introduced.
+
+## 8. Writer and lifecycle coverage
+
+| Path | Applicability behavior |
+| --- | --- |
+| Remember | Structured applicability or silent inference; replacement defaults to source applicability; policy remains governed by knowledge authority. |
+| Session recording | Persists inferred applicability with each ordinary observation and keeps its existing session/observation provenance. Later explicit work signals can narrow new observations. |
+| Session review | Preserves structured applicability on prose edits; legacy projection edits cannot silently change structured boundaries. Instruction/skill candidate transitions retain their separate lifecycle. |
+| Deterministic Sync | Exact applicability is part of matching. Same content/same boundary deduplicates; overlapping or disjoint different boundaries stay separate. |
+| Assisted Sync/audit | Canonical validation compares applicability with source boundaries after model output. Omitted optional fields inherit source metadata. Incompatible merges are rejected before canonical mutation. |
+| Memory Transformation/lifecycle | Source applicability is inherited; proposals can carry structured metadata. Mixed-boundary consolidation preserves originals instead of creating a broader aggregate. Clean local operations remain automatic. |
+| Imports | Explicit structural applicability or path/topic source metadata is preserved. Otherwise ordinary inference/unresolved fallback. New imported instructions remain relevant/imported. The keyword classifier is unchanged. |
+| Replacement/supersession | Source ceiling and protected-clause checks include applicability. Incompatible retirement cannot erase the original boundary. |
+| Publication | Canonical applicability is copied; matching/merge checks include it. Publication approval confers no policy/applicability authority. |
+| Maintenance/optimization | Prose edits preserve applicability. Structured changes use the same central gate. Duplicate optimization groups include applicability, not only the first projected path/topic. |
+
+## 9. Compatibility, migration, cache and presentation
+
+Production registry step `knowledge-applicability-2-3` mechanically adds `{kind:"legacy"}` and changes record version. It preserves content, category, context policy, authority, lifecycle status, original scope, priority, provenance and relationships in both active and archive stores, Local and Versioned. It does not inspect bodies to infer a subsystem or task kind. Existing global records therefore retain their scope.
+
+The Foundation performs read-only planning, explicit approved execution, backup, staged transform/validation, commit and derived rebuild with recovery/history. Schema advancement follows validated canonical migration. Open/Prepare automatically surface the existing migration card/text flow only when needed. Migration resume now carries taskContext as well as the original task and session. Older runtime capability blocks mutation before an old serializer can strip v3 metadata.
+
+MemoryIndex format **10** stores applicability. Missing, malformed or projection-inconsistent v3 cache entries rebuild from canonical Markdown. Even the trusted low-level writer refuses unmigrated projects and incomplete explicit v3 records; it cannot silently substitute legacy applicability. Knowledge schema/version mismatches cannot be masked by a warm cache. Snapshots retain the resolved task and decision metadata. No independent index inference exists.
+
+Normal UI still says Required, Relevant and Applies to. Scope details stay in View Context/Knowledge Details. Text mode uses the same Core state and migration actions. There are no new per-record review prompts or persistent pending-scope controls.
+
+## 10. Acceptance fixtures and validation
+
+Tests use synthetic records in temporary repositories, including scoped rules for documentation, implementation and testing.
+
+Focused tests cover tri-state/AND/OR/multiple paths, strict round-trips, no-widening, inferred narrowing, same-session enrichment, required readiness/retry, unknown relevant retrieval, Open, Details, index rebuilding, silent ten-observation Sync, trusted rules, assisted Sync, imports, disjoint consolidation, mechanical migration/rollback/interruption, older-runtime mutation barriers and MCP UI/text parity. Existing tests additionally cover publication, maintenance, archive migration, backup failures, multi-step planning and UI migration/resume.
+
+## 11. Limits and deferred work
+
+- Inference is deterministic and deliberately limited. Subsystem aliases, repository ownership maps, multilingual classification and richer trusted touched-file integrations are not a general semantic classifier.
+- Explicit/recognized task focus is treated as the work boundary. A host must enrich incomplete context honestly; simply inventing another subsystem to clear readiness is not supported use.
+- A genuinely unknown required policy can block readiness until the agent resolves context. This is not a recurring approval workflow; perfect automatic resolution from arbitrary prose is not promised.
+- The system conservatively keeps differing overlapping scopes separate rather than proving semantic union/equivalence.
+- No nested predicates, negative clauses, arbitrary globs or task-kind hierarchy.
+- Legacy compatibility behavior intentionally remains coarse. Current curation/import behavior is described in [Importer and curation](IMPORTER-CURATION.md); allocation is described in [Context Selection v2](CONTEXT-SELECTION-V2.md).
+- Existing skills retain their own model; this phase versions knowledge only.

package/docs/COMPATIBILITY.md

@@ -0,0 +1,49 @@
+# v0.1 compatibility
+
+> v0.1 contract: Local/Versioned describe Git storage and sharing, not a security boundary against the connected agent. Review and approval are workflow safeguards, not authenticated human consent. The agent may create, promote and maintain Versioned files. Curator does not commit or push; users review repository changes before doing so. See [Privacy](PRIVACY.md).
+
+Supported runtime target: **Node 22.14.0–22.x**, npm and Git. Node 22.14.0 is the tested minimum; the package rejects other Node majors through its engine contract (npm may only warn unless engine-strict is enabled). `import.meta.dirname` and modern Node filesystem/runtime APIs are used. Earlier Node 20 declarations were not a verified compatibility promise.
+
+| Environment | Status |
+| --- | --- |
+| macOS ARM64, Node 22.14.0 | Tested locally: full tests and isolated release gate |
+| macOS / Ubuntu, Node 22.14.0 and latest 22.x | CI release-gate matrix; support certification requires green runs on the exact RC commit |
+| Native Windows | Not supported in v0.1; filesystem/Git fixtures and process behavior are not verified |
+| Node 20, 24 or other majors; WSL | Not verified / outside the initial runtime contract |
+
+CI configuration is not evidence that a remote run has passed. Record actual runs before publication.
+
+## Hosts
+
+| Host | Status / boundary |
+| --- | --- |
+| Codex CLI | Tested: Codex CLI 0.144.4 on macOS ARM64 with an isolated v0.1.0 artifact. Text lifecycle, knowledge maintenance and promotion preview; no Apps rendering claim from a CLI test. |
+| Codex desktop | Used during development with Apps; artifact-host UI interaction has not yet been independently verified. |
+| Claude Code | Experimental adapter: native 2.1.52 user MCP registration and stdio connection verified in isolated HOME. Bare-word model flow stopped at login; not certified as supported. |
+| Claude Desktop | No installer adapter; not verified. |
+| Cursor | Not yet verified against this RC. Workspace and Apps behavior must be checked before claiming support. |
+| Other MCP hosts | Experimental; require standard stdio tools, optional roots and optional Apps/sampling. |
+
+Use `prodero install` for one global machine integration. New workspaces initialize directly through MCP. Negotiated host roots authorize project selection; Claude's captured host project directory selects the primary root, and supported local Codex stdio launches supply the workspace through their launch directory. `projectRoot` is a checked selector, not authority. Missing supported context fails closed; no manual allowlist, per-project registration or CLI initialization is required. Explicit `--root` remains an optional hard boundary. Both integrations use the absolute public `prodero` executable: `mcp` for the installed package and `mcp --dev` for the saved Curator checkout. The public executable captures workspace context before loading development code. Update old global integration once and reconnect; `npm --prefix` is not a supported outer launcher. Managed PATH resolves the shebang to the verified Node installation. See [host integration](hosts.md) and [workspace trust contract](PRIVACY.md).
+
+Apps-capable hosts can render bundled main/lifecycle/plugin resources. Others receive text and structured content; knowledge actions and explicit text approval remain available. Serving an HTML resource in a protocol smoke test does not verify host rendering. Sampling is optional and host-controlled; deterministic operation works without it. Assisted inputs may be transmitted to the host/model.
+
+Machine integration verification: Codex CLI 0.144.4 loaded the installed artifact's native configuration and global launcher in isolated HOME, received only `prodero`, and invoked `prodero_open` with the test workspace. The uninitialized project response exposed initialization and the main App resource; no project was initialized by installation. This text run does not certify desktop rendering.
+
+Claude Code does not automatically read project `AGENTS.md`. Initialization remains unchanged; experimental Claude users need the host's documented project `CLAUDE.md` import of `@AGENTS.md` for the existing project lifecycle instructions. The installer does not create that project file or move lifecycle instructions into the global launcher. See [host integration](hosts.md). Restart hosts after package updates.
+
+## RC evidence
+
+The [release gate](RELEASING.md) checks a clean installed artifact, stdio lifecycle, Local storage, reviewed synthetic sharing, restart and synthetic patch upgrade preservation. Synthetic upgrades do not certify future releases or arbitrary schema downgrades. Record results for the exact release candidate.
+
+Codex CLI 0.144.4 connected to the installed artifact with a fixed project root. It performed open/initialize/prepare/record/close/next prepare with the learned decision, conversational remember/search/inspect/Local edit and promotion preview. Noninteractive writes required invocation-scoped preapproval of only the synthetic test tools; publication was excluded. The host's sandbox kept `.git` read-only, so the outer test harness committed the initialization baseline; normal host operations then left Git clean. Interactive users should approve their own actions; do not copy test preapprovals into normal host setup.
+
+The host correctly rejected an incomplete edit without a title, then accepted the corrected request. Apps UI rendering and host sampling were not verified by this text run. Actual publication is covered by the separate deterministic synthetic protocol fixture, not claimed as human UI approval.
+
+Passing configured remote CI jobs on the final RC commit remains required before publication. Local protocol checks do not certify other Node/OS combinations or host App rendering.
+
+Codex setup and per-tool configuration reference: [official configuration reference](https://developers.openai.com/codex/config-reference).
+
+## Project and knowledge compatibility
+
+Project schema 8 and Knowledge Schema 3 are the current targets. Schema 3 adds explicit applicability with a mechanical legacy-scope migration; see [Applicability](APPLICABILITY.md). Missing knowledge version means legacy format 1; its approved migration preserves instruction behavior with explicit context policy and legacy authority. Both versions live in the project config; moving or cloning a project requires no machine registry. Newer project or knowledge formats fail closed at the storage boundary. Open/Prepare can present update instructions without interpreting unsupported records. See [Migration Foundation](MIGRATIONS.md) for approval, recovery and future format transitions.

package/docs/CONTEXT-SELECTION-V2.md

@@ -0,0 +1,61 @@
+# Context Selection v2
+
+Context Selection v2 changes runtime allocation only. Knowledge Schema remains v3. Applicability, authority, canonical writers, migration and curation authorization are unchanged. Open/Bootstrap keeps its existing compact allocation.
+
+## One resource ledger
+
+Prepare uses `ContextAllocation` as its single capacity ledger. Existing applicability and ranking identify candidates before allocation. Delivery is whole-record and deterministic; no model calls occur in selection.
+
+Order:
+
+1. Applicable Required, using existing criticality/relevance ordering.
+2. Strong matching active Skills (existing skill score at least 14).
+3. Relevant, using existing lexical/applicability/graph ranking and scope/category diversity.
+4. Remaining matching Skills if capacity permits.
+
+Required takes precedence over Skills. A skill with strong domain evidence gets capacity before optional knowledge. Four skills and 1,500 skill tokens remain safety limits. The score 14 threshold uses accumulated domain evidence in the existing scoring model (for example, title plus scope, or multiple trigger matches), rather than introducing new skill semantics. Skills omitted by total/token/item constraints are diagnosed individually.
+
+## Required reserve and safety
+
+The default total remains 6,000 estimated tokens. The existing 2,000 Required setting is a reserve, not a ceiling. Required may borrow all unused total capacity; an unused reserve is released to Skills/Relevant. With default total, Required is bounded by 6,000; independent hard ceilings of 16,000 tokens and 128 records protect projects configured with much larger totals. Hard ceilings are runtime safeguards, not new required user configuration.
+
+No record is split. An oversized record can be omitted while later fitting Required records are delivered, but the result is explicitly incomplete. No required record is reclassified as Relevant to evade a ceiling.
+
+`policyReadiness` precedence remains conflict (`review-required`), unknown applicability (`context-needed`), then delivery failure (`required-incomplete`), then `ready`. All first three states block safe continuation. Allocation completeness and omission diagnostics remain available even when another readiness state takes precedence. Incomplete delivery is not ordinary optimization; inspect omissions and retry after providing an appropriate task boundary or explicitly changing total capacity. The allocator never changes policy or scope itself.
+
+## Relevant marginal continuation
+
+Existing `context.max_items` (default 8) is the initial soft retrieval target. It remains a bounded graph-seed target too. Eligible records are ranked with existing signals; beyond that target a candidate must satisfy all of:
+
+- diversity-adjusted score at least 12 and at least 30% of the best candidate's base score;
+- at least three previously unsupplied non-query, non-numeric terms;
+- novel terms at least 20% of its non-query content vocabulary;
+- whole-record token capacity and the 128-record safety ceiling.
+
+Novelty is measured against delivered Required and previously selected Relevant. It is an approximate redundancy signal, not semantic equivalence or authority. A rejection does not prevent a later valuable/fitting record from being considered. Traversal can stop when all remaining records are below the monotonic score floor or none can fit. Ranking uses sorted scope/category queues, preserving diversity ordering without sorting the whole candidate set on each step.
+
+This deliberately leaves spare capacity when the next information is weak or redundant. The first target is still governed by existing retrieval eligibility; it is not a guarantee that eight records exist. Settings retain compatibility names (`maxRelevantItems`, `requiredContextBudgetTokens`) in existing contracts; `allocation` gives their unambiguous target/reserve meaning.
+
+## Diagnostics and compatibility
+
+`ContextResult.allocation.version = 2` reports demand, delivery, borrowed tokens, completeness, hard ceilings, beyond-target selection, capacity/safety/marginal omissions, skill allocation, and unused total capacity. Existing metrics remain for compatibility. Required pressure relative to the reserve can be high while delivery is complete; readiness/completeness, not that ratio, decides whether work can continue.
+
+Omitted records retain legacy `reason` plus precise `constraint` where applicable. Retrieval evidence adds `marginal-value`; snapshots retain the actual allocation rather than rerunning retrieval. View Context exposes allocation Details and omitted-record causes; text presentation uses the same Core result. Normal UI remains counts and readiness.
+
+Legacy `budgetTokens`/`requiredBudgetTokens` config aliases remain supported. No config edit or knowledge migration is required for this allocator.
+
+Skill curation previously simulated a one-token Required ceiling to retrieve those records as optional evidence. It now consumes delivered Required and Relevant explicitly; no escape hatch can bypass the Required safety ceiling.
+
+## Stable acceptance fixtures
+
+`test/helpers/context-v2-fixture.mjs` creates synthetic temporary projects with explicit v3 policies/applicability. Fixed token demands exercise Required borrowing, Relevant novelty and skill competition using the actual estimator, catalog and selector. These fixtures are not a copy of a private project.
+
+## Limitations
+
+Token counts remain byte-based estimates of knowledge/skill payload, not a tokenizer count of the entire MCP/JSON envelope or host prompt. Marginal novelty cannot prove semantic redundancy; synonymous notes or incidental vocabulary may be misestimated. Thresholds are deterministic heuristics, tested against synthetic workloads, not a guarantee for arbitrary live project corpora. The first target uses existing retrieval quality. Large genuinely mandatory corpora can still produce incomplete context; the allocator does not silently relax protection.
+
+## Validation
+
+- Server TypeScript build and MCP Apps UI/plugin builds: passed through `npm test` pretest.
+- `git diff --check`: passed.
+- Ten focused allocator regressions cover actual selector fixtures, Required borrowing/completeness and hard ceilings, oversized whole records, strong/weak Relevant, Skill competition, readiness precedence, MCP/text serialization and View Context diagnostics. Existing budget, pressure, curation simulation and instruction-review tests now exercise real total-capacity failures rather than the retired ordinary item stops.

package/docs/CURATION-APP-REVIEW.md

@@ -0,0 +1,156 @@
+# App-first knowledge review
+
+> v0.1 contract: Local/Versioned describe Git storage and sharing, not a security boundary against the connected agent. Review and approval are workflow safeguards, not authenticated human consent. The agent may create, promote and maintain Versioned files. Curator does not commit or push; users review repository changes before doing so. See [Privacy](PRIVACY.md).
+
+The review workflow separates analysis, dispositions, clarification and execution state.
+See [Review lifecycle](#review-lifecycle) for the current journal,
+projection, deferral and legacy compatibility contract. The protected Apply
+protocol below remains authoritative.
+
+## Architecture and protocol
+
+The graphical workflow is Analyze → Review knowledge → Current / Suggested /
+Decide later → review summary → Apply changes → result. Only the final Apply
+handler invokes `prodero_curation_apply`. Rendering, navigation, refresh, analysis,
+simulation and staged decisions do not apply knowledge changes.
+
+`reviewCuration` is no longer a startup requirement. Previously its trusted
+embedding callback authenticated review and supplied the exact-batch grant; normal
+MCP startup did not supply it. Now the server adapter validates saved review
+state before granting the existing invocation-local `withTrustedKnowledgeBatch`.
+Core retains the same policy gate and exact-record authorization, without MCP or
+host-specific dependencies.
+
+1. `prodero_curation` exposes plan, simulate and defer, including in text mode.
+2. App-only `prodero_curation_review` exposes create, inspect, decide and preview, plus analysis, answers, deferral/reopening and retry actions.
+   Creation seals the server's current plan; the UI displays that saved plan.
+3. Decisions are `current | suggested | deferred`, keyed by server-defined review
+   items. Absence means not reviewed, never implicit acceptance. Linked merge
+   proposals form one review item. Unsafe/conflicting items cannot be Suggested.
+4. Each staging request supplies the expected decision revision. Conflicting
+   edits return `review_changed` and require reloading the saved decisions.
+5. The final App-only `prodero_curation_apply` request contains `reviewId`,
+   `planHash`, `decisionRevision`, `selectedIds`, and optionally `projectRoot`.
+   Replacement records, output text and approval booleans are not accepted.
+6. The adapter derives selection from the saved decisions and immutable plan,
+   compares it exactly with the request, checks dependency closure, and executes
+   only those entries through Core.
+
+Both App-only tools declare `_meta.ui.visibility: ["app"]` and are deliberately
+outside the `prodero_text` gateway. Their handlers also require the standard MCP
+Apps MIME capability on the connection; non-App clients fail closed even if they
+ignore visibility metadata. Capability negotiation is not proof of user intent. The old `action:"apply"`, including with
+`approved:true`, fails validation. The external callback has been removed; an old
+runtime embedding must migrate to the App flow. Unrelated Sync Memory routes and
+authorization remain unchanged.
+
+## Review lifecycle
+
+`.prodero/local/curation-reviews/<reviewId>.json` holds the immutable snapshot:
+project path and canonical real path, plan hash, engine version, complete catalog
+fingerprint, source revisions/preimages, exact outputs, evidence revisions,
+dependency groups, creation time and integrity hash. The paired `.state.json`
+now holds the version-2 decision journal: snapshot/project binding, a legacy-compatible baseline and append-only revisioned user events. Version-1 state remains readable.
+Writes are atomic and staging uses the common writer lock. No lock is held during
+human review. Reopening resumes the newest valid review matching the current plan;
+MCP restart does not discard it.
+
+Snapshots expire for Apply after seven days and are bounded to 32 per project,
+with an 8 MiB per-file limit. Decision-bearing snapshot/journal pairs remain pinned
+and inspectable past expiry. Creation prunes only abandoned decision-free pairs;
+if saved decisions fill the capacity, creation fails visibly without deleting them.
+Journals additionally cap events at 2,048. Cleanup is opportunistic.
+Checkpoint receipts have independent existing history retention and are not
+removed with reviews. Pending transactions prevent creating a new review rather
+than making analysis recover a partially applied mutation.
+
+## Validation, transactions and replay
+
+Apply acquires the existing writer lock, recovers unfinished transactions, then
+checks for a completed receipt **before** stale validation. Operation identity is
+a hash of review ID and the sorted exact selection; order does not affect it.
+The completed receipt is bound to project identity and plan hash. An identical
+retry returns its checkpoint, even after review expiry/removal or a lost response.
+It does not execute a second mutation or fail because the successful operation
+made its own source plan stale.
+
+For a new operation the server validates snapshot integrity, project, engine,
+plan hash, decision revision, exact selection and complete dependency groups.
+It replans the full relevant catalog/evidence under the lock and compares plan
+hash and catalog fingerprint. Core also checks selected source/evidence revisions
+and transaction preimage hashes. Any stale plan applies nothing and returns
+`stale_review`; changing the selection on an already applied review requires a
+fresh review. Cooperative project writers share this lock. Arbitrary external
+filesystem edits are not a serialized writer and remain subject to the existing
+transaction conflict/recovery contract.
+
+The existing exact-mode transaction writes outputs/retirements and checkpoint,
+with checkpoint completion last, then rebuilds the index. Recovery rolls forward;
+there is no new Undo implementation. History includes review and operation IDs,
+plan/engine, exact selection, staged decisions, preimages and complete proposed
+outputs. Results identify applied, unselected and unresolved proposals, checkpoint
+ID/location and whether the response is a replay.
+
+## Human review
+
+All surfaces consume a shared server projection, including persisted deferrals.
+The default entry focuses on decisions needing attention; Review all includes
+all knowledge. Cards compare current/suggested text, policy, applicability and
+scope. Clicking a card stages its choice and advances; Previous and per-item
+summary links allow corrections. Left/Right select Current/Suggested, L defers,
+and Backspace returns. Keyboard navigation has no Apply shortcut.
+
+Straightforward suggestions can be selected together through an explicit action;
+existing Current/Later choices are preserved. Nothing is preselected because it
+is high-confidence. Unresolved recommendations remain unavailable for application.
+The summary distinguishes current attention, deferred issues, deferred changes,
+unchanged records and included proposals and can preview context
+impact for the staged selection. Technical identifiers and results are in Details.
+Stale review displays “Knowledge changed since this review” with a fresh-review
+action. Successful completion shows counts and history availability.
+
+## Workflow safeguards and host compatibility
+
+The first-party App and a compliant MCP Apps host provide the intended review workflow, not authenticated human authorization.
+The host must hide App-only tools from the model and route App tool calls. An App
+can invoke tools through `App.callServerTool`; a server receives a normal tool
+request, not a cryptographic attestation of a physical click. Visibility metadata
+is **not** authentication against a malicious raw MCP client, modified App, or
+host that exposes all tools to its model. No `approved` boolean or client-provided
+proposal can substitute for the validated server snapshot and Core grant.
+
+This uses the standard [MCP Apps interaction model](https://modelcontextprotocol.io/extensions/apps/overview)
+and [tool visibility metadata](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx).
+Codex and Claude use the same adapter where the host supports these capabilities;
+there is no host-name branching. Actual visibility enforcement, App permissions,
+reload behavior and rendering must be verified for each host/version. A host
+without Apps uses preview-only text. This phase implements no MCP elicitation.
+No trusted-host authorization or elicitation system is required for the accepted v0.1 contract. Existing App-only curation and preview-only text routing remain workflow restrictions; other agent-callable Versioned writers remain available.
+
+## Verification and host acceptance
+
+Automated tests cover snapshot persistence/retention, selection and merge groups,
+unresolved rejection, source/evidence/dependency/catalog staleness, identity and
+payload rejection, non-App connection rejection, writer serialization, recovery before validation, replay after
+lost response and snapshot removal, alternate selections, legacy/text rejection,
+and App-only metadata. Production UI handlers run against the actual server over
+an MCP in-memory transport: rendering, cards, backtracking, bulk decisions,
+preview/reload, keyboard, final Apply, completion and stale recovery are exercised.
+These tests do not establish host-side filtering or visual appearance.
+
+For host acceptance, after `npm run build` in the repository, use
+`node scripts/curation-review-fixture.mjs` to create a
+throwaway project, open its Curator App, and verify:
+
+1. Review renders; opening/reopening, refresh and preview preserve knowledge bytes.
+2. Current/Suggested/Later stage only decisions; only Apply sends
+   `prodero_curation_apply` and creates a curation checkpoint.
+3. Details' checkpoint matches the reviewed outputs and source preimages.
+4. Repeating the same captured Apply request through the App bridge returns the
+   same checkpoint with `replayed:true` (including after a lost response).
+5. Edit a fixture source after review; Apply returns `stale_review`, changes
+   nothing else and offers Review updated changes.
+6. Inspect the host's model-facing catalog: neither App-only tool is exposed;
+   model-visible curation and text paths cannot apply.
+
+Do not substitute a raw SDK client for the host checks in steps 1, 2 and 6.

package/docs/CURATION-CLAUSE-REFINEMENT.md

@@ -0,0 +1,45 @@
+# Required clauses and attention evidence
+
+## Previous behavior
+
+`planKnowledgeCuration` previously inherited Required for every analyzed fragment except transient text and a fragment beginning `Workflow Note:`. It forced each inherited fragment to category instruction. The import analyzer also joined Impact and many Constraint fields to their Decision. Consequently commands, test-quality notes, implementation observations and explanations could become independently mandatory. This was a proposal rule, not an automatic canonical mutation.
+
+## Current analysis
+
+`curation-clauses.ts` is a curation-only refinement of the existing evidence-first analyzer. Importer v2 behavior is unchanged. Internal roles are constraint, invariant, convention, procedure, command, lesson, history, rationale and unresolved. These roles are not new canonical categories or authority values. Knowledge Schema remains v3.
+
+Labeled source fields and complete sentences establish exact source ranges. Required is inherited only by identified normative constraints, invariants and conventions. Explicit supporting fields do not acquire mandatory policy through imperative grammar. An explicitly mandatory command can remain normative. A historical observation does not weaken a separate conditional constraint. Unstructured authored rules remain intact rather than being speculatively demoted.
+
+Adjacent compatible clauses coalesce. Nonadjacent normative clauses from the same source and applicability are grouped into one output, while supporting text remains in coherent role groups. Outputs retain original text; mappings cover every source range and validate reconstructed content. This deliberately avoids creative compression. Supporting records retain source provenance, lifecycle, priority, relationships and legacy authority while receiving Relevant delivery policy. Every semantic change still needs exact trusted batch review.
+
+This deterministic role classifier is conservative proposal analysis, not a general natural-language proof. Inseparable or conflicting normative meaning remains review work. Token savings never decide a role.
+
+## Consolidation
+
+The planner can consolidate source-identical normative cores only with identical applicability, scope, authority, priority and storage layer. Shared outputs union provenance and relationships. Every participating source must be selected in the same exact review batch; source retirement and output creation use the existing journal transaction. Different clauses, different scopes, or mere shared vocabulary do not establish equivalence. Paraphrase-based consolidation is intentionally not claimed as proven.
+
+## Read-only evidence
+
+`curation-evidence.ts` scans bounded test, handler, documentation, build and deployment directories. It reads source text only: no test execution, shell evaluation, configuration loading or project lifecycle calls. Vendor trees, caches, canonical memory, assets and symlinks are excluded. Each excerpt includes relative path, line and SHA-256. File count/depth/size ceilings bound work; truncated inspection is explicit in the plan.
+
+Current tests can resolve a helper label into the actual API testing boundary. Named source domains plus matching implementation evidence can replace incidental DB/PHP/SKU labels. Historical observations can remain traceable Relevant history without asserting they are still true. Static test definitions do not establish a passing runtime or deployed production state. A current export test allowing fake queries/dispatch is evidence of architecture beyond an old blanket refusal; it does not authorize real integrations.
+
+Evidence classifications distinguish resolved proposal, reduced ambiguity, genuine decision and historical-only. The original normative meaning remains protected even when implementation disagrees. Mirroring conflicts compare active Required knowledge, excluding historical lessons that merely mention failed mirror fixes.
+
+Plans include evidence root, truncation status and source revisions. Apply rechecks referenced evidence bytes, in addition to canonical source revisions and the existing exact-plan trusted capability. Neither evidence, confidence, plan possession nor a boolean approval bypasses the exact-record Core policy checks. These internal checks do not authenticate human consent; the App adapter can issue the grant from a validated caller request. See [the v0.1 trust model](PRIVACY.md).
+
+## Presentation and simulation
+
+Shared UI/text presentation puts unresolved decisions before grouped suggestions. Evidence excerpts, hashes and full source/output content are in Details. No permanent panel or new Prepare interruption is introduced. Deferral uses the existing revision-bound recommendation lifecycle.
+
+Simulation writes only disposable canonical copies and invokes the unchanged real context selector. Metrics now also include applicability decisions/reasons. Simulation uses the current [Context Selection v2](CONTEXT-SELECTION-V2.md) allocator: a default 6,000-token total, a 2,000-token Required reserve, 128-item / 16,000-token Required safety ceilings and a soft Relevant target of 8.
+
+## Boundaries
+
+- Static evidence cannot prove a historical PHPUnit error is resolved or production rollout completed.
+- No new host-specific trusted review adapter is introduced. The existing trusted Core/embedding batch boundary is required for application.
+- Exact repeated normative cores consolidate; differing fail-closed/harness/DB/export requirements are not merged merely to fit a budget.
+
+## Validation
+
+Synthetic clause/evidence/consolidation tests exercise the actual planner and context selector in temporary projects.

package/docs/IMPORTER-CURATION.md

@@ -0,0 +1,142 @@
+# Importer v2 and legacy curation
+
+> v0.1 contract: Local/Versioned describe Git storage and sharing, not a security boundary against the connected agent. Review and approval are workflow safeguards, not authenticated human consent. The agent may create, promote and maintain Versioned files. Curator does not commit or push; users review repository changes before doing so. See [Privacy](PRIVACY.md).
+
+## Existing architecture and root cause
+
+The optional `plugins/migrate_ai_studio/index.cjs` importer gathers bounded source
+and repository evidence, seals a project-bound plan, reviews inclusion as one batch,
+then delegates canonical writes to Core `imports.ts`. Checkpoint receipts provide
+exact replay, before-state fingerprints, and verification. Source files are never
+rewritten. Semantic mode already has bounded evidence validation and exclusions.
+
+Previously `durableSections` concatenated Decision, Impact, Constraint and Workflow
+Note, matched must/should/never/always/required/keep/use/run/do not/cannot in Decision,
+and assigned instruction/global. Before explicit policy this implied Required.
+After Phase 1B Core prevents required/imported creation, but the plugin still had
+poor category/granularity and global projections. Titles used the first sentence
+of Decision. Literal portable-prose sanitization replaces task IDs and legacy
+workspace paths; source evidence must retain the original reference.
+
+## Importer implementation
+
+`knowledge-analysis.ts` is a deterministic proposal service exposed through the
+existing plugin context. It uses the Phase 2 Task Context/applicability APIs, not a
+new evaluator. Explicit source labels, normative meaning, transient-state markers,
+paths, leading named topics and activity evidence guide classification. Decision
+labels do not override clear normative meaning; imperative words never authorize
+mandatory delivery. It supports existing canonical categories only. Decision and
+Impact remain cohesive; compatible normative Constraint stays attached. Workflow,
+State and Lesson sections can split where lifecycle differs. Exact source slices
+remain traceable. Oversized sections fail instead of being silently truncated.
+
+All historical knowledge still passes Core import validation and the transaction
+authority gate: Relevant/Imported, normal priority. The plugin cannot request
+Required or explicit_user/reviewed. Source-derived scopes are unresolved or scoped;
+there is no project-wide fallback. Historical state is retained. Prompt text is
+additional guidance, never authorization.
+
+The existing wire plan/receipt version remains compatible. The analysis engine is
+versioned independently (`evidence-2`); existing plugin protocol identifiers remain
+unchanged. New receipts retain source evidence. Re-audit checks original source
+entry keys as well as decomposed child keys, so old receipts prevent unchanged
+source re-import even after canonical editing or changed classification. New
+receipt source ranges detect source updates and leave them excluded for review.
+Old receipts without source positions cannot establish that an arbitrarily edited
+or moved source entry is the same entry: that remains a limitation. Normal import
+never rewrites legacy canonical knowledge. Exact content/applicability dedup still
+runs in Core. Preview summarizes categories, Relevant/Required, scoped/unresolved
+and per-record source details; selection is batch-oriented.
+
+## Curation is not migration
+
+`knowledge-curation.ts` uses a read-only MemoryCatalog (`persistCache:false`). It
+analyzes active/disputed legacy Required records, excluding already curated
+outputs, and returns a deterministic project/revision/engine/schema-bound plan.
+No plan creation writes canonical files, indexes, archives, schema or history.
+Current explicit_user/reviewed records are not cleanup targets, though their
+conflicting evidence can place legacy sources in attention. Other authority and
+relevant-only maintenance targets are deferred.
+
+Proposals distinguish applicability narrowing, policy/category changes and
+content decomposition. Legacy mandatory meaning is deliberately preserved unless
+a separately identified workflow/history component is proposed as relevant.
+Time-sensitive state, known contradiction relations, disputed records and possible
+artifact-mirroring conflicts are attention items. Content alone does not establish
+that a rule is obsolete. There is no LLM winner and no timestamp winner.
+
+Every selected source is accounted for. Decomposition maps character ranges to
+output IDs, retains source sessions/evidence and adds revision-qualified derivation.
+No lexical paraphrase is considered a proof of clause preservation. Different or
+incomparable applicability is not merged. The deterministic base analyzer keeps non-equivalent related records separate;
+current bounded reasoning and clarification can refine review proposals.
+This intentionally avoids conflating similar wording with equivalent protection.
+
+## Review and application
+
+A plan is not permission. `withTrustedKnowledgeBatch` extends the existing central
+Phase 1B gate with invocation-local, exact-record/preimage/project authorization.
+`curationReviewEntries` exposes the exact batch to a trusted adapter; serialized
+plan IDs, confidence and approved booleans cannot mint the capability.
+
+`applyKnowledgeCuration` supports selected safe groups, validates the plan and
+selected source revisions, takes the existing writer lock, recovers a pending
+journal and uses `commitSyncTransaction` in exact mode. New decomposition outputs
+precede source retirement. Original bytes, exact plan/selection, unchanged IDs and
+engine version are retained in the final checkpoint. Canonical parser validation
+precedes commit; the existing journal supplies deterministic roll-forward after
+interruption. Index rebuild follows commit and is retried after completed replay.
+There is no new rollback engine: checkpoint preimages support diagnosis/restoration,
+while automatic recovery uses the existing roll-forward contract. Unselected
+attention records remain byte-for-byte unchanged. No source file is silently erased.
+
+Stale selected sources fail with their ID. Core can apply an unaffected selected
+group using its original plan; the MCP UI currently refreshes the whole fingerprint
+and conservatively rejects stale plans. Core replay of the same reviewed selection
+is idempotent. Review grants expire when their invocation completes.
+
+## MCP, UI and text
+
+`prodero_curation` provides plan/simulate/defer and remains available through
+`prodero_text`. Graphical review now uses persistent server-owned snapshots,
+staged Current/Suggested/Later decisions and a separate App-only apply tool.
+The external `reviewCuration` startup callback is no longer required. The adapter
+validates the entire plan under the writer lock before granting Core's exact-batch
+permission. Text mode remains preview-only; legacy model-visible apply is closed.
+See [App-first knowledge review](CURATION-APP-REVIEW.md) for protocol, retention,
+replay, trust boundaries, compatibility and verification status.
+
+Open may offer a non-blocking cleanup card; Prepare has no curation dependency.
+Later persists a checkpoint tied to the exact recommendation, not a knowledge
+record or policy rejection. Repeated Open suppresses unchanged deferred cards;
+material canonical changes or a new analysis version can resurface them. Details
+retain access. Analysis errors are caught by Open and do not block ordinary work.
+No new recurring approval interaction is introduced.
+
+## Simulation and metrics
+
+Simulation copies canonical memory and skills plus the current config into an
+isolated temporary repository, writes actual proposed Markdown, and runs the real
+`prepareContext` entry point before and after. It does not call lifecycle Prepare,
+Sync, simplify ranking or adjust budgets. Temporary stores are removed in finally.
+Metrics include real estimated candidate/selected/omitted tokens and counts,
+relevant item-limit omissions, total tokens, unknown required and readiness.
+
+Two explicit modes distinguish **safe batch** (attention unchanged) from a
+conditional **all proposals** scenario (attention outputs included for measurement
+only, still requiring further review). The default UI simulates the safe batch.
+The latter is not a prediction that attention has been resolved or approved.
+
+Current targets are Knowledge Schema v3 and Project Schema v8; curation itself does not advance schema versions. Retrieval,
+required/relevant item limits, skill limits and token budgets are unchanged.
+
+## Limitations and scaling
+
+Deterministic analysis makes zero model calls. Parsing/classification is linear in
+source text; catalog/evidence grouping is in memory. Conflict cross-checking can
+be quadratic in candidate count; optional expensive semantic work is not required
+for project usability. This is not a complete semantic oracle: leading identifiers,
+path-vs-domain boundaries, stale validity and complex conflicts can need refinement.
+Current review supports bounded reasoning, clarification answers, deferral/reopening
+and retry through the existing curation tools. This is not autonomous organization
+cleanup, arbitrary rewriting or a new rollback UI.