mirai-graph 1.3.0 → 2.1.0

package/standard/projection-views.md

@@ -1,69 +0,0 @@
-# Projection Views
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-A full Mirai Graph can become too dense for direct human review. Projection views
-are bounded generated views that expose the part of the graph needed for a
-specific decision, task or review.
-
-Projection views are control surfaces. They help people and AI systems inspect
-readiness, risk, evidence and next actions without treating the generated view
-as the source of truth.
-
-## Common View Types
-
-- `readiness_view`: current readiness and blockers;
-- `risk_view`: risks, unsafe actions and required gates;
-- `owner_routing_view`: owner domains, capabilities and routing paths;
-- `evidence_view`: evidence coverage and unsupported claims;
-- `gate_view`: governance gates, verdicts and missing approvals;
-- `adoption_view`: Mirai Graph adoption level and next action;
-- `runtime_view`: runtime policy status, fallback and context refs;
-- `learning_view`: feedback, proposals, evaluations and approved updates.
-
-## Required Fields
-
-A projection view should record:
-
-- `id`;
-- `view_type`;
-- `source_graph`;
-- `generated_at`;
-- `purpose`;
-- `included_objects`;
-- `included_relations`;
-- `evidence`;
-- `limitations`;
-- `next_actions`.
-
-## Authority Boundary
-
-A projection view is generated context. It should not become canonical graph
-state unless an implementation explicitly records an approved update.
-
-Projection views may reveal gaps. They should not silently fill those gaps.
-
-## User Value
-
-Projection views are important because they make Mirai Graph usable for repeated
-management work:
-
-- what is ready;
-- what is blocked;
-- who owns the next step;
-- which evidence supports a claim;
-- which gate must happen before action;
-- what changed since the previous review.
-
-## Limited Claim
-
-A projection view supports this limited claim:
-
-```text
-The implementation generated a bounded, task-specific view from graph state.
-```
-
-It does not prove that the graph is complete or that the recommended action is
-safe to execute.

package/standard/recovery-resume.md

@@ -1,49 +0,0 @@
-# Recovery And Resume
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-Recovery and resume rules make governed work resumable after interruption,
-context loss, failed commands, dirty worktrees, missing access or failed
-validation without relying on chat memory.
-
-## Resume Principle
-
-Resume from durable artifacts:
-
-- workflow or process record;
-- launch or reservation record;
-- branch and commit state;
-- validation result;
-- evidence pack;
-- sync proposal;
-- blockers;
-- next safe command;
-- rollback option.
-
-Do not resume by guessing from conversation history.
-
-## Required Resume Record
-
-A resume record should include:
-
-- current state;
-- last good commit or durable checkpoint;
-- current branch or workspace id;
-- target object or work scope;
-- launch/reservation reference;
-- last validation result;
-- evidence status;
-- blockers;
-- next safe command;
-- rollback option;
-- whether human confirmation is required.
-
-## Schema
-
-Machine-readable resume records can be validated with:
-
-```text
-schemas/recovery-resume-record.schema.json
-```

package/standard/relation-model.md

