@prodero/curator 0.0.0-stage → 0.2.0

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.

package/docs/KNOWLEDGE-AUTHORITY.md

@@ -0,0 +1,165 @@
+# Knowledge authority and safe automatic memory
+
+> 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).
+
+Runtime policy reference. The current runtime extends this model with [Knowledge Schema v3 applicability](APPLICABILITY.md); authority and policy guarantees remain in force.
+
+## Core architecture
+
+Current targets are Knowledge Schema v3 and Project Schema v8. The authority
+checks are runtime policy checks, not a reinterpretation of existing knowledge.
+`context_policy` remains independent of category, priority and authority.
+
+`core/knowledge-authority.ts` evaluates transitions. `core/knowledge-write-policy.ts`
+applies that decision to an entire canonical transaction **before** the durable
+journal exists. Remember, deterministic and assisted Sync, imports, lifecycle
+transformations, maintenance, supersession and publication converge on
+`commitSyncTransaction`. Presentation does not decide authorization.
+
+The adapter checks paths/preimages, loads only referenced canonical bodies through
+the catalog, decides replacements before retirements, prevents protected rules from
+being hidden by unauthorized supersession, then uses the existing journal,
+checkpoint, index rebuild and recovery mechanism. Recovery replays an already
+validated decision; serialized authority or evidence does not authorize new work.
+
+The low-level `writeKnowledge` function is a trusted canonical-storage primitive
+used by fixtures, not by any production inference writer. Migration, restore,
+manual filesystem editing and arbitrary code running inside the Core process are
+trusted administrative capabilities, outside the model-facing security boundary.
+This is not a sandbox against a malicious plugin with filesystem/process access.
+
+## Authority and trust boundary
+
+| Classification | Meaning | How it is established |
+| --- | --- | --- |
+| `inferred` | Agent/session-derived knowledge | Automatic default |
+| `imported` | Imported source knowledge | Import adapter; relevant by default |
+| `legacy_inherited` | Behavior mechanically inherited from v1 | Existing migration, never a new agent promotion |
+| `explicit_user` | Rule attributed to an explicit user request | Model-mediated chat command or optional host adapter; the label is not authentication |
+| `reviewed` | Exact policy change attributed to a review | Core embedding capability; provenance alone does not authenticate a person |
+
+Classification is provenance, not a permission token or confidence score. Neither
+`kind: rule`, evidence with `kind: user_instruction`, existing prose, a model-written
+quote by itself, nor `approved: true` alone in tool arguments grants policy authority. The explicit Required chat command described below is a model-callable exception with bound content and request provenance. Existing
+source-session, observation and evidence references are retained.
+
+`withTrustedKnowledgeIntent` is an in-process, async-scoped capability bound to the
+resolved project, exact content/category/scope/priority/status, intended policy,
+auditable reference, and optionally exact source preimage. It expires when the
+operation completes, including detached async callbacks. It is not persisted or
+exposed as an MCP input. Entry points must bind the authorized operation; the engine cannot independently prove user intent relayed by an assistant or host.
+
+`createServer({currentUserRule})` optionally accepts a **host-supplied** verifier.
+It returns the current turn ID, actual user text, explicit mandatory intent and
+exact intended content/scope/importance. `rememberCurrentUserRule` checks binding
+and applies that intent without a second confirmation. No lexical classifier
+pretends to prove intent. Generic, missing, mismatched or unavailable attestations
+fall back to ordinary Remember when no explicit Required chat command is supplied. The stock stdio MCP transport does not provide authenticated user-turn intent.
+
+For a direct user request such as "remember: always reply in Russian", the assistant may call `prodero_remember` with `kind: "rule"`, `required: true`, and `userInstruction` containing the exact current request. This explicit command authorizes only the supplied rule through the same scoped writer boundary; it records `chat-user-request` provenance, not a fabricated host attestation. The assistant must not use this command for inferred lessons, imported documents or embedded instructions. No second confirmation is required. Missing request text or a non-rule kind is rejected. The default applicability is the current project; path rules remain scoped. Ordinary Remember and automatic learning retain their existing Relevant defaults.
+
+Use memory search and an exact `replaceId` to make an existing Relevant rule Required. The result reports its actual context policy. Open continues to load only applicable Required instructions; it does not include all Relevant rules.
+
+## Automatic versus reviewed transitions
+
+- New facts, decisions, lessons and inferred instructions are relevant/inferred.
+  Newly imported instructions are relevant/imported. New inferred criticality is
+  capped at important; critical remains distinct from required.
+- Category hints classify knowledge, never mandate delivery. Global instruction
+  candidates retain their existing pending lifecycle.
+- Relevant wording refinement, deduplication and provenance enrichment remain
+  automatic within the original scope and policy/authority ceiling.
+- Exact copies/publication retain existing policy and authority. Equal-policy,
+  equal-authority, equal-scope and equal-priority source clauses may be combined
+  losslessly; no new normative clause is granted by that combination.
+- Protected records include required, critical, explicit_user and reviewed
+  knowledge. Inference cannot change their policy, authority, scope, priority,
+  category, protected clauses or effective active status. Safe whitespace
+  normalization and exact clause-preserving consolidation remain possible.
+- Scope changes on existing inferred records are conservatively preserved too;
+  new replacements inherit a common source applicability boundary.
+- Unauthorized new promotion is downgraded to a safe relevant record. Ambiguous
+  automatic edits preserve the original; changed content can be retained as a
+  separate relevant Local record with a relationship to the original.
+- Exact requested protected mutations (maintenance/forget) fail before canonical
+  changes with `POLICY_REVIEW_REQUIRED`. A model-callable approval boolean cannot
+  select between incompatible authoritative states. Trusted Core intent can
+  authorize an exact change, including de-escalation.
+- Publication review authorizes the publication layer only. It never establishes
+  `reviewed`, upgrades relevant to required, or grants new criticality.
+
+Semantic equality is intentionally conservative: whole source clauses must be
+preserved. An LLM assertion of equivalence is not proof. Paraphrases that cannot be
+proven safe remain separate relevant knowledge, or require exact review when the
+caller explicitly requests changing the original rule.
+
+## Writers and lifecycle
+
+Remember saves an agent-selected rule as instruction/relevant/inferred. Generic
+“remember this” remains ordinary memory. An unsafe replacement reports the preserved
+source separately rather than falsely reporting that the original was replaced.
+
+Deterministic Sync and assisted reconciliation use the same transaction gate.
+Existing extractive validation, source verification, graph constraints and bounded
+retrieval remain in place. Model prompts are not the enforcement mechanism.
+A rejected protected rewrite can retain the new information locally without
+retiring its authoritative source. Checkpoints retain aggregate transition reasons.
+
+Memory Transformation applies the shared policy to proposed new records and skips
+unsafe replacement/archive links. Clean Local transformations stay automatic.
+Archive moves additionally validate the original source; moving to a new filename
+cannot bypass protected retirement checks. Reviewed publication and instruction
+optimization use exact policy validation at commit rather than silently applying
+a different policy from the reviewed plan.
+
+AI Studio classification is unchanged. Even historical text classified as an
+instruction becomes relevant/imported on new import. Import/publication approval
+is not approval to create a mandatory rule. Existing migrated records are untouched.
+
+## Review and presentation
+
+Core distinguishes `allowed`, `allowed_with_safe_fallback`, `review_recommended`,
+`review_required`, and `forbidden`, with reasons and an independent blocking flag.
+Optional recommendations are aggregate checkpoint/Sync diagnostics, not a forced
+queue, per-record approval popup, or permanent UI panel. There is no new memory
+review prompt during an ordinary session. A batch may contain ten inferred
+instructions and finish close/Sync/next Prepare without review.
+
+Prepare exposes `policyReadiness` and UI blocking state for an **applicable explicit
+required-policy contradiction or unresolved required dispute**. Merely matching
+rule titles or suggesting promotion does not block work. The session remains
+available; resolve the policy and retry Prepare with the same task/session. The
+agent must honor this structured readiness state; Curator cannot stop unrelated
+external tools from executing. Text and UI explain whether work must wait.
+
+Policy mutation errors expose the same structured blocking/preserved state through
+UI tools and the text gateway. Existing maintenance screens remain, but their
+model-callable `approved` flag cannot authorize an otherwise protected edit.
+The curation App adapter can grant exact reviewed mutations after validating saved
+review state. This is a workflow consistency boundary, not authenticated human
+consent. Optional host attestations are distinct from stock model-mediated chat
+and App paths; v0.1 does not require a trusted-host authorization subsystem.
+
+## Compatibility and deferred work
+
+Policy checks preserve existing protected metadata and use the current schema,
+applicability and migration boundaries. See [Knowledge Schema v2](KNOWLEDGE-SCHEMA-V2.md)
+for the historical policy-format migration and [Applicability](APPLICABILITY.md)
+for the current v3 representation.
+
+Optional future host attestations and richer normative-equivalence proofs are outside
+the v0.1 contract. Current importer and applicability behavior is documented separately. Arbitrary content semantics cannot be proven by a generic LLM;
+conservative retention is deliberate. Ordinary automatic inference does not grant Required policy. Exact chat commands,
+validated review adapters, mechanical legacy migration and equivalent existing
+policy use the current Core boundary. The connected agent can supply chat/review
+arguments; these checks cannot prove who intended them.
+
+## Verification
+
+Tests use temporary repositories, fixture records and in-memory MCP clients.
+Coverage includes ordinary Remember, ten inferred observations, deterministic and
+assisted Sync, protected source retention, escalation/de-escalation, trusted current
+turns, stale/wrong-project/expired intent, imports, lifecycle archive/replacement,
+publication, exact protected mutation errors, UI/text parity and conflict readiness.
+Existing migration, v2 round-trip, cache, recovery, instruction consolidation and
+full regression suites are also run. See [release verification](RELEASING.md) for reproducible validation.

