@convesoft/mara 0.2.0 → 0.3.0-alpha.0

package/README.md

@@ -5,12 +5,13 @@ designs, decisions, and other durable facts stable identities, types, relations,
 validation, and deterministic retrieval. A CLI and stdio MCP server share the
 same operations, including discovery of narrative outside items.
 
-Mara 0.2.0 provides schema format 2 with flavour
-selection guidance, an engineering template, and unified `search`, `get`, and
-`related`. Start with the [0.2 migration guide](docs/migration-0.2.mara.md) for
-an existing project. The [0.1.0 documentation](https://github.com/convesoft/mara/tree/v0.1.0)
-describes the older released interface; use documentation and skill from the
-same revision as your executable.
+This checkout adds typed inline relationships, metadata inverse aliases,
+symmetric relationships, and occurrence inspection to the unified `search`,
+`get`, and `related` workflow.
+It requires schema format 3 and emits discovery format 2. Follow the
+[relationship migration contract](docs/relations.mara.md) for existing projects.
+Published 0.2.0 still uses schema format 2 and discovery format 1; use its
+[documentation](https://github.com/convesoft/mara/tree/v0.2.0) and matching skill.
 
 ## Run Mara
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@convesoft/mara",
-  "version": "0.2.0",
+  "version": "0.3.0-alpha.0",
   "description": "Structured project knowledge CLI and MCP server",
   "author": "Aliaksei Raketski",
   "license": "MIT OR Apache-2.0",
@@ -18,10 +18,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@convesoft/mara-linux-x64-gnu": "0.2.0",
-    "@convesoft/mara-linux-arm64-gnu": "0.2.0",
-    "@convesoft/mara-darwin-x64": "0.2.0",
-    "@convesoft/mara-darwin-arm64": "0.2.0"
+    "@convesoft/mara-linux-x64-gnu": "0.3.0-alpha.0",
+    "@convesoft/mara-linux-arm64-gnu": "0.3.0-alpha.0",
+    "@convesoft/mara-darwin-x64": "0.3.0-alpha.0",
+    "@convesoft/mara-darwin-arm64": "0.3.0-alpha.0"
   },
   "files": [
     "bin/mara.cjs",

package/plugin.json

@@ -15,5 +15,5 @@
     "mcp",
     "agent-skill"
   ],
-  "version": "0.2.0"
+  "version": "0.3.0-alpha.0"
 }

package/skills/mara/SKILL.md

