@sentropic/focus 0.5.0-rc.3 → 0.5.0-rc.5

package/schemas/focus-editing-manifest.v1.schema.json

@@ -0,0 +1,167 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sentropic:focus:FocusEditingManifest:1.0.0",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "manifestId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "documentRef": {
+      "type": "string",
+      "minLength": 1
+    },
+    "baseHash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "manifestBaseHash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "fields": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "nodeId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "targetRef": {
+            "type": "string",
+            "minLength": 1
+          },
+          "field": {
+            "enum": [
+              "markdown",
+              "question",
+              "recommendedAnswer",
+              "context",
+              "label",
+              "body",
+              "consequence"
+            ]
+          },
+          "contentFormat": {
+            "enum": [
+              "text/plain",
+              "focus.markdown.p0@1"
+            ]
+          },
+          "blockKind": {
+            "enum": [
+              "prose",
+              "question",
+              "option"
+            ]
+          }
+        },
+        "required": [
+          "nodeId",
+          "targetRef",
+          "field",
+          "contentFormat",
+          "blockKind"
+        ]
+      }
+    },
+    "paragraphs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "nodeId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "targetRef": {
+            "type": "string",
+            "minLength": 1
+          },
+          "field": {
+            "enum": [
+              "markdown",
+              "question",
+              "recommendedAnswer",
+              "context",
+              "label",
+              "body",
+              "consequence"
+            ]
+          },
+          "paragraphId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "blockKind": {
+            "const": "paragraph"
+          },
+          "parentId": {
+            "type": "null"
+          },
+          "order": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "range": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "start": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "end": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "unit": {
+                "const": "utf16"
+              }
+            },
+            "required": [
+              "start",
+              "end",
+              "unit"
+            ]
+          }
+        },
+        "required": [
+          "nodeId",
+          "targetRef",
+          "field",
+          "paragraphId",
+          "blockKind",
+          "parentId",
+          "order",
+          "range"
+        ]
+      }
+    },
+    "retiredParagraphIds": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    }
+  },
+  "required": [
+    "schemaVersion",
+    "manifestId",
+    "documentRef",
+    "baseHash",
+    "manifestBaseHash",
+    "fields",
+    "paragraphs",
+    "retiredParagraphIds"
+  ]
+}

package/skills/focus/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: focus
-version: 1.0.0
+version: 2.0.0
 description: Prepare and review readable decision dossiers that trace the owner's request, expose real stakes and offer short explicit choices. Read-only snapshots; no decisions, signatures, amendments or Track writes.
 category: decision
 tools: []
@@ -14,6 +14,23 @@ Method capability: `sentropic.focus.decision-dossier`. Prepare a
 (`schemas/decision-dossier-document.v1.schema.json`). This instruction-only
 skill grants no tools or write authority.
 
+For supporting evidence, select the explicit v2 template with the freshly built
+checkout CLI: `node packages/h2a/dist/bin.js focus template --evidence -o dossier.json`,
+then `node packages/h2a/dist/bin.js focus build dossier.json -o dossier.html`.
+It declares `schemaVersion: 2` and uses the separate schema
+`urn:sentropic:focus:DecisionDossierDocument:2.0.0`. Omitting the discriminant
+selects unchanged v1. Old consumers refuse v2; never strip evidence to bypass that.
+Store original bytes once in `sources` (canonical base64, original SHA-256 and byte
+size). Origins are frozen provenance data, never URLs/paths fetched by the reader.
+Use typed `citations`, section/option `citationRefs`, `evidenceGroups`, and collapsed
+`annexes`; keep choices, material risks and reservations in the primary decision.
+Summaries consume its reading budget; raw evidence volume and estimated consultation
+are disclosed separately. Hashes prove byte identity, not truth or owner approval.
+Embedded H1 supports offline text/capture consultation, complete-source search,
+original download and return to context. It does not advertise H2 DS geometry/CDN
+or H3 linked exploration. DS owns renderer controls inside the canvas; Focus
+declares choices/reference bindings. Do not author coordinates or invent a toolbar.
+
 A dossier serves the owner's intention. Ask the owner to choose a path or
 manage a real problem whose risk concerns them. Handle routine technical
 implementation within existing authority. Double review must find missing
@@ -130,3 +147,35 @@ Markdown conversion and HTML sanitization are explicit host hooks. Unsupported
 nodes, unknown fields, enabled interactions, duplicate ids, unresolved targets
 and forged evidence refuse with field diagnostics; never render an incomplete
 dossier as complete.
+
+## Manual edit-return preview (separate from snapshot authority)
+
+The new `@sentropic/focus/editing` subpath defines versioned sidecar manifests,
+paragraph diffs and a pure reconciler. The portable editor is not qualified yet:
+it awaits the published DS `RichTextEditor`, then offline browser/distribution
+and reactivity gates. Do not advertise snapshot cards as editable.
+
+Before an editable production, retain its exact source, manifest and opaque
+producer/generation/request references. The checkout command
+`node packages/h2a/dist/bin.js focus feedback retain <source.json> --state <dir>
+--producer <id> --generation <id> --request <id>` prepares that manual state.
+Only an explicitly selected state/source is authoritative; never open paths from
+`provenance.source`, notes or the return payload.
+
+Within the consumer's existing mandate, manually consume a complete return with
+`focus feedback apply <return.json|yaml> --state <dir>`. Validate version, digest,
+correlation and baseline mapping; re-read the current source, then check the
+durable lineage before paragraph preconditions. Keep exact wording and notes.
+An empty superseding return can revoke earlier corrections. Late superseded,
+forked or order-indeterminate returns cannot resurrect them. Preserve drafts on
+conflict; distinguish processed, source-applied, rebuilt and recorded in Track.
+Receipts identify the consumed return/changes and actual source digests; replay
+also identifies the previous outcome.
+
+This preview publishes source JSON under a cooperating single-writer lock and
+journal. It does not rebuild presentation or write Track. Revalidate/rebuild the
+new presentation separately before presenting it. Original comprehension
+evidence remains evidence about the original version. Live routing, amendment
+translation, snapshot registry edit capabilities and policy defaults remain
+unqualified; this skill grants no additional tool or write authority. Details:
+`docs/focus/document-editing.md` in the source repository.