package/docs/KNOWLEDGE-SCHEMA-V2.md

@@ -0,0 +1,150 @@
+# Knowledge Policy Schema v2
+
+Historical schema reference. The current runtime extends this model with [Knowledge Schema v3 applicability](APPLICABILITY.md); authority and policy guarantees remain in force.
+
+## Architecture and canonical format
+
+This transition introduced knowledge schema 2 on project schema 6. Current targets in
+`prodero.release.json` are project 8 and knowledge 3; project-local `.prodero/config.json` remains authoritative.
+The adjacent `knowledge-policy-1-2` compatible-semantic transition is registered in
+Core's existing migration engine. There is no separate conversion command or lock.
+
+Canonical Markdown frontmatter now includes:
+
+```yaml
+version: 2
+kind: knowledge
+category: instruction
+context_policy: relevant
+authority: inferred
+```
+
+Category describes the
+kind of knowledge. `context_policy: required` selects mandatory delivery when
+applicable; `relevant` uses ordinary retrieval and does not mean unimportant.
+Priority, critical status, scope and relevance score retain their existing meanings.
+All categories support relevant. Only instruction supports required in this phase.
+Decision/constraint/invariant required combinations are rejected, not auto-promoted.
+
+Core uses `version`, `contextPolicy`, `authority`. Record version is an explicit
+parser discriminator, not another independently evolving project version axis.
+Malformed v2 records missing version/policy/authority fail validation; project-bound
+readers also reject v1 records in projects declaring knowledge v2. Pure serializers
+have no project identity. Project-bound storage operations retain the Foundation's
+newer-project/newer-knowledge barrier.
+
+## Authority and trust boundary
+
+Authority values: `legacy_inherited`, `inferred`, `imported`, `explicit_user`,
+`reviewed`. They classify the provenance basis of a policy, not confidence, priority,
+or proof of authorization. Evidence stays in existing `evidence`, `sourceSessions`,
+`derivedFrom` and relationship fields; no second evidence system was added.
+
+No Phase 1A conversational, Sync or transformation writer grants explicit_user or
+reviewed merely from agent assertions, user_instruction evidence, or publication
+approval. Existing creation behavior uses inferred; imports use imported. Trusted
+canonical input can represent stronger classifications, but consumers must not treat
+that string as authenticated user intent. Phase 1B must establish the actual grant
+boundary. Remember still creates required instructions as before, with conservative
+inferred authority. This is intentional compatibility, not a completed safety model.
+
+## Mechanical migration and recovery
+
+Every canonical record in both memory layers and both monthly archives is converted,
+including historical/disputed records. Instructions become required; every other
+category becomes relevant, including critical decisions. All migrated authority is
+legacy_inherited. No model, content heuristics, scope inference or reclassification
+runs. Modern frontmatter receives only structural metadata; bodies and unrelated
+metadata are preserved. Legacy unstructured Markdown receives canonical defaults
+matching its compatibility reader. The converter checks complete parsed-record
+identity apart from the schema discriminator. Checkpoint preimages remain historical
+evidence, not live canonical records, and are not rewritten.
+
+Foundation planning/approval, full backup, staging, validation, cache rebuild,
+journal, config-last commit, history and rollback are reused. Versions advance only
+after staged v2 validates. Recovery restores preimages then retries. Current checks
+are no-ops. The release's previous Foundation runtime rejects knowledge 2 at storage;
+pre-Foundation runtimes reject project 6. This cannot protect arbitrary external
+editors that bypass Prodero's storage contract.
+
+## Readers, writers, retrieval and contracts
+
+The v1 compatibility reader alone derives policy from category. Normal v2 parsing
+uses explicit metadata. The transitional draft creation adapter preserves existing
+writer defaults until Phase 1B; its fallback never applies to parsed v2 records.
+Render/read/edit/archive/publication preserve policy and authority. Same-category
+replacements inherit source policy; mixed policies cannot be silently consolidated.
+Instruction optimization groups by policy/authority as well as existing boundaries.
+
+Prepare and Bootstrap share policy-based required applicability. Scope matching,
+ranking, overflow, token budgets and item limits are unchanged. The Markdown router's
+Required section now uses policy rather than global importance. Genuine instruction
+category behavior remains in consolidation, protected merge checks, candidate
+lifecycle, instruction editing/optimization, importer classification and category
+filters. These are not globally replaced with policy checks.
+
+MemoryIndex format 9 stores policy and authority, invalidating old disposable caches.
+Canonical Markdown remains authoritative. Snapshot JSON retains canonical fields.
+MCP exposes contextPolicy/authority on canonical records and summaries. The temporary
+instruction `enforcement` alias is derived exclusively from contextPolicy; `kind`
+continues to describe instruction category. Neither alias is canonical on disk.
+Bootstrap's alias is required because that collection contains required records only.
+
+Open/Prepare use the Foundation's temporary Knowledge update available view. The
+same approved Core action is available through UI, chat/text and CLI; no shell is
+needed. UI resumes the original tool call; text returns exact resumable arguments.
+After migration normal views are unchanged; legacy authority is not added as a badge.
+No new policy editor or promotion authorization surface is introduced.
+
+## Validation evidence
+
+Permanent tests use synthetic records plus focused round trips, malformed data, historical migration,
+selectors, cache deletion/rebuild, maintenance, publication, replacement, text resume,
+older-runtime barriers, failure injection and interrupted production migration.
+Foundation tests continue to cover UI approval, progress/resume, newer project
+schemas, plan immutability and ordered synthetic future migrations.
+
+## Phase 1B escalation paths (historical Phase 1A audit)
+
+These paths are now governed by [Knowledge authority](KNOWLEDGE-AUTHORITY.md).
+The following describes the Phase 1A baseline, not current runtime permissions.
+
+The following still require authority/intent enforcement, intentionally unchanged:
+
+- Remember `kind: rule` and replacements: agent-supplied assertions of user intent.
+- Session observations with `categoryHint: instruction` and deterministic Sync.
+- Assisted distillation/reconciliation and audit-created instruction candidates.
+- Memory Transformation/lifecycle creation that changes category into instruction.
+- Import source classification (including must/should/use/run rules) and apply paths.
+- Trusted direct Core draft writers, canonical manual edits, and future promotion APIs.
+- Policy changes across explicit supersession/reclassification boundaries; publication
+  approval must remain distinct from approval to establish mandatory authority.
+
+Global instruction candidates remain pending, and skill/instruction candidate review
+retains its current checks. Phase 1A adds metadata preservation, not a claim that all
+escalation routes are authorized. No applicability redesign, corpus cleanup, lexical
+reclassification, new required categories, budgets/item-limit changes, evidence
+verification, policy editor or complete authorization system is included.
+
+## Implementation map
+
+- `core/knowledge-policy.ts`: supported combinations, strict policy validation,
+  compatibility draft adapter and policy-preserving replacement helper.
+- `core/knowledge-migration.ts`, `core/migrations.ts`: production registry step,
+  current/archive traversal and mechanical equivalence validation.
+- `core/memory.ts`, `core/types.ts`, `core/memory-index.ts`: canonical persistence,
+  compatibility parsing, shared model and disposable index format 9.
+- `core/bootstrap.ts`, `core/context.ts`, `core/index.ts`: mandatory selection and
+  Required router labeling. No selection caps or applicability changes.
+- `core/consolidation.ts`, `core/knowledge-engine.ts`, `core/knowledge-lifecycle.ts`,
+  `core/promotion.ts`, `core/instruction-review.ts`: writer/merge preservation.
+- `core/imports.ts`: explicit imported classification with existing category logic.
+- `core/knowledge-provenance.ts`, `core/memory-transformation-bundle.ts`,
+  `core/skill-curation.ts`, `core/sync-transaction.ts`: project-aware validation at
+  additional read/write boundaries.
+- `test/knowledge-policy-v2.test.mjs`: focused production migration and v2 regressions.
+  Existing migration, project, scope and update tests use explicit format fixtures.
+
+All paths above are relative to `src/` except the test path. The existing MCP server,
+presentation model, UI handlers and CLI migration actions delegate to the same Core
+engine; Phase 1A does not fork those implementations.

