mirai-graph 1.3.0 → 2.1.0

package/standard/context-pack-generation.md

@@ -1,184 +0,0 @@
-# Mirai Graph Context-Pack Generation
-
-Status: 1.2 stable standard section
-
-## Purpose
-
-Context-pack generation defines how a Mirai Graph implementation produces
-task-specific working context from canonical graph state.
-
-A generated context pack helps a human or AI assistant perform a task. It does
-not replace canonical graph state.
-
-## Context Pack
-
-A context pack is a task-bounded view of the graph.
-
-It should include:
-
-- task id or task description;
-- included objects;
-- included relations;
-- evidence references;
-- assumptions;
-- omissions or excluded context;
-- generation method;
-- relevance scores and selection explanations when generated by tooling;
-- timestamp or version reference;
-- limitations.
-
-## Minimum Context-Pack Metadata
-
-```json
-{
-  "id": "context_pack.notify_after_approval",
-  "task_id": "task.notify_after_approval",
-  "source_graph": "package.synthetic_context_reduction_v0",
-  "generated_at": "2026-05-28",
-  "included_objects": [],
-  "included_relations": [],
-  "evidence": [],
-  "selection": {
-    "method": "token_matching_one_hop_relation_expansion_safety_shared_evidence",
-    "task_tokens": ["task", "notify", "after", "approval"],
-    "object_explanations": [],
-    "relation_explanations": []
-  },
-  "limitations": []
-}
-```
-
-## Generation Flow
-
-```text
-task -> select relevant objects -> select relevant relations
-     -> include evidence references -> record omissions
-     -> generate context pack -> review/use for task
-```
-
-Project Technology implements this as a deterministic four-phase protocol:
-
-```text
-discover -> expand -> compile -> verify
-```
-
-The traversal receipt binds the task digest, graph digest and revision to the
-visited nodes. The client records selected and rejected nodes, reasons,
-confidence and selector type. Compilation then adds the mandatory dependency
-closure and returns one of `needs_more_discovery`, `needs_decision`, `blocked`
-or `ready`.
-
-`ready` requires a result owner, terminal sources with exact revision and
-SHA-256, all mandatory processes and validators, explicit reasons for omitted
-branches, no required dependency cycle and no access or readiness conflict.
-The context budget may remove optional material only; it must never remove the
-mandatory closure.
-
-The compiled pack adds selected and rejected paths, visited nodes, stop
-reasons, mandatory closure, terminal sources, processes, constraints,
-validators, completeness and `context_pack_digest`. These fields extend this
-single context-pack contract; there is no parallel pack format.
-
-## Selection Rules
-
-A context pack should include:
-
-- objects directly required by the task;
-- relations needed to understand dependencies and blockers;
-- evidence supporting included claims;
-- governance gates relevant to the task;
-- known risks or limitations;
-- safety, security, privacy or public-release constraints that share evidence
-  with the selected task context, even when they are not lexical task matches.
-
-## Selection Explanations
-
-Generated context packs should explain why each included object and relation was
-selected.
-
-Object explanations should include:
-
-- object id;
-- relevance score or equivalent ranking signal;
-- reasons such as exact token match, one-hop relation expansion, safety-context
-  inclusion or evidence preservation.
-
-Relation explanations should include:
-
-- relation id;
-- reason for inclusion;
-- source and target ids when available.
-
-Scores are implementation signals. They help review the generated context, but
-they do not prove semantic completeness.
-
-## Usage Evidence
-
-Loading a source is not proof that it was used. For each significant rule,
-usage evidence connects:
-
-```text
-source -> applied rule -> decision -> changed or checked surface
-       -> validator -> outcome
-```
-
-Verification fails when the evidence belongs to another context pack, skips a
-mandatory source, process or validator, uses stale or tampered content, exposes
-private material or treats generated context as write authorization.
-
-## Validation
-
-Context-pack validation should check both shape and graph references:
-
-- required metadata fields are present;
-- `source_graph` matches the package manifest id;
-- included object ids exist in the source graph;
-- included relation ids exist and connect included objects;
-- evidence ids exist in the source graph;
-- selection explanations cover every included object and relation;
-- relation explanations identify source and target ids.
-
-A context pack should exclude:
-
-- unrelated graph areas;
-- private material outside the task boundary;
-- deprecated objects unless needed for historical context;
-- generated claims not accepted into canonical state.
-
-## Evidence Preservation
-
-Generated context should preserve evidence references. If a context pack
-summarizes an object, it should still identify the source object and evidence
-ids.
-
-## Omissions
-
-Omissions are part of responsible context generation.
-
-Each non-trivial context pack should state:
-
-- what was excluded;
-- why it was excluded;
-- whether exclusion creates risk;
-- when a broader context review is needed.
-
-## Generated Context Is Not Canonical State
-
-Generated context packs may be reviewed and then used as evidence or source
-material for graph updates. They do not automatically mutate canonical graph
-state.
-
-With `continuity_policy: task_boundary`, accepted continuity objects in
-`graph/specs` participate in the same traversal as every other graph object.
-Relevant previous cases can therefore be found without reading chat history or
-requiring a user to say "continue". Host-local receipts never enter a context
-pack and never become portable authority.
-
-## Anti-Patterns
-
-- Treating a generated context pack as the graph.
-- Removing evidence references during summarization.
-- Using one task pack for a different task without review.
-- Omitting governance gates to make a task easier.
-- Omitting safety constraints because they do not share task keywords.
-- Generating public context from private material without a release gate.

