@agent-native/core 0.130.2 → 0.131.3

package/corpus/templates/content/docs/product/capabilities/content.source.sync-policy.md

@@ -0,0 +1,161 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.source.sync-policy"
+name: "Source sync policy"
+user_promise: "Each connected Source declares one plain-language policy for refresh and write-back: View only, Keep in sync, or Review before write-back."
+primary_user_job: "Connect work that remains trustworthy without deciding on every edit whether it should leave Content."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "configured"
+dependencies: ["content.source.catalog", "content.event.committed"]
+related_features:
+  [
+    "content.feature.trust-your-connected-sources",
+    "content.feature.bring-your-local-work",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "A Source has one inspectable policy, applies only authorized compatible changes through its declared ownership routes, stops real conflicts for review, and records receipts without confusing queued, failed, or unreviewed work with synchronization."
+proof_requirements:
+  [
+    "Policy selection and enforcement through shared Actions and the interface",
+    "Per-field or representation ownership, access intersection, base revisions, deterministic routing, conflict, retry, and receipt behavior",
+    "End-to-end View only, Keep in sync, and Review before write-back workflows with provider-side verification",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Source sync policy
+
+## Why this exists
+
+Connected work should not turn every ordinary edit into a synchronization
+dialog. People need to understand whether Content is only showing a Source,
+keeping compatible work aligned automatically, or preparing a deliberate
+outbound review. A familiar access role such as **Can view** answers who may
+read Content; it does not answer whether Content may write to a provider.
+
+## Example workflow
+
+An editor connects a collection whose body is provider-owned and whose
+annotations are Content-owned. They choose **Review before write-back**. A
+body edit becomes one typed outbound change set with its base revision, while
+an annotation saves in Content immediately. After review, the provider accepts
+the body change and Content records a receipt. If the provider changed the
+same body incompatibly, automatic application stops and the editor sees a
+typed conflict rather than a plausible but incorrect "synced" state.
+
+## Product contract
+
+### Configure once, follow predictably
+
+- Every Source declares exactly one user-facing policy: **View only**, **Keep
+  in sync**, or **Review before write-back**. Adapters may offer only the
+  policies their certified capabilities can honor.
+- **View only** refreshes authorized inbound Source changes into Content and
+  never writes Content-originated changes back to that Source.
+- **Keep in sync** automatically applies compatible, authorized inbound and
+  outbound changes. It is not permission for last-writer-wins: a real conflict
+  stops automatic application for review.
+- **Review before write-back** may refresh inbound changes according to the
+  adapter contract, but bundles Content-originated changes into a typed,
+  reviewable outbound change set before provider mutation.
+- The policy configures synchronization, not human access. An operation must
+  satisfy Content access, Source scope and approval, adapter capability,
+  provider grant, field or representation ownership, and the selected policy.
+  Passing one layer never implies the others.
+
+### Ownership routes one edit once
+
+- Each Source-backed value declares its Source/property or representation
+  identity, baseline, writable directions, and conflict rule. A Source can own
+  a body while Content owns comments, view configuration, or other native
+  metadata on the same Page.
+- An ordinary edit follows that declared route without repeated prompts. A
+  Database membership or a Query projection never fans the edit out to other
+  Sources; intentional multi-destination work belongs to an explicit Rule,
+  mirror, or Automation with per-destination outcomes.
+- A computed, aligned, or otherwise ambiguous projection is read-only until an
+  authorized unambiguous route is declared. Creating through a composite
+  surface requires one inferable target or a choice of target.
+- Provider lifecycle transitions, including publication, remain separate
+  guarded operations. Editing content or successfully syncing it never
+  silently changes Draft, Published, or another provider lifecycle state.
+
+### Conflict, retry, and receipts tell the truth
+
+- Outbound work carries the relevant base revision and identity. The adapter
+  checks freshness before applying it; an incompatible upstream change becomes
+  a visible conflict or rebase/review state, not a silent overwrite.
+- A queued change is waiting for authority or transport and is not synced. A
+  reviewable change is not sent until approved. A failed or unknown outcome is
+  distinguishable from a provider-confirmed success.
+- Each attempt records actor, origin, policy, affected representations, base,
+  destination outcome, and a provider receipt when available. Retrying uses
+  stable operation identity so a recovered request does not duplicate effects.
+
+## Boundaries and non-goals
+
+- The Sources catalog owns Source discovery, approval, scope, and connection
+  metadata. Adapters own provider-specific operations and certification.
+- Human roles and Page/Database access are owned by the access capabilities;
+  this policy adds no second permission system.
+- Portable representations and unknown-data preservation belong to faithful
+  round-tripping. This record decides when a permitted write may travel, not
+  how every provider format is encoded.
+- This Capability does not promise every adapter automatic bidirectional sync,
+  offline write queue, lifecycle transition, or generic conflict UI.
+
+## Acceptance stories
+
+### Keep compatible work synchronized without accidental publication
+
+Given an authorized writable Source with **Keep in sync** and compatible
+field ownership, when an editor changes a supported Source-owned field, then
+the adapter applies the change once, records an Event and provider receipt,
+and leaves provider publication state unchanged.
+
+### Stop a genuine conflict instead of overwriting it
+
+Given a queued outbound change based on revision A and an incompatible provider
+change since A, when synchronization resumes, then Content marks the work as a
+typed conflict for review, preserves both inputs, and does not report it as
+synced or retry it as if the base still matched.
+
+### Keep reviewable write-back reviewable
+
+Given a Source configured for **Review before write-back**, when an authorized
+editor changes two compatible provider-owned representations, then Content
+creates one typed change set with both changes and their bases; no provider
+mutation occurs until the required review decision succeeds.
+
+## Current evidence
+
+Existing change sets, guarded writes, source metadata, local synchronization,
+and audit records provide useful donor machinery. They do not yet prove one
+plain-language policy across adapters, ownership-aware routing everywhere,
+reliable receipt semantics, or the full interface workflow. This Capability
+therefore remains `approved_shape`.
+
+## Proof plan
+
+1. Exercise each policy through shared Actions and the interface with
+   authorized and unauthorized read, write, review, and lifecycle requests.
+2. Verify per-field and representation ownership, projected-value routing,
+   multi-membership non-fan-out, base checks, retries, idempotency, and durable
+   receipts under refresh, disconnect, and restart.
+3. Create compatible concurrent changes and incompatible conflicts for at least
+   two independently certified adapters; verify neither generic behavior nor a
+   provider success is inferred from the other.
+4. Run access, approval, grant, capability, and policy intersection tests
+   through searches, Queries, agents, UI edits, and background work.
+
+## Open questions
+
+- The advanced presentation of directional read, watch, and write controls is
+  still open, provided it cannot contradict the three plain-language policies.
+- The common conflict-resolution vocabulary and retention rules for provider
+  receipts need design alongside the review surface.

package/corpus/templates/content/docs/product/capabilities/content.system.dependencies.md

@@ -0,0 +1,80 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.system.dependencies"
+name: "Task dependencies"
+user_promise: "Parent/subtask and blocked/blocking relations with constraints"
+primary_user_job: "Express what contains or blocks work and see trustworthy consequences across project and planning Views."
+kind: "workflow"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.relationship.edge", "content.expression.language"]
+related_features:
+  [
+    "content.feature.run-projects-your-way",
+    "content.feature.plan-work-across-time",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Task hierarchy and blocking are typed Relationships with inverse, cardinality, self-edge, and cycle rules; expressions and planning consume those edges rather than copied dependency fields."
+proof_requirements:
+  [
+    "Typed dependency and hierarchy create, inverse, cardinality, self-edge, cycle, and deletion coverage",
+    "Access-safe Relationship Actions, expressions, rollups, history, and recovery coverage",
+    "Project, List, Timeline, and agent-context workflow with unavailable or stale relations",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Task dependencies
+
+## Why this exists
+
+Projects need to say what blocks what without making a task dependency engine that drifts
+away from the rest of Content.
+
+## Example workflow
+
+An editor marks one task as blocking another and groups subtasks beneath a parent. The
+same typed edges inform task Views, expressions, and later scheduling surfaces.
+
+## Product contract
+
+- Parent/subtask and blocked/blocking are canonical typed Relationships with declared inverses and constraints.
+- Creation and edits use the shared Relationship Action, access checks, history, and recovery.
+- Expressions and scheduling consume canonical edges; Views project them without copying dependency truth.
+- Cycles, self-relations, cardinality, missing endpoints, and inaccessible endpoints receive explicit policy.
+
+## Boundaries and non-goals
+
+Relationships own edges; schedule constraints consume them. This is not a Page-parent
+system, a hidden status mutation engine, or a parallel task graph.
+
+## Acceptance stories
+
+### Reject a forbidden cycle
+
+Given a relationship type that forbids cycles, when an editor creates a blocking cycle,
+then the shared Action rejects it with an actionable explanation and no partial edge.
+
+### Project an authorized blocker
+
+Given a task whose blocker is inaccessible, when a viewer opens a task View, then no
+endpoint title, count, or inference leaks through dependency presentation.
+
+## Current evidence
+
+Relationship and expression primitives are prerequisite substrate; no complete task
+dependency workflow is proven. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Test inverse, self-edge, cardinality, cycle, deletion, and concurrent relationship edits.
+2. Verify access closure, expressions, history, agent context, and recovery.
+3. Exercise List, project, Timeline, unavailable-relation, and keyboard workflows.
+
+## Open questions
+
+Which dependency types are blessed by the initial Task template needs template design.

package/corpus/templates/content/docs/product/capabilities/content.system.my-tasks.md

@@ -0,0 +1,75 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.system.my-tasks"
+name: "My Tasks"
+user_promise: "“My Tasks” as an access-scoped dynamic saved view"
+primary_user_job: "See the work assigned to me across eligible task memberships without maintaining a copied personal queue."
+kind: "workflow"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.system.task-project", "content.view.query"]
+related_features: ["content.feature.run-projects-your-way"]
+roadmap_boundary: "feature"
+acceptance_summary: "My Tasks is a fast, access-scoped saved View using current-user expressions across eligible task memberships and preserving each task's canonical origin."
+proof_requirements:
+  [
+    "Current-user expression, multi-membership, sort, filter, and canonical-origin coverage",
+    "Access-safe result, count, cross-context policy, Action, and agent-context coverage",
+    "Real-interface fast List, empty, stale, unavailable, reload, and recovery workflow",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# My Tasks
+
+## Why this exists
+
+Assigned work should gather itself, not require a person to keep a second queue in sync.
+
+## Example workflow
+
+A contributor opens My Tasks, filters to due work, edits one task, and opens its Project.
+The task remains its one canonical record in the source Database.
+
+## Product contract
+
+- My Tasks is a saved dynamic View using current-user expressions over eligible canonical task memberships.
+- It evaluates access before results, counts, sort, filters, agent context, or cross-context display.
+- Every row retains its task and project origin; edits use ordinary shared Actions.
+- Empty, unavailable, stale, and revoked results are distinct from a complete empty queue.
+
+## Boundaries and non-goals
+
+The Task template defines task meaning and Queries define result execution. My Tasks is
+not a copied inbox, assignment authority, or implicit cross-context search.
+
+## Acceptance stories
+
+### Gather assignments without duplication
+
+Given assigned tasks in two eligible projects, when a person opens My Tasks, then each
+authorized canonical task appears once according to saved View semantics.
+
+### Remove revoked work
+
+Given access to a task is revoked, when My Tasks refreshes, then that task and any count
+or preview inference disappear from the person and agent context.
+
+## Current evidence
+
+No current-user cross-membership query and fast List proof is recorded. This Capability
+remains `approved_shape`.
+
+## Proof plan
+
+1. Test current-user expressions, memberships, origin, filters, sort, and canonical edits.
+2. Verify access, policy, counts, cross-context behavior, and agent disclosure.
+3. Exercise fast List, empty, stale, unavailable, reload, and recovery workflows.
+
+## Open questions
+
+The default inclusion rule for unassigned and delegated tasks needs template design.

package/corpus/templates/content/docs/product/capabilities/content.system.project-status.md

@@ -0,0 +1,77 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.system.project-status"
+name: "Project status"
+user_promise: "Project status updates and rollups as ordinary Content views/pages"
+primary_user_job: "Understand a project's current state and next concern from canonical tasks and updates without a separate reporting system."
+kind: "workflow"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies:
+  ["content.system.task-project", "content.view.grouping-aggregation"]
+related_features: ["content.feature.run-projects-your-way"]
+roadmap_boundary: "feature"
+acceptance_summary: "Project Pages and ordinary Views compose canonical task relationships, access-safe rollups, status updates, schedules or reminders, and suitable renderers."
+proof_requirements:
+  [
+    "Task/project relation, status update, rollup, and canonical drill-in coverage",
+    "Access-safe aggregation, schedule/reminder policy, Actions, history, and recovery coverage",
+    "Real-interface project status, empty/stale/unavailable, renderer, and agent-context workflow",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Project status
+
+## Why this exists
+
+A status page should tell a truthful story from work already happening, not become an
+orphaned dashboard that someone must remember to reconcile.
+
+## Example workflow
+
+A lead opens a Project Page, reads its latest update and access-safe task rollup, drills
+into a concerning group, and schedules a reminder through the project's ordinary rules.
+
+## Product contract
+
+- Project status is composed from canonical Task/Project relations, Pages, Views, and access-safe aggregates.
+- Status updates remain ordinary attributable Content with history and permissions.
+- Rollups and drill-in evaluate access before measures, labels, counts, reminders, exports, or agent context.
+- Empty, stale, unavailable, and partially complete inputs are represented truthfully.
+
+## Boundaries and non-goals
+
+Task templates own task shape; grouping owns measures. This is not a separate reporting
+warehouse, management-only data model, or inferred status authority.
+
+## Acceptance stories
+
+### Read a safe project rollup
+
+Given a Project with private tasks, when a viewer opens its status, then rollups and
+counts include only authorized task information and drill-in remains scoped.
+
+### Publish an update canonically
+
+Given an authorized project editor, when they add a status update, then it is an ordinary
+attributable Content change with history and no copied dashboard record.
+
+## Current evidence
+
+No complete project status composition, aggregation, reminder, and renderer proof is
+recorded. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Test task/project relations, updates, rollups, drill-in, and status history.
+2. Verify access, reminders, exports, agents, stale inputs, and recovery.
+3. Exercise project Page and renderer workflows under empty and unavailable conditions.
+
+## Open questions
+
+The initial status vocabulary and reminder integration policy need template design.

package/corpus/templates/content/docs/product/capabilities/content.system.research-workspace.md

@@ -0,0 +1,80 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.system.research-workspace"
+name: "Research workspace Template"
+user_promise: "A blessed editable research template composes Sources, Notes, Projects, reading queues, citations, capture, and synthesis views over one Content datastore"
+primary_user_job: "Adapt a research system to my practice while keeping sources, notes, citations, and synthesis connected to their canonical evidence."
+kind: "workflow"
+state: "exploring"
+publicness: "public"
+availability: "universal"
+dependencies:
+  [
+    "content.template.graph",
+    "content.research.annotation",
+    "content.research.citation",
+  ]
+related_features: []
+roadmap_boundary: "supporting"
+acceptance_summary: "An editable research Template composes generic sources, notes, projects, reading queues, citations, capture, and synthesis Views without a parallel research engine."
+proof_requirements:
+  [
+    "Template instantiation, editable provenance, and source/note/project/citation composition coverage",
+    "Access-scoped search, capture, annotation, citation, links, backlinks, and source-policy coverage",
+    "Real-interface reading, synthesis, export, unavailable-source, and recovery workflow",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Research workspace Template
+
+## Why this exists
+
+Research benefits from a coherent starting shape, but the shape must remain editable and
+must not seize custody of connected originals.
+
+## Example workflow
+
+A researcher instantiates the Template, captures a source-backed note, adds an annotation
+and citation, connects it to a project, and opens a synthesis View with provenance intact.
+
+## Product contract
+
+- The research workspace is an editable Template composition over generic Content primitives.
+- Sources declare truth and write-back policy; notes, citations, annotations, links, and Views retain canonical identity.
+- Search, capture, synthesis, export, and agent context are access-scoped and provenance-aware.
+- Source unavailability, sync staleness, deletion, and citation failure report honestly and recoverably.
+
+## Boundaries and non-goals
+
+Research primitives own annotations and citations; the Template is not a new research
+database, provider lock-in, or a claim that every source can be written back.
+
+## Acceptance stories
+
+### Adapt without losing provenance
+
+Given an instantiated research Template, when a researcher changes its Views or schema,
+then source notes and citations retain their canonical provenance and policy.
+
+### Synthesize authorized evidence
+
+Given mixed-access sources, when a researcher opens a synthesis View or asks an agent,
+then only authorized evidence and citations are available to the result.
+
+## Current evidence
+
+This record remains `exploring`; no complete generic research composition is proven.
+
+## Proof plan
+
+1. Test Template instantiation, edits, provenance, Sources, notes, citations, and projects.
+2. Verify access, source policy, search, export, agents, stale data, and recovery.
+3. Exercise capture-to-synthesis and unavailable-source workflows in the real interface.
+
+## Open questions
+
+The initial blessed template contents and source-adapter selection remain exploratory.

package/corpus/templates/content/docs/product/capabilities/content.system.task-project.md

@@ -0,0 +1,76 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.system.task-project"
+name: "Blessed Task and Project Template"
+user_promise: "Blessed editable Task/Project template over Content"
+primary_user_job: "Start a useful project system quickly, then adapt Tasks and Projects without forking into a separate task product."
+kind: "workflow"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.template.graph", "content.view.fast-capture"]
+related_features: ["content.feature.run-projects-your-way"]
+roadmap_boundary: "feature"
+acceptance_summary: "An editable Task/Project Template composes fast capture, dynamic Views and defaults, typed relations, Rules, status rendering, and History over canonical Content objects."
+proof_requirements:
+  [
+    "Template install, editable schema/View provenance, Task/Project creation, and fast-capture coverage",
+    "Relations, dynamic filters/defaults, Rules, status renderer, history, access, and recovery coverage",
+    "Real-interface project workflow from capture through status, reload, and agent context",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Blessed Task and Project Template
+
+## Why this exists
+
+People need a credible place to start projects, then room to make the system fit the work
+without being trapped in a parallel task engine.
+
+## Example workflow
+
+A team instantiates the Template, captures a task from a List, assigns it to a Project,
+uses a status View, and later adjusts the template's Properties and Views for its practice.
+
+## Product contract
+
+- The Template forks editable Task and Project configuration with provenance, not a possessed shared product type.
+- Tasks, Projects, relations, Rules, status rendering, History, and Views use canonical Content objects and Actions.
+- Dynamic filters and creation defaults are contextual helpers, never hidden validation or source-of-truth copies.
+- Access, source policy, deletion, stale state, and recovery retain ordinary Content behavior.
+
+## Boundaries and non-goals
+
+Templates compose primitives; dependencies and scheduling have separate contracts. This is
+not a fixed task taxonomy, a proprietary workflow engine, or a permission bypass.
+
+## Acceptance stories
+
+### Start then adapt
+
+Given a new workspace, when an editor instantiates the Template and later changes a View,
+then canonical task/project identity and template provenance remain intact.
+
+### Capture into a project
+
+Given an authorized fast List, when a person captures a task and assigns its Project,
+then shared Actions apply defaults, Rules, history, and access without creating a duplicate.
+
+## Current evidence
+
+Existing Template and Database machinery are donor substrate, but the complete Task/Project
+workflow is not yet proven. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Test instantiation, provenance, editable schema and Views, and fast capture.
+2. Verify relations, Rules, defaults, status, history, access, deletion, and recovery.
+3. Exercise capture-to-project-to-status through UI and agent context after reload.
+
+## Open questions
+
+The initial Task/Project Property set and opinionated Views need Template design.

package/corpus/templates/content/docs/product/capabilities/content.template.governance.md

@@ -0,0 +1,76 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.template.governance"
+name: "Template governance"
+user_promise: "Find and adopt a reusable working system with clear ownership, approval, version, provenance, and access."
+primary_user_job: "Choose a reusable system with visible ownership and approval."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.template.graph", "content.access.page-database"]
+related_features:
+  [
+    "content.feature.share-how-your-organization-works",
+    "content.feature.put-your-organizations-know-how-to-work",
+    "content.feature.evolve-systems-safely",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Template governance provides private, organization-approved, and published catalogs with stable identity, ownership scope, inspectable content, versioning, approval, discovery, provenance, and access-aware adoption."
+proof_requirements:
+  [
+    "Catalog scope determines discoverability, editing, approval, and audit; it does not bypass object access.",
+    "Templates are inspectable snapshots of ordinary primitives, not opaque packages or a second authority system.",
+    "Adoption preserves origin and version choice; a later update is handled through review rather than possession.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Template governance
+
+## Why this exists
+
+A reusable system is only trustworthy when adopters can inspect who made it, what version they are taking, and who approved it. Discovery must not turn a catalog entry into a permission bypass.
+
+## Example workflow
+
+Kai inspects an organization-approved editorial Template, then adopts its version into a workspace with visible owner, approval, and provenance.
+
+## Product contract
+
+- Catalog scope determines discoverability, editing, approval, and audit; it does not bypass object access.
+- Templates are inspectable snapshots of ordinary primitives, not opaque packages or a second authority system.
+- Adoption preserves origin and version choice; a later update is handled through review rather than possession.
+
+## Boundaries and non-goals
+
+- `content.template.graph` owns snapshot/instantiation; Template updates own adopted-instance diffs and selective application.
+- Governance does not grant access to referenced objects, auto-update instances, or turn Templates into opaque packages.
+
+## Acceptance stories
+
+### Scope does not bypass access
+
+Given one referenced object is inaccessible, when a person inspects or adopts the Template, then inspection/adoption does not leak it.
+
+### Make approval history visible
+
+Given a new version is published, when an adopter opens catalog detail, then adopters distinguish draft, approved, and adopted versions without auto-update.
+
+## Current evidence
+
+`docs/product/features/content.feature.share-how-your-organization-works.md` names Template substrate; no unified catalog, approval action, or adoption implementation exists.
+
+## Proof plan
+
+1. Create private/org/published entries with scope, owner, version, provenance.
+2. Test discovery, approval, audit, and edit permissions.
+3. Adopt under mixed access without leaking hidden references.
+4. Hand updates to Template update workflow.
+
+## Open questions
+
+Publisher-role policy remains open.