@prodero/curator 0.0.0-stage → 0.1.0

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,99 @@
+# 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).
+
+## 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).

package/docs/RECOVERY.md

@@ -0,0 +1,56 @@
+# Storage recovery
+
+Canonical knowledge, sessions, skills and checkpoints are durable project data. Normal learning and inferred proposals remain in ignored storage; the promotion review workflow writes Git-shareable Versioned Knowledge. Review/approval is a workflow safeguard, not human authentication; Curator does not commit or push. See [Privacy](PRIVACY.md).
+
+| Location | Role | Safe to delete as cache? |
+| --- | --- | --- |
+| `.prodero/memory/`, `local/memory/`, `sessions/`, `skills/`, `local/skills/`, `checkpoints/`, `config.json` | Canonical data | No |
+| `.prodero/.cache/` | Rebuildable memory/session indexes and graph | Yes, after old-runtime migration backups have been relocated as described below |
+| `.prodero/index.md`, `local/index.md` | Generated routers | Rebuildable; root router may include Local skill metadata. This repository ignores it; inspect other projects before sharing |
+| `.prodero/.transactions/` | Writer lock, pending Sync/migration journal | No |
+| `.prodero/.backups/` | Migration recovery snapshots, excluded by root rules and its own `.gitignore` | No |
+| `.prodero/.migrations/` | Migration history, excluded by root rules and its own `.gitignore` | No |
+
+A clone or worktree normally has no ignored `local/` or `.cache/`. Prodero recreates missing runtime directories without rewriting tracked placeholders. It does not reconstruct lost Local Knowledge: deleting `local/` from an existing working tree deletes canonical local data, not a cache.
+
+Runtime setup also upgrades missing Git-ignore rules in existing projects before new runtime writes. Sessions/checkpoints are excluded by directory contents, not filename extensions, while their root `.gitkeep` placeholders remain trackable. Atomic and interrupted-write remnants stay ignored, including `*.tmp-*` beside Versioned files. This does not delete recovery artifacts, change atomic-write/recovery behavior, or untrack existing user files.
+
+## Invalid canonical files
+
+LF and CRLF are supported. Modern knowledge, session and skill metadata is validated, including IDs, lifecycle state and timestamps. Unknown statuses, stripped modern metadata, invalid configuration and malformed checkpoints produce file-oriented diagnostics instead of active defaults. Deliberately supported legacy Markdown remains readable; old date-ID `checkpoint-ready` sessions are recognized explicitly. Files are not silently repaired or rewritten merely because they were read.
+
+Correct a damaged canonical file from Git or a known backup after stopping writers. Do not remove it as a cache fix. Prodero rejects symlinks in its storage paths and IDs that could escape their directory; replace unintended links with the intended ordinary directories only after inspecting them.
+
+## Interrupted Sync
+
+Both deterministic and assisted Sync validate a complete write plan, persist `.transactions/pending.json`, then apply atomic file replacements with the immutable checkpoint last. The next Sync recovers that journal before processing more evidence. `prepare` runs this recovery through automatic Sync. A crash after the checkpoint but before journal cleanup is also recoverable and does not process the same snapshot twice.
+
+To recover, keep `.transactions/` and canonical files intact, stop competing writers, and run `prodero sync-sessions --root=/absolute/project` or ask the agent to prepare the project. Missing or structurally invalid cache entries rebuild from canonical data. Deleting `.cache/` does not delete the Sync journal.
+
+If a canonical file was independently edited after the journal was prepared, recovery stops with the affected path and preserves the journal. Inspect the file and its journal before/after hashes; restore the intended preimage or already-applied result before retrying. Never discard the journal merely to clear an error.
+
+## Interrupted migration
+
+Migrations use the same per-worktree writer exclusion as Sync and session writes. All supported migration steps and canonical input are checked before applying a migration; each attempt has a complete recovery snapshot. The schema is written only after the steps, post-validation and cache invalidation succeed.
+
+Backups now live under `.prodero/.backups/schema-<version>-<id>/`. Existing `.cache/migration-backups/` from older runtimes are relocated into `.backups/legacy-cache-<id>/` when initialization/preparation/migration next accesses the project. Run one of those operations with the hardened runtime before deleting an old runtime's cache if it contains recovery backups.
+
+A failed migration restores its snapshot and reports its backup path. A process interruption retains `.transactions/migration.json`. Open and Prepare present a recovery action before normal work. Approving recovery restores the snapshot; the next plan offers the update again. Explicit CLI initialization retains its legacy recovery behavior. This also handles a rollback interrupted while restoring `config.json`. New session writes fail explicitly while a migration recovery journal remains, so a later rollback cannot erase an acknowledged observation.
+
+If automatic restoration fails, stop all Prodero writers and retain both the journal and its referenced backup. Restore the snapshot's `config.json`, `index.md`, `memory/`, `local/`, `sessions/`, `skills/`, `archive/` and `checkpoints/` together, preserving their original presence/absence. Do not mix snapshots. Verify the result before clearing the migration marker and retrying. Never copy an uninspected or symlinked backup over project data.
+
+## Concurrency and limits
+
+Session creation, record and close share a filesystem lock across processes. Session mutations wait up to five seconds for a writer; a timeout reports failure, never success. Acknowledged observations remain in the file, and a closed session cannot be reopened by a late record. An empty repeated close remains successful; repeated close with nonempty final entries is explicitly rejected, so callers should inspect the session after an uncertain response rather than replay that final batch blindly.
+
+A dead PID owner can be reclaimed. An ownerless/invalid lock or interrupted lock-recovery guard fails conservatively: after stopping all writers, inspect `.transactions/lock` and `.transactions/lock-recovery` before removing stale lock directories. PID reuse is intentionally handled conservatively rather than risking deletion of a live owner's lock.
+
+These guarantees are verified with local filesystem process-crash, injected I/O-error and multiprocess tests. They do not provide a multi-file snapshot to unrelated readers while a journal is being applied, nor protection against hostile processes replacing the directory topology during filesystem operations. Network filesystems and sudden hardware/power loss have not been certified. Do not edit storage concurrently with migration/recovery.
+
+Migration Foundation adds independent knowledge compatibility, staged transforms, backup integrity, diagnostic history and resumable Open/Prepare actions. See [Migration Foundation](MIGRATIONS.md).
+
+### Private recovery permissions
+
+On POSIX platforms, new migration backups, staging trees, history, transaction journals and locks use owner-only directories (`0700`) and files (`0600`), including interrupted-write artifacts. Runtime setup tightens existing private store roots without recursively chmod-ing their children; existing files are tightened when checked/accessed or replaced. Do not interpret this as a historical cleanup or ACL audit. Symlinks, multiply linked files and another owner's data are not permission-repair targets.
+
+Migration backups preserve shared-file mode metadata separately from their private content copies. Successful commits preserve existing shared target modes; rollback restores saved shared modes (older backups use their original source modes). Versioned stores are not made private merely because they passed through staging. Curation simulations live beneath the private, ignored `.cache` tree and are removed by the normal simulation cleanup. Windows uses native ACL behavior rather than POSIX chmod.