package/standard/development-cockpit.md

@@ -1,67 +0,0 @@
-# Development Cockpit
-
-Development Cockpit is a Mirai Graph instrumentation layer for steering governed work by observable signals instead of chat memory or informal confidence.
-
-It does not replace tests, review, approval, release gates, or canonical graph updates. It aggregates evidence-backed indicators so a coordinator can see whether a work system is on course, drifting, blocked, or ready for the next governed transition.
-
-## Purpose
-
-Development Cockpit is used when a project needs a compact operating view over:
-
-- trajectory toward the current goal;
-- graph coverage and implementation coverage;
-- evidence confidence;
-- documentation and code-location traceability;
-- quality and architecture integrity;
-- security, drift, blockers, dependencies, and next action.
-
-The cockpit is intentionally an instrument panel. It can recommend a next action, but it cannot authorize execution, approval, release, or canonical update by itself.
-
-## Required Model
-
-A cockpit report must declare:
-
-- `subject_ref`: the project, package, process, or work batch being observed;
-- `generated_at`: when the report was produced;
-- `instruments`: observable indicators with score, band, status, reason, and evidence references;
-- `readiness`: separated readiness signals for developer testing, product maturity, production, and external user testing;
-- `next_best_action`: a bounded recommended action with target cycle and required gates;
-- `blocking_rules`: conditions that stop transition even when aggregate scores look high;
-- `limitations`: boundary language that prevents confusing metrics with acceptance.
-
-## Instrument Rules
-
-Each instrument should be evidence-backed. Missing evidence is a signal, not a reason to fabricate confidence.
-
-Recommended instrument families:
-
-- `trajectory`: alignment with goal, DNA, scope, and current milestone;
-- `graph_coverage`: whether relevant objects, relations, dependencies, and lifecycle states are represented;
-- `implementation_coverage`: whether planned work maps to concrete implementation and evidence;
-- `evidence_confidence`: whether evidence is current, reproducible, and tied to the right claims;
-- `traceability`: whether features connect to specs, code, tests, documentation, and review;
-- `quality`: test health, semantic review, technology adherence, and defect patterns;
-- `architecture`: ownership boundaries, dependency shape, and source-boundary conformance;
-- `risk`: blockers, drift, security findings, release risks, and recovery options.
-
-## Transition Boundary
-
-Development Cockpit can support a transition decision only when paired with the relevant gate:
-
-```text
-cockpit signal -> transition request -> required evidence -> gate validation -> decision
-```
-
-High cockpit readiness is not execution, implementation, acceptance, release, or approval.
-
-## Kaizen Use
-
-Cockpit signals should feed Kaizen when they reveal repeatable process issues:
-
-- repeated missing evidence;
-- recurring dependency drift;
-- frequent reviewer corrections;
-- weak traceability between feature intent and implementation;
-- mismatch between tests and semantic acceptance.
-
-The Kaizen output is a classified improvement or proposal, not an automatic canonical update.