@@ -1,149 +0,0 @@
-# Mirai Graph Relation Model
-
-Status: 1.1 stable standard section
-
-## Purpose
-
-The relation model defines typed links between Mirai Graph objects.
-
-Relations make system dependencies, evidence links, governance boundaries and
-growth paths explicit.
-
-## Relation
-
-A relation is a typed directional connection from one object to another.
-
-Example:
-
-```json
-{
-  "id": "relation.feature.notify_after_approval.depends_on.feature.approval_flow",
-  "type": "depends_on",
-  "source": "feature.notify_after_approval",
-  "target": "feature.approval_flow",
-  "readiness": "draft",
-  "evidence": ["source.notification_delivery"],
-  "profile": "software_specification"
-}
-```
-
-## Minimum Fields
-
-A Mirai Graph relation should include:
-
-```json
-{
-  "id": "relation.unique_id",
-  "type": "depends_on",
-  "source": "object.source_id",
-  "target": "object.target_id",
-  "readiness": "draft",
-  "evidence": [],
-  "profile": "core"
-}
-```
-
-## Field Semantics
-
-### `id`
-
-A stable identifier for the relation.
-
-### `type`
-
-The relation category. Core relation types should be standardized; profiles may
-add domain-specific relation types.
-
-### `source`
-
-The object where the directed relation starts.
-
-### `target`
-
-The object where the directed relation ends.
-
-### `readiness`
-
-The maturity state of the relation.
-
-### `evidence`
-
-Evidence supporting the relation.
-
-### `profile`
-
-The profile that defines or specializes the relation.
-
-## Core Relation Types
-
-Initial core relation types:
-
-- `depends_on`;
-- `supports`;
-- `blocks`;
-- `implements`;
-- `evidences`;
-- `contradicts`;
-- `governs`;
-- `requires_approval_from`;
-- `generates`;
-- `derived_from`;
-- `supersedes`;
-- `belongs_to`;
-- `related_to`.
-
-Project Technology context traversal also standardizes:
-
-- structure: `contains`, `specializes`;
-- mandatory closure: `requires`, `governed_by`, `validated_by`;
-- sources: `documented_by`, `implemented_by`;
-- interaction: `hands_off_to`, `conflicts_with`.
-
-These names are domain-neutral. A consumer may present them with its own user
-vocabulary, but canonical traversal uses the shared relation types.
-
-## Relation Boundary Rules
-
-A relation should be created when the connection changes how the system is
-understood, governed, implemented or evaluated.
-
-A relation should not be created when:
-
-- the link is merely decorative;
-- the relation type is unclear;
-- there is no source and target object;
-- it embeds a private source detail that should remain outside public graph
-  state;
-- it is generated but not accepted into canonical state.
-
-## Directionality
-
-Relations should be directional unless the relation type explicitly defines
-symmetry.
-
-Example:
-
-`feature.notify_after_approval depends_on feature.approval_flow`
-
-does not mean:
-
-`feature.approval_flow depends_on feature.notify_after_approval`
-
-## Evidence And Confidence
-
-The initial draft requires evidence links but does not yet define a confidence
-field. Future versions may add:
-
-- confidence;
-- review status;
-- reviewer;
-- source type;
-- extraction method.
-
-## Open Questions
-
-- Should relation confidence be required?
-- Should relation IDs be generated or human-authored?
-- Should `related_to` be allowed in mature canonical graphs, or only during
-  early graph-seed work?
-- How should contradictory relations be represented and resolved?

package/standard/risk-control-matrix.md

@@ -1,53 +0,0 @@
-# Risk Control Matrix
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-A risk control matrix maps known risks to detection signals, prevention
-mechanisms, gates, evidence requirements, recovery actions, escalation rules
-and owner roles.
-
-It is designed for graph-governed projects where AI-assisted or multi-agent work
-can otherwise create false readiness, source-of-truth drift, unsafe runtime
-behavior or conflicting changes.
-
-## Required Shape
-
-Every risk row should include:
-
-- risk id and description;
-- severity;
-- detection signal;
-- prevention mechanism;
-- gate or validator;
-- evidence requirement;
-- recovery action;
-- escalation rule;
-- owner role.
-
-## Severity Model
-
-- `critical`: can compromise safety, source of truth, ownership or release.
-- `high`: can break architecture, boundaries or implementation claims.
-- `medium`: can cause rework, stale planning or evidence gaps.
-- `low`: can confuse review without blocking work by itself.
-
-## Default Recovery Pattern
-
-```text
-stop writes
--> capture current state
--> identify last good checkpoint
--> classify risk
--> restore scope or evidence
--> escalate if ownership is unclear
-```
-
-## Schema
-
-Machine-readable risk matrices can be validated with:
-
-```text
-schemas/risk-control-matrix.schema.json
-```

package/standard/route-explanation.md

@@ -1,35 +0,0 @@
-# Route Explanation
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-A route explanation records why a graph-managed federation selected a primary
-owner, companion capabilities, gates and fallbacks for a request.
-
-It is meant to make routing auditable before any runtime action starts.
-
-## Required Meaning
-
-A route explanation should include:
-
-- request summary;
-- primary owner;
-- companion capabilities;
-- rejected nearby candidates with reasons;
-- required gates;
-- required raw-source fallbacks;
-- route execution evidence reference;
-- confidence and known gaps;
-- runtime preflight reference when the route is high-risk.
-
-## Boundary
-
-Route explanation is not authorization.
-
-```text
-explained route != permission to execute
-explained route != permission to rewrite canonical sources
-```
-
-High-risk routes should link to a runtime preflight result before execution.