package/docs/RELEASING.md

@@ -0,0 +1,40 @@
+# Release candidate gate
+
+From a clean checkout on Node 22.14+ (22.x):
+
+```sh
+npm run release:gate
+```
+
+The gate copies tracked working files plus non-ignored new files into a clean temporary checkout (never node_modules/dist), runs `npm ci`, build, tests, pack, then installs the tarball into a separate prefix with production dependencies only. Its standalone runner resolves SDK dependencies from that installation. CLI, stdio MCP, bundled resources, the knowledge lifecycle, Git boundaries, restart and synthetic manual upgrade preservation are checked. `npm test` rebuilds first; ordinary `npm pack` runs the full tests through prepack. The gate's pack skips lifecycle scripts only after its build/tests have passed.
+
+For host-integration verification, use a fresh temporary directory outside the real user home, an isolated HOME and Codex/Claude/XDG configuration, and no inherited host registrations. Keep custom `PRODERO_GATE_OUTPUT` paths outside real-home ancestry: normal workspace checks inspect ancestors and can correctly report `HOST_SCOPE_CONFLICT`. Never disable those checks or alter real settings to make a smoke test pass.
+
+CI allows 45 minutes per matrix job. Child-command output is streamed to the console and written continuously to evidence logs, so cancellation retains partial test diagnostics. The limit remains finite; a timeout is not a passing check.
+
+Gate outputs and the tarball remain in the printed temporary directory for inspection. Nothing is published. CI repeats the gate on macOS/Ubuntu and the declared minimum/latest Node 22. Remote CI results must actually pass before those targets are certified.
+
+A protocol runner is not a real host. Independently connect a primary host to the **installed artifact** in a synthetic Git project, run open/init/prepare/record/close/next prepare/remember/search/edit/restart, inspect tool results and Git status, and record host/runtime/artifact versions. Review promotion outcomes and approve only the intended synthetic fixture publication. Apps rendering needs its own host check.
+
+## Install the artifact for review
+
+Before the first npm publication, install the generated tarball instead of a registry release:
+
+```sh
+npm install --global /absolute/path/prodero-curator-0.1.0.tgz
+prodero install
+```
+
+Use the isolated host environment described above for automated verification. For a deliberate real-host check, review the installer’s configuration changes and restart the selected coding agent. Open a synthetic project and type `prodero`. The tarball includes the compiled server, Apps and plugin resources; no source checkout or development dependencies are needed.
+
+## Final human publication checklist
+
+1. Independently audit the RC, review diffs, run the full gate on the exact committed tree and obtain green declared CI matrix runs. Record artifact SHA-256 and primary-host evidence.
+2. Review the intended public Git tree **and history** for private content. Ignoring runtime files today does not remove old commits. Decide explicitly what history to publish; never rewrite it automatically.
+3. Confirm ownership of npm scope `@prodero`, package/repository identity `@prodero/curator` / `prodero/curator`, and permission to release. A registry 404 does not establish scope ownership.
+4. Create/configure the intended public repository only with explicit approval. Enable Issues and private vulnerability reporting; verify the links and update any identity/channel changes in docs and package metadata.
+5. Confirm version `0.1.0`, MIT license, changelog date, preview limitations and exact artifact contents. Obtain explicit approval for publication.
+6. Authenticate npm with the account's required 2FA/provenance policy. Publish the **reviewed tarball**, not an unreviewed rebuild: `npm publish /absolute/path/prodero-curator-0.1.0.tgz --access public`.
+7. Verify external `npm install --global @prodero/curator@0.1.0`, `prodero --version` and `prodero check-update`. Only with separate approval create/push the `v0.1.0` tag and release notes or announcements.
+
+The automated gate does not publish or push and does not change the source repository history. It creates an isolated disposable test commit in its temporary checkout. Package upgrades do not move project knowledge. Back up the full `.prodero` directory before preview upgrades; `.cache` is disposable, migration recovery backups are not.