@@ -10,8 +10,11 @@ When MCP is unavailable, use an available Mara CLI invocation with `--format jso
 for structured results. The same operation selection, authoring, continuation,
 and validation rules apply to both surfaces.
 
-This skill targets the 0.2 interface: schema format 2 and unified `search`,
-`get`, and `related`. Use the skill shipped with the selected executable or
+This skill targets the current 0.3 development interface: schema format 3,
+discovery format 2, relationship format 1, validation format 1, and trace
+format 1. Typed inline relationships, inverse aliases, symmetric edges,
+external targets, graph policies, YAML current-state rules, and matrices are
+implemented. Use the skill shipped with the selected executable or
 the same source revision. If an older installation exposes a different
 interface, report the mismatch and use its matching guidance; do not silently
 change the version pin or substitute removed commands.
@@ -71,12 +74,12 @@ Use the selected project's declarations, including custom flavours. Keep
 supporting narrative as Markdown when it does not need an independent identity;
 search/get/related can still discover, read, and navigate it.
 
-Schema format 2 requires all four guidance keys directly on every flavour:
+Schema format 3 retains all four guidance keys directly on every flavour:
 a nonblank `description`, a nonempty list of nonblank `use_when` entries,
 an `avoid_when` list (`[]` is valid), and a `distinguish_from` mapping (`{}` is
 valid). Distinction targets must be other declared flavours with nonblank
 explanations. When asked to migrate format 1, edit the existing schema in place,
-set `format_version: 2`, and supply meaningful guidance. Preserve custom
+set `format_version: 3`, and supply meaningful guidance. Preserve custom
 flavours, prefixes, fields, relations, document bytes, IDs, and MIDs; do not
 reinitialize or replace the schema with a template. Require `valid:true` from
 both `schema_validate` and `project_validate` (CLI `schema validate` and
@@ -107,9 +110,39 @@ inspect `<command> --help` for positional arguments and options.
 | Change title, custom fields, or body | `item_update` | `item update` |
 | Relocate an item; preserve ID and MID | `item_move` | `item move` |
 | Change human ID and supported references; preserve MID | `item_rename` | `item rename` |
+| Inspect an edge and its source occurrences | `relation_get` | `relation get SOURCE RELATION TARGET` |
 | Add or remove an existing item's typed edge | `relation_add` or `relation_remove` | `relation add`, `relation remove` |
 | Delete an item; resolve reported relation/mention blockers | `item_delete` | `item delete` |
 | Check an item or whole-project integrity | `item_validate` or `project_validate` | `item validate`, `project validate` |
+| Inspect coverage for selected roots | `trace_matrix` | `trace matrix` |
+
+Validation (`project_validate`, `item_validate`, `schema_validate`) returns
+`valid`, `evaluation_complete`, `summary`, `diagnostics`, and output
+continuation. Match diagnostic `code` and `severity`, not message text.
+Warnings do not invalidate a complete result; configuration/source failures
+remain errors. Current-state rules load from explicit YAML files enabled by
+project format 2 and `[rules]` with `format_version = 1` and `files = [...]`.
+Run `schema_validate` to check definitions, then `project_validate` or
+`item_validate` to evaluate policy. Status/owner fields are project-defined;
+templates and existing projects gain no policies automatically. Schema relation
+`cardinality` and `acyclic` declarations impose structural graph policies when
+present. Policy failures do not block structured edits.
+Invalid schemas now return the common envelope with `valid:false`, not an MCP
+tool error. Counts are null when the schema cannot load. Diagnostic `path` and
+`line` alias `location`; project-owned configuration paths are relative and
+unavailable coordinates are omitted.
+
+All three validation operations accept `limit` (1–100, default 20) and `cursor`;
+CLI uses `--limit` and `--cursor`.
+Continue unchanged inputs until `has_more:false`; summary
+and validity cover the full target before pagination and reporting paths.
+With configured rules, invalid corpus prerequisites skip policy evaluation,
+including item-targeted checks. Fix the original diagnostics and run validation
+again. `evaluation_unavailable` never means a policy pass. There is no logical
+work counter; finite shape/path restrictions and output pagination remain.
+Invalid arguments, stale cursors,
+I/O preventing a result, and oversized indivisible output return
+`{format_version:1,error:{code,message}}` with MCP `isError:true`.
 
 Use mutations only when the user has asked to change project knowledge. Choose
 the structured mutation for the semantic change. An invalid-argument error calls
@@ -136,11 +169,12 @@ accept `limit`.
 
 Call `related` with `{"reference":"<selected reference>"}` for direct schema
 relations, mentions, and containment. It returns `node` and
-`connections:[{relation,direction,neighbour,source}]`; pass a selected
+`connections`; pass a selected
 `neighbour.reference` to `get` or another `related` call. Each call follows only
 direct connections; there is no automatic expansion or hops option.
 
-Use `direction:"incoming"` or `"outgoing"`; omission includes both. Related
+Use `direction:"incoming"`, `"outgoing"`, or `"symmetric"`; omission includes all.
+Direction is canonical even when a relation filter uses an inverse alias. Related
 `relations` accepts `schema:name` and `builtin:name`, with short names allowed
 only when unambiguous in the vocabulary. Related `flavours` selects item
 neighbours only. JSON represents containment as `contains` with direction;
@@ -161,8 +195,8 @@ Item MIDs retain durable identity. Search and related default to 20 entries
 and accept `limit` from 1 through 100; related counts connections, including
 different connections to the same neighbour. The byte budget may shorten pages.
 
-Unified discovery responses use `format_version: 1`, independently of schema
-format 2 and the application version. Inspect `node.kind` (item, section, block,
+Unified discovery responses use `format_version: 2`, independently of schema
+format 3 and the application version. Inspect `node.kind` (item, section, block,
 or document); only items have ID/MID/flavour. Item list retains its item-only
 response. On upgrade, discard old cursors and update parsers for the mixed
 `results`, consecutive `content`, and `connections` shapes above.
@@ -173,6 +207,86 @@ then `"${mara_cli[@]}" --project /absolute/project --format json get '<reference
 Use `related '<reference>'` for connections, `--relation builtin:mentions` to
 select explicit mentions, and `--cursor '<next_cursor>'` for continuation.
 