package/standard/route-regression.md

@@ -1,33 +0,0 @@
-# Route Regression
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-Route regression compares router behavior before and after a learning proposal,
-router update or federation graph change.
-
-## Result Shape
-
-A route regression result should include:
-
-- before route result reference;
-- after route result reference;
-- diff summary;
-- per-fixture route diffs;
-- regression status.
-
-Recommended statuses:
-
-```text
-improved
-unchanged
-regressed
-blocked
-insufficient_evidence
-```
-
-## Boundary
-
-Route regression is evidence for review. It does not prove semantic completeness
-or authorize graph-only runtime.

package/standard/routing-fixtures.md

@@ -1,54 +0,0 @@
-# Routing Fixtures
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-Routing fixtures test whether a graph-managed router selects the expected
-owner, companions, gates and fallback behavior for known scenarios.
-
-They are especially useful for negative routing cases where a nearby generic
-owner would be unsafe.
-
-## Negative Fixtures
-
-Fixtures should cover routes that must not collapse into a simpler route:
-
-- production or live infrastructure;
-- customer-visible writes;
-- credentials, secrets or private data;
-- legal, commercial or scientific claims;
-- owner-source rewrites;
-- platform architecture or migration decisions.
-
-## Forbidden Route Shapes
-
-Use `forbidden_route_shapes` when a skill can be a valid primary owner but
-must not be selected alone.
-
-Example:
-
-```json
-{
-  "primary_skill": "generic_development",
-  "without_companions": ["operations", "qa"],
-  "reason": "Production deployment requires runtime and acceptance gates."
-}
-```
-
-## Boundary
-
-Fixture evidence may support learning proposals. It must not directly rewrite
-source-of-truth files.
-
-## Evidence
-
-A fixture run should preserve one evidence pack per fixture:
-
-- parsed route result;
-- execution evidence with command, working directory, exit code and output
-  hashes;
-- stdout/stderr references;
-- route explanation reference for high-risk routes.
-
-High-risk fixtures should fail when the route explanation is missing.

package/standard/runtime-enablement.md

@@ -1,85 +0,0 @@
-# Runtime Enablement
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-Mirai Graph can generate context for humans, agents and software runtimes. Runtime
-enablement defines when graph-mode may be used as the primary context layer for
-a specific task.
-
-This section generalizes the boundary:
-
-```text
-generated context != authorization
-runtime decision != executed action
-feedback != canonical update
-```
-
-## Runtime Question
-
-The runtime gate answers one narrow question:
-
-```text
-Can this specific task use graph-mode as the primary context layer?
-```
-
-It does not answer whether the task should be executed, whether the graph should
-be rewritten, or whether the generated context is complete.
-
-## Runtime Modes
-
-- `blocked`: graph-mode must not be used for the task.
-- `fallback_required`: graph-mode may help, but raw sources, runbooks or
-  approvals are mandatory.
-- `graph_context_allowed`: graph-mode can be the primary context for the
-  declared measured scope.
-- `no_match`: no policy covers the requested task.
-
-## Safe Defaults
-
-Implementations should use these defaults:
-
-- compact context first;
-- broader context only when justified by evidence;
-- no canonical writes through runtime policy;
-- raw-source fallback for sensitive work;
-- gap recording when graph coverage is missing.
-
-## Mandatory Fallback Triggers
-
-Fallback should be required for:
-
-- unmeasured scenarios;
-- destructive actions;
-- production or live infrastructure;
-- credentials, secrets or private data;
-- legal, commercial or financial risk;
-- customer-visible writes;
-- irreversible changes;
-- safety-critical operations.
-
-## Runtime Preflight
-
-A runtime preflight artifact should include:
-
-- task;
-- target object or profile;
-- selected context profile;
-- status;
-- required fallbacks;
-- blocking gaps;
-- generated context references;
-- raw source references that must still be read;
-- limitations.
-
-## Limited Claim
-
-Passing a runtime enablement gate supports this limited claim:
-
-```text
-Graph-mode may be used as the primary context layer for the declared task and
-scope, subject to recorded fallbacks and limitations.
-```
-
-It does not authorize execution or canonical graph updates.