package/docs/MIGRATIONS.md

@@ -0,0 +1,103 @@
+# Migration Foundation
+
+## Audit and reused mechanisms
+
+Before this change, `core/migrations.ts` provided ordered project migrations 1→5,
+canonical validation, backups, a recovery journal, cache invalidation, and rollback.
+`storage.ts` rejected newer project schemas, checked paths/symlinks, and wrote files
+with same-directory rename. `sync-transaction.ts` provided a shared process lock,
+stale-owner recovery, and a separate Sync preimage journal. Initialization and Prepare
+automatically migrated. Open loaded memory without first presenting compatibility.
+MemoryIndex, session index and graph have disposable cache formats; config uses a
+passthrough validator. MCP UI and text already share presentation contracts.
+
+This extends that migration engine; there is no second conversion or lock system.
+
+## Versions and registries
+
+`.prodero/config.json` is authoritative: `schemaVersion` describes project structure;
+`knowledgeSchemaVersion` describes canonical knowledge. Missing knowledge version
+means legacy format 1. Runtime targets come from `prodero.release.json`.
+Project transition 5→6 only records knowledge version 1. It preserves record bytes.
+The project bump also fences older, pre-foundation runtimes supporting only schema 5.
+No sessions/skills/config version axes are introduced.
+Project transition 6→7 refreshes the managed AGENTS.md block for text-only skill
+execution. Open/Prepare use the existing update review. The migration snapshots
+AGENTS.md, preserves text outside the managed block, commits it before the project
+version, and restores it on failure without overwriting concurrent user edits.
+Project transition 7→8 replaces the embedded block with a three-line reference to
+`prodero_instructions_read`. This text-only MCP tool reads `instructions/AGENTS.md`
+from its own installation, so dev/package switching needs no project edits. This is a one-time
+project migration using the same approval, backup and rollback flow. Subsequent
+instruction-only updates replace the packaged document and need no project schema
+bump or edits to consumer repositories. Project/knowledge format changes still
+require migrations.
+
+`MIGRATIONS` and `KNOWLEDGE_MIGRATIONS` contain adjacent transitions. Descriptors
+carry class, description, affected stores, transform and optional validation.
+Classes are structural, compatible-semantic and review-required. The latter is
+blocked until a migration-specific review resolver exists; `approved:true` never
+substitutes for semantic decisions. The knowledge registry contains the ordered compatible-semantic `knowledge-policy-1-2` and `knowledge-applicability-2-3` transitions. The current target is knowledge schema 3; see [Knowledge Schema v2](KNOWLEDGE-SCHEMA-V2.md) and [Applicability](APPLICABILITY.md).
+
+## Package installation stays separate
+
+`prodero update` updates only the verified npm package after terminal confirmation. It does not enumerate or migrate projects or change the selected dev checkout. After user restart/reconnect, Open/Prepare offer this existing migration gate only when project/knowledge formats require it. Chat update indicators and `prodero_update` provide terminal instructions, never package installation.
+
+## Planning, approval and continuation
+
+`planProjectMigration` reads metadata without creating directories, sessions, caches
+or recovering journals. It reports targets, ordered steps, backup policy, safety,
+review/block state, runtime identity and a metadata/registry plan hash.
+`applyProjectMigration` requires explicit approval bound to that plan; it rechecks
+under the shared writer lock. Current projects are idempotent no-ops.
+
+Open, lightweight/detailed status and Prepare inspect this plan before reading
+canonical knowledge. Current projects have no migration controls. Other states use
+one Core plan and one view-model in UI/text. `prodero_migrate` is also exposed through
+`prodero_text`. CLI `migrate status` plans; `migrate` is explicit approval to update
+(or restore an interrupted update). Review-required steps remain blocked.
+
+An interrupted Prepare returns a resumable request containing its exact original
+arguments. Migration preserves this request. The App invokes the actual original
+tool after success; text agents can immediately invoke the returned request. This
+is not a durable host task scheduler: following a client restart, the agent must use
+the model-visible request. No session is created before compatibility is resolved.
+
+## Transaction and recovery
+
+The existing shared lock excludes Sync/session/migration writers. A validated full
+backup includes config, indexes, both knowledge layers, archives, sessions, skills
+and checkpoints. Backups are outside disposable caches. A journal references the
+backup, its integrity digest and diagnostic history before transformation begins.
+Transforms and each transition's validation run in a separate staged project.
+
+Derived indexes are rebuilt against the target schema in staging. Commit installs
+canonical data and rebuilt indexes using atomic individual file replacements under
+the journal/read fence, then writes the new version last. Disposable cache stamps
+are revalidated by the usual loaders at their installed paths. This is a recoverable
+logical transaction, not an operating-system atomic directory swap. Failure restores
+the validated backup and invalidates derived caches. Interrupted transactions roll
+back deterministically before a new attempt. Backup corruption blocks recovery;
+Prodero never guesses missing preimages. Legacy v1 journals remain recoverable.
+Partial backup creation cannot change canonical data; orphan backups may be retained.
+History under `.prodero/.migrations` records IDs, versions, runtime, times, status and
+backup reference. These ignored diagnostic files are not schema authority.
+
+## Knowledge format 2
+
+Phase 1A registers knowledge 1→2 and makes explicit policy and conservative authority
+canonical. Existing instruction behavior is preserved mechanically. See
+[Knowledge Schema v2](KNOWLEDGE-SCHEMA-V2.md) for the schema and trust boundary.
+Foundation runtimes reject newer knowledge versions at the common storage barrier;
+pre-foundation runtimes reject project schema 6. UI metadata diagnostics remain
+available without interpreting newer knowledge. Direct low-level serializers are
+not project-bound storage APIs.
+
+## Boundaries
+
+Recovery is rollback-and-retry, not arbitrary user rollback after later writes.
+Backups are local recovery copies, not an off-machine disaster-recovery service.
+No power-loss/fsync durability guarantee beyond the existing filesystem primitives
+is added. External tools editing `.prodero` outside Prodero's lock are unsupported.
+No global project registry, bulk migration or backup retention policy is provided.
+Migration review is distinct from the curation review workflow.