+## Inspect and change relationships
+
+Schema lookup accepts inverse aliases and returns the canonical declaration,
+`requested_name` and `inverse`. Lists show canonical names with aliases and
+symmetry. Alias endpoint validation exchanges source and target first.
+
+`related` returns each semantic schema edge once, with canonical `relation`,
+endpoint-facing `label`, `direction`, `neighbour`, `edge` and `occurrence_count`.
+Builtin connections retain `source`; use `relation_get` for schema locations.
+Symmetric edges are excluded by incoming/outgoing filters. Directed self-edges
+appear once as outgoing when direction is omitted. Different relation kinds
+remain distinct. Item-list/search filters still select items with authored
+metadata or inline assertions; canonical and alias filters select the same kind.
+
+`relation_get {source,relation,target,limit?,cursor?}` returns the canonical
+`edge`, total `occurrence_count` and a page of `occurrences`. Each occurrence
+retains its author, spelling, source location and opaque `reference` selector.
+Default limit is 20, maximum 100, with a 65,536-byte budget. Continue unchanged
+until `has_more:false`; re-inspect after source/schema changes.
+
+Add rejects an edge already asserted anywhere, including inverse, symmetric
+and inline ID/MID equivalents. Direct source may intentionally repeat assertions.
+`relation_remove {source,relation,target}` removes every occurrence across
+included files. Supply `occurrence` from inspection to remove exactly one.
+Stale or mismatched selectors fail without writes. Results report
+`changed_occurrences`, `remaining_occurrences` and `edge_exists`. Inline removal
+demotes internal `[[relation:target]]` to `[[target]]` and external assertions
+to Markdown autolinks, preserving surrounding prose. The retained internal
+mention still blocks deletion of its target.
+
+Author `[[relation:ID]]`, `[[relation:MID]]`, or
+`[[relation:external:https://host/path]]` in an item body using a canonical
+schema name or inverse alias. External targets require `external: true` on the
+relation declaration; Mara preserves their authored address and never fetches it.
+No whitespace, labels or nested markup is allowed
+inside the token. These assertions share metadata edge identity and produce no
+builtin mention. Code, raw contexts and escaped openings remain literal; typed
+tokens outside item bodies have no typed meaning. Unknown relations, malformed
+tokens and invalid targets in supported contexts fail validation. Use body
+creation/update to author inline assertions; relation add writes metadata.
+
+For a format-1/2 or relation-vocabulary migration, follow
+`docs/migration-0.3.mara.md` with the matching 0.3 executable. The supported
+workflow is manual: save a Git checkpoint or project copy, review the complete
+source diff, then require complete, valid schema and project validation. Mara
+has no schema migration preview/apply command; `project_transaction_rollback`
+does not undo manual edits. Preserve MIDs and unrelated declarations, fields,
+prose and links. Existing relations remain directed with no alias unless the
+schema explicitly changes. Review newly meaningful typed tokens, alias
+collisions, all authored spellings and YAML rule paths before changing names.
+When removing an inverse alias, inspect the canonical edge, reauthor it on its
+canonical source if needed, remove inverse metadata, and demote inverse inline
+tokens to bare mentions when preserving prose navigation. Never replace an
+inverse name with the canonical name on the same item: that can reverse a
+directed edge while validation still passes. Verify the canonical endpoints
+after migration. Do not treat a direction, endpoint or meaning change as a
+rename.
+
+## Inspect trace coverage
+
+Use `trace_matrix` (CLI `trace matrix`) for a read-only view of selected roots.
+Select roots with `ids`, `flavours`, `fields`, `paths`, or `all:true`; pass either
+enabled rule IRIs in `rules` or a request-local `check:{files,shape}`. CLI uses
+repeatable `--id`, `--flavour`, `--field KEY=VALUE`, `--path`, and either
+`--rule` or `--check-file` with `--shape`. Do not mix the two evaluation modes.
+The check files supply shapes for this request only; they do not enable policy
+for project validation. A named rule uses its own applicability and selection
+within the requested roots.
+
+Read each result state (`passed`, `failed`, `not_applicable`, `unavailable`),
+the check and edge records, source locations, and per-evaluation `summaries`.
+An external endpoint is terminal; an edge outside root selection can still
+contribute to a check. Known rule failures are matrix data, while
+`evaluation_complete:false` means the view could not be fully evaluated.
+Continue with unchanged inputs and `next_cursor` until `has_more:false`;
+restart after source, schema, or rule changes. CLI defaults to Markdown for
+this command; `--format json` returns trace format 1. MCP returns JSON and
+accepts `render:"markdown"` for the matching Markdown page. The output is a
+projection, not a saved source of project knowledge.
+
 ## Preserve authored references
 
 Use `[[ID]]`/`[[MID]]` in item bodies or narrative for item mentions, and
@@ -204,7 +318,7 @@ The shared `:key: value` source syntax does not make these interchangeable:
 - **Typed relations:** `justifies` and `satisfies` are relations, not custom
   fields. `fields:[{"key":"justifies","value":"REQ-EXAMPLE"}]` is invalid.
   Use creation `relations` or explicit relation operations; inspect allowed
-  source/target flavours first. Incoming backlinks are derived, never authored.
+  source/target flavours first. Use canonical names or declared inverse aliases; reverse navigation is derived.
 
 CLI equivalents are `--title`, repeatable `--field KEY=VALUE`, update
 `--clear-field KEY`, and creation `--relation NAME=TARGET`. Never pass a relation