package/standard/dynamic-episode-layer.md

@@ -1,113 +0,0 @@
-# Dynamic Episode Layer
-
-Status: proposal/experimental standard section
-
-## Purpose
-
-The Dynamic Episode Layer records how a concrete event moves through a Mirai
-Graph system and why the system reacted the way it did.
-
-Existing technology chains define how work should be performed. Dynamic
-episodes record what actually happened for one event:
-
-```text
-event
--> activated graph objects and relations
--> selected workflow and technology chain
--> selected path
--> blocked alternatives
--> gates
--> result
--> findings
--> feedback route
--> Kaizen or graph proposal
-```
-
-This layer is designed for AI employees, AI-assisted code generation,
-governance simulations, project control and other systems where a result is not
-enough. A reviewer must be able to inspect why a path was selected, why other
-paths were blocked and which evidence supports the decision.
-
-## Core Rule
-
-```text
-canonical graph state != runtime trace != generated explanation != approval
-```
-
-A dynamic episode may create evidence, explanations, audit records, feedback
-and proposals. It must not mutate canonical graph state or authorize execution
-by itself.
-
-## Required Boundaries
-
-- An episode trace is evidence, not authorization.
-- Generated context is not canonical state.
-- Feedback is not an automatic graph update.
-- Passing tests do not mean acceptance.
-- Blocked paths must remain blocked until an owner-approved process changes the
-  gate, policy or graph relation.
-- Private event contents must not be copied into public examples or research
-  packages.
-
-## Record Levels
-
-The layer distinguishes four record levels:
-
-- `debug_log`: temporary implementation troubleshooting, short retention.
-- `episode_trace`: structured record explaining one event reaction.
-- `audit_record`: compact accountability record for later review.
-- `research_dataset`: sanitized, public-safe evidence derived from traces.
-
-## Dynamic Episode Lifecycle
-
-```text
-event_received
--> source_refs_loaded
--> graph_activation_recorded
--> workflow_selected
--> selected_path_recorded
--> blocked_paths_recorded
--> gates_evaluated
--> result_recorded
--> findings_classified
--> feedback_routed
--> kaizen_or_replay_candidate_recorded
-```
-
-## Required Fields
-
-A valid dynamic episode trace must identify:
-
-- event;
-- source references;
-- activated objects, relations, policies, gates and technology steps;
-- selected path;
-- blocked paths;
-- findings and classifications;
-- result;
-- evidence references;
-- limitations;
-- explicit `canonical_write_allowed=false`.
-
-## Relationship To Other Standard Sections
-
-- `implementation-control` defines process state and false-transition guards.
-- `technology-quality-feedback` checks whether the approved work technology was
-  followed.
-- `context-pack-generation` turns traces into bounded explanations.
-- `feedback-learning-gate` governs proposal and learning updates.
-- `action-runtime-boundary` prevents traces, evidence and proposals from
-  becoming unauthorized actions.
-
-## Conformance
-
-This proposal starts at synthetic conformance:
-
-- `D0_concept`: standard text only.
-- `D1_synthetic_episode`: synthetic example and validator.
-- `D2_internal_pilot`: internal project episode traces.
-- `D3_replay_regression`: replay and regression evidence.
-- `D4_audited_runtime`: operational audit records and retention policy.
-
-The current public layer should claim no more than `D1_synthetic_episode` until
-real pilots are validated.

package/standard/dynamic-layer-code-generation.md