package/docs/PRIVACY.md

@@ -0,0 +1,28 @@
+# Privacy and local storage
+
+## v0.1 agent and Git trust model
+
+v0.1 trust model: Local Knowledge is Git-ignored working state, not a security boundary against the connected agent. Versioned Knowledge is Git-shareable project state; the agent may create, promote and maintain it. Review/preview/approval steps are workflow safeguards, not authenticated human authorization; `approved:true` does not prove human consent. Curator does not commit or push. Users must review repository changes before committing or pushing.
+
+The connected agent can read both layers and can supply the approval arguments itself. Exact hashes, revision checks, App-only visibility and reviewed-plan flags check workflow consistency; they do not authenticate a person. This applies equally to UI, text and generic/plugin dispatch. Do not store information here on the assumption that the agent cannot place it in Git-shareable files.
+
+## Storage and retention
+
+Prodero canonical knowledge is plaintext local/project storage. Git-ignore rules keep normal learning out of new commits; they are not access control or encryption. Anyone who can read your working tree, filesystem backups or Git history may be able to read its contents.
+
+- Local memories, inferred skill candidates and dismissed proposals live under `.prodero/local/`. Sessions and checkpoints are also ignored. These are durable data, not disposable cache.
+- Runtime setup installs directory-wide Git exclusions for `local/`, `sessions/`, `checkpoints/`, `.cache/`, `.transactions/`, `.backups/` and `.migrations/` before creating runtime state. These cover interrupted writes and unknown filenames, with only the root `sessions/.gitkeep` and `checkpoints/.gitkeep` placeholders allowed. Atomic `*.tmp-*` files anywhere under `.prodero/` are also ignored. Existing user ignore rules and files are retained; ignore rules do not untrack files already in Git or prevent deliberate force-adds/ignore overrides.
+- On POSIX platforms, Curator creates managed private directories with `0700` and files with `0600`, including atomic scratch files, Local knowledge/skills, sessions, checkpoints, caches, reviews/reasoning, transactions and migration recovery copies. Runtime setup tightens existing private store roots; checked access tightens the addressed private path, without recursively changing unrelated children. Dormant legacy files can retain old modes behind an owner-only parent until accessed. Linked files and other owners' inodes are not chmod targets; inability to enforce permissions fails the operation. Versioned files retain ordinary repository permissions. On Windows, POSIX chmod is skipped and native filesystem ACLs/inheritance apply; no owner-only Windows ACL guarantee is claimed. These modes are not encryption or a boundary against the same OS user, the connected agent or administrators.
+- Versioned Knowledge lives in `.prodero/memory/`; explicitly created, promoted or imported skills live in `.prodero/skills/` (including legacy candidates). These are Git-shareable working-tree files, not necessarily committed or pushed. Normal session learning produces Local Knowledge; promotion, maintenance, skill creation, imports and selected Sync operations can change Versioned state.
+- Ordinary `forget` retires Local Knowledge. It rejects Versioned Knowledge and asks for explicit repository maintenance. **Forget is not secure erase**: historical records, source sessions, checkpoints, recovery journals/backups, filesystem backups and Git history may retain content. Retiring a local superseder can make the unchanged versioned record relevant again.
+- Secret screening rejects high-confidence credential patterns before normal memory/session/skill writes, publication and optional provider calls. Diagnostics omit the detected value. Obvious placeholders and environment-variable examples are supported. Detection is conservative, can reject legitimate examples, and is **not a universal DLP guarantee**. Do not enter credentials into Prodero. Manually edited or older unsafe canonical content is rejected when read; it is not silently deleted or scrubbed.
+- Optional host sampling sends selected project content to the host/model for consolidation, promotion or skill curation. The adapter requests no additional host context, but the host/model's retention and privacy policies apply. Deterministic mode does not use this sampling path. MCP context/search results intentionally deliver selected knowledge to the calling agent, whose own policies also apply.
+- Installed executable `.cjs` plugins are trusted local code, not a security sandbox. They may have the process's filesystem/network capabilities. Review plugins before installation; core screening cannot constrain arbitrary plugin behavior or another process editing the files.
+
+If a real credential was stored, revoke or rotate it with its issuer. Review canonical data, recovery copies and publication history before deciding what to remove. Deleting `.cache/` or calling `forget` alone does not resolve an exposure. Prodero does not rewrite Git history automatically.
+
+## Import integrity hashing
+
+Importer semantic ingestion retains its bounded text selection and common secret screening. Integrity digests additionally hash eligible ordinary files outside that selection to detect unrelated edits, but exclude recognized sensitive paths, private Curator runtime trees and Git-ignored files. An explicitly selected, screened Git-ignored legacy document can still participate as exact evidence, independently of tree hashing. Internal canonical-state integrity includes Local memory/skills/archive, sessions and checkpoints to protect concurrent-change and receipt checks; reviews, caches, transactions and backups are outside that snapshot.
+
+Digest/snapshot passes have hard count, byte, depth, entry and time bounds and stream content instead of buffering whole files. This is not complete DLP: content-only credentials in ordinary eligible filenames can be read while hashing, and Git consults configuration/ignore metadata. No claim is made about unchanged excluded files. See [the detailed importer contract](../plugins/migrate_ai_studio/README.md#integrity-scope-and-limits-plugin-170).