package/standard/semantic-intent-resolution.md

@@ -1,91 +0,0 @@
-# Semantic Intent Resolution
-
-Status: 1.0 release-candidate extension contract
-
-## Purpose
-
-Semantic Intent Resolution is an input-control contract for turning a free-form
-human request into a governed work decision before execution starts.
-
-It answers:
-
-- what the user likely wants;
-- what scale the work has;
-- which process and owner should handle it;
-- what context is missing;
-- whether execution can start;
-- which gates and evidence are required.
-
-This is not a standalone Mirai Graph profile. It is an extension contract that
-composes existing project, implementation, AI employee, technology feedback and
-dynamic episode layers.
-
-## Control Pattern
-
-```text
-request
--> intent hypothesis
--> work scale
--> owner/process decision
--> context-slot check
--> clarification, brief, workflow restore or safe execution
--> process control
--> evidence, episode trace and technology quality feedback
-```
-
-## Boundary
-
-Semantic Intent Resolution does not authorize action.
-
-```text
-semantic confidence != approval
-generated brief != authorization
-proposal != canonical update
-episode trace != permission to execute
-```
-
-High confidence in a route or intent still cannot bypass policy, approval,
-security, live-operation, data-mutation, Git-history or destructive-action
-gates.
-
-## Required Fields
-
-- `user_request`
-- `intent_hypothesis`
-- `confidence`
-- `work_scale`
-- `selected_chain_id`
-- `process_model_id`
-- `owner_role`
-- `required_context_slots`
-- `missing_context_slots`
-- `safe_default_action`
-- `execution_allowed`
-- `evidence_requirements`
-
-## Decision Rules
-
-- Low confidence blocks execution and requires review.
-- Missing required context for significant work blocks execution or creates a
-  clarification/brief path.
-- Track-level work must not be collapsed into one batch.
-- Goal-level work requires goal evidence such as Done When, stages, batches,
-  gates or evidence plan.
-- Risky work requires the relevant gates even when intent confidence is high.
-- Generated outputs do not update canonical graph state.
-
-## Integration Points
-
-- `project_management`: classifies work scale and track/goal/batch boundary.
-- `implementation_control`: decides readiness before execution.
-- `ai_employee`: selects role, owner and action boundary.
-- `technology_quality_feedback`: checks whether intake followed the approved
-  work technology.
-- `dynamic_episode_layer`: records why a path was selected, blocked or
-  clarified.
-
-## Public Safety
-
-Public examples must be synthetic. Do not publish private requests, customer
-messages, runtime traces, internal handoff payloads, access details, tokens,
-private policies or raw logs.

package/standard/source-boundary-contract.md

@@ -1,49 +0,0 @@
-# Source Boundary Contract
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-Source boundary contracts define which repository or graph areas are canonical,
-generated, curated for human review, evidence, workflow records, legacy context,
-tooling or local scratch.
-
-They prevent generated artifacts, review notes or implementation repositories
-from silently becoming source of truth.
-
-## Source Roles
-
-- `canonical`: reviewed source-of-truth data or rules.
-- `generated`: reproducible output from canonical or evidence sources.
-- `curated_human`: reviewed human-readable projection or explanation.
-- `workflow`: process, planning, launch, recovery or coordination record.
-- `evidence`: reviewed support material for a claim.
-- `legacy`: historical material preserved for traceability.
-- `tooling`: validators, generators, schemas or support scripts.
-- `local_scratch`: ignored local intake or temporary workspace.
-
-## Synchronization Flow
-
-```text
-canonical sources
--> tooling
--> generated and curated views
--> human review or implementation planning
--> accepted proposals
--> canonical update
--> regenerated views
-```
-
-## Promotion Rule
-
-If generated output, human review, workflow records or evidence contain a new
-important fact, that fact must be promoted through an explicit proposal before
-it becomes canonical state.
-
-## Schema
-
-Machine-readable source boundary contracts can be validated with:
-
-```text
-schemas/source-boundary-contract.schema.json
-```