@@ -1,87 +0,0 @@
-# Dynamic Layer For AI-Assisted Code Generation
-
-Status: proposal/experimental standard section
-
-## Purpose
-
-The Dynamic Episode Layer can be applied to AI-assisted code generation to keep
-implementation work inside the intended specification, package boundary and
-technology chain.
-
-The target pattern is:
-
-```text
-feature/package request
--> package DNA and feature graph
--> dependency activation
--> implementation technology chain
--> bounded code generation
--> test/evidence collection
--> dynamic episode trace
--> technology quality feedback
--> developer feedback classification
--> Kaizen / graph update proposal
--> replay or regression check
-```
-
-## Code Drift Classes
-
-The layer should make these drift types visible:
-
-- `scope_drift`: files or components outside the allowed scope were changed.
-- `package_boundary_violation`: a package owned another package's concern.
-- `wrong_dependency_activation`: required dependencies were not activated.
-- `unsupported_assumption`: the agent invented missing behavior or API shape.
-- `wrong_workflow_selected`: the wrong implementation technology was followed.
-- `technology_step_skipped`: a required work step was omitted.
-- `approval_gate_bypass`: readiness, tests or evidence were treated as
-  authorization.
-- `evidence_gap`: result claims are not backed by required evidence.
-- `feedback_loss`: developer feedback was not routed to reusable improvement.
-
-## Required Episode Outputs
-
-For significant code-generation episodes, store:
-
-```text
-episode-trace.json
-episode-trace.md
-technology-quality-feedback.json
-developer-feedback-classification.md
-kaizen-proposal.md
-metrics.json
-```
-
-The exact storage path is project-specific. For internal projects, use
-`source/output/dynamic-episodes/<episode-id>/` or another project-local
-generated/evidence path.
-
-## Acceptance Boundary
-
-Code can be generated, tests can pass and evidence can be collected, but the
-episode is not accepted until the relevant process-control and technology
-quality gates pass.
-
-The trace may propose:
-
-- work fix;
-- test gap;
-- spec gap;
-- graph update proposal;
-- process improvement;
-- blocker;
-- replay/regression scenario.
-
-It must not update the canonical specification, graph or source code by itself.
-
-## Research Use
-
-For research, episode traces can support comparison between:
-
-- prompt/spec-only baseline;
-- graph/context package without dynamic trace;
-- graph + technology chain + dynamic episode trace.
-
-Claims must remain bounded. Synthetic or internal pilot evidence is not broad
-scientific proof until it is reproduced, reviewed and published with clear
-limitations.

package/standard/episode-trace.md

@@ -1,97 +0,0 @@
-# Episode Trace
-
-Status: proposal/experimental standard section
-
-## Purpose
-
-An episode trace is the primary artifact of the Dynamic Episode Layer. It is a
-structured explanation of why a graph-governed system reacted to an event in a
-specific way.
-
-It answers:
-
-```text
-what arrived
-what activated
-which workflow was selected
-which path was followed
-which alternatives were blocked
-which gates passed or failed
-which assumptions were made
-what result happened
-what findings were classified
-what feedback or Kaizen route should follow
-```
-
-## Not A Thought Log
-
-An episode trace does not expose or claim to know the hidden internal reasoning
-of an LLM. It records the operational reason visible to the graph-controlled
-system: selected workflow, activated graph elements, gates, policies, evidence,
-results and findings.
-
-## Minimum Trace Shape
-
-```text
-event
-source_refs
-activated
-selected_path
-blocked_paths
-gates
-actions
-results
-findings
-feedback_classification
-kaizen_candidates
-replay_regression
-evidence_refs
-limitations
-canonical_write_allowed=false
-```
-
-## Failure Analysis Loop
-
-```text
-episode trace
--> finding classification
--> root-cause candidate
--> feedback route
--> work fix / test gap / spec gap / graph proposal / process improvement
--> Kaizen proposal
--> replay or regression check
-```
-
-Common root-cause candidates include:
-
-- `wrong_workflow_selected`;
-- `missing_dependency_activation`;
-- `scope_gate_not_activated`;
-- `scope_gate_ignored`;
-- `approval_gate_bypass`;
-- `unsupported_assumption`;
-- `technology_step_skipped`;
-- `evidence_treated_as_authorization`;
-- `character_boundary_not_activated`;
-- `context_pack_missing_required_object`.
-
-## Replay And Regression
-
-Replay uses the same or equivalent event against a graph/process version and
-compares:
-
-- selected path;
-- blocked paths;
-- required gates;
-- findings;
-- result;
-- explanation grounding.
-
-Replay is required before claiming that a graph or technology-chain change
-improved behavior.
-
-## Public Safety
-
-Public traces must be sanitized. Do not publish private event payloads,
-credentials, customer data, raw private logs or internal evidence unless they
-have been explicitly approved for publication.

package/standard/evidence-provenance.md

@@ -1,128 +0,0 @@
-# Mirai Graph Evidence And Provenance
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-Evidence and provenance rules explain how Mirai Graph links graph state to the
-materials, observations, decisions and reviews that justify it.
-
-Mirai Graph does not require every early idea to be fully proven. It does require
-important claims, accepted objects, accepted relations and public validation
-statements to make their evidence boundary explicit.
-
-## Evidence Object
-
-Evidence may be represented as a first-class object:
-
-```json
-{
-  "id": "source.example_note",
-  "kind": "evidence",
-  "title": "Example source note",
-  "summary": "A public-safe note used as evidence for a synthetic example.",
-  "readiness": "accepted",
-  "evidence": [],
-  "profile": "software_specification",
-  "source_path": "source-corpus/example.md"
-}
-```
-
-## Evidence Reference
-
-Objects and relations reference evidence by stable id:
-
-```json
-{
-  "id": "feature.example",
-  "evidence": ["source.example_note"]
-}
-```
-
-For mature Mirai Graph packages, evidence references should resolve to evidence
-objects or declared external sources.
-
-## Evidence Levels
-
-Initial evidence levels:
-
-- `synthetic`: artificial example or benchmark material;
-- `internal_case`: internal project or operational evidence;
-- `public_source`: public document, paper, repository or standard;
-- `experiment`: structured experiment result;
-- `review`: expert or peer review record;
-- `decision`: accepted governance or owner decision.
-
-Future schemas may add an explicit `evidence_level` field.
-
-## Provenance Questions
-
-For important graph state, a reviewer should be able to answer:
-
-- Where did this object or relation come from?
-- Is the source public, private, synthetic or experimental?
-- Who accepted it into canonical state?
-- What changed since the previous version?
-- Can this evidence be used publicly?
-- Does the evidence support the claim being made?
-
-## Public-Safe Evidence Rules
-
-Public Mirai Graph repositories should not include:
-
-- private source chats;
-- raw internal company materials;
-- customer or employee data;
-- secrets or access details;
-- private repository paths;
-- unpublished client work;
-- private metrics without approval and redaction.
-
-Use synthetic data or generalized public-safe summaries when public evidence is
-needed.
-
-## Claim Discipline
-
-Evidence must match claim strength.
-
-Synthetic benchmark evidence can support:
-
-- method inspection;
-- reproducibility of an example calculation;
-- schema and tooling demonstration.
-
-Synthetic benchmark evidence cannot support:
-
-- external validity;
-- real-world productivity improvement;
-- universal superiority claims;
-- agent safety claims.
-
-Internal case evidence can support:
-
-- case-study claims;
-- design feasibility;
-- observed workflow patterns.
-
-Internal case evidence cannot be treated as public reproducibility unless the
-data boundary and redaction plan are public and approved.
-
-## Provenance In Generated Context Packs
-
-A generated context pack should preserve evidence references for the objects and
-relations it includes.
-
-If context is compressed, the pack should still make clear:
-
-- what canonical objects it uses;
-- what evidence supports them;
-- what was omitted;
-- what the task boundary is.
-
-## Anti-Patterns
-
-- Treating a citation as evidence for a claim it does not support.
-- Treating synthetic examples as real-world validation.
-- Copying private source material into public examples.
-- Losing evidence references during context-pack generation.
-- Marking a public claim as validated before review.