mirai-graph 1.4.0 → 2.1.0

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.

package/standard/feature-implementation-traceability.md

@@ -1,68 +0,0 @@
-# Feature Implementation Traceability
-
-Feature Implementation Traceability is a Mirai Graph pattern for connecting feature intent to implementation, tests, evidence, documentation, and review.
-
-It answers a simple governance question:
-
-```text
-For each feature, what proves where it is implemented, how it was tested, what remains incomplete, and which transition decision it supports?
-```
-
-## Scope
-
-The traceability layer is useful for software products, AI employees, research systems, organizational processes, and other projects where generated or human plans must be tied to delivered work.
-
-It should track:
-
-- feature or capability reference;
-- owning component or package;
-- implementation mapping;
-- dependency mapping;
-- test and validation evidence;
-- documentation evidence;
-- review status;
-- known gaps and blockers;
-- supported transition or release decision.
-
-## Required Separation
-
-Mirai Graph keeps these states separate:
-
-- `specified`: the feature is described;
-- `mapped`: the feature is connected to expected implementation locations or work items;
-- `implemented`: the work has concrete implementation evidence;
-- `tested`: validation evidence exists;
-- `reviewed`: semantic or human review exists;
-- `accepted`: the relevant gate accepted the work;
-- `released`: release or publication gate passed.
-
-`specified`, `mapped`, `ready_to_execute`, and `ready_to_code` are not implementation.
-
-## Mapping Rules
-
-Every mapping should declare:
-
-- `feature_ref`;
-- `implementation_refs`;
-- `test_refs`;
-- `evidence_refs`;
-- `review_refs`;
-- `documentation_refs`;
-- `status`;
-- `confidence`;
-- `known_gaps`.
-
-An implementation mapping without evidence should stay below accepted readiness.
-
-## Governance Use
-
-Traceability supports:
-
-- cockpit instrumentation;
-- process-transition validation;
-- release readiness review;
-- technology quality feedback;
-- drift detection;
-- Kaizen classification.
-
-It does not create approval. It gives reviewers and validators a reproducible path from intent to work evidence.

package/standard/federation-health.md

@@ -1,42 +0,0 @@
-# Federation Health
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-Federation health summarizes whether a graph-managed federation is routable,
-explainable and safe to use as a context/control layer.
-
-## Health Signals
-
-A health dashboard should include:
-
-- skill or capability count;
-- runtime-ready count;
-- stale graph count;
-- watch conflict count;
-- unresolved conflict count;
-- failed fixture count;
-- high-risk routes without explanation;
-- fallback-required route count;
-- blocked route count;
-- route regression status;
-- pending learning proposals;
-- conflict details with severity and next action.
-
-## Conflict Details
-
-Counts are not enough. A useful dashboard should identify:
-
-- conflict family id;
-- affected capabilities;
-- failed fixture ids;
-- latest route explanation references;
-- required owner review;
-- next action;
-- severity.
-
-## Boundary
-
-Health dashboards are evidence and control surfaces. They do not grant runtime
-authorization or canonical write permission.

package/standard/feedback-learning-gate.md

@@ -1,101 +0,0 @@
-# Feedback Learning Gate
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-This section defines how feedback can improve a Mirai Graph-modeled AI employee
-without allowing uncontrolled self-modification.
-
-## Core Flow
-
-```text
-feedback -> proposal -> replay/evaluation -> approval -> canonical graph update
-```
-
-## Feedback
-
-Feedback is an observation, review, correction, rating, error report or outcome
-signal.
-
-Feedback may come from:
-
-- a human reviewer;
-- an audited result;
-- a failed action;
-- a successful action;
-- a monitoring signal;
-- a peer AI employee;
-- an external evaluation.
-
-Feedback is evidence. It is not automatically a behavior change.
-
-## Learning Proposal
-
-A learning proposal describes what should change in the graph.
-
-It may propose:
-
-- updating a policy;
-- adding or changing a lesson;
-- changing a workflow;
-- changing a skill description;
-- adding a risk;
-- changing a delegation rule;
-- adding a new approval requirement.
-
-## Replay Or Evaluation
-
-Before acceptance, the proposal should be evaluated.
-
-Evaluation may include:
-
-- replaying the failed scenario;
-- comparing expected and actual result;
-- checking policy impact;
-- checking safety or public-release risk;
-- checking whether the lesson is too broad;
-- checking whether the change conflicts with existing graph state.
-
-## Approval
-
-Learning changes that affect future behavior should pass a governance gate.
-
-Examples:
-
-- `feedback_learning_before_behavior_update`;
-- `human_review_before_canonical_write`;
-- `public_safety_before_release`;
-- `approval_before_external_action`.
-
-## Canonical Update
-
-After approval, a canonical graph update may add, deprecate or change objects
-and relations.
-
-The update should preserve:
-
-- feedback evidence;
-- proposal id or source;
-- approval record;
-- affected object and relation ids;
-- limitation or rollback note when relevant.
-
-## Anti-Patterns
-
-- Treating every feedback item as a permanent lesson.
-- Letting a failed action automatically rewrite policy.
-- Updating behavior without preserving evidence.
-- Merging runtime logs directly into canonical memory.
-- Accepting broad lessons from one narrow example.
-
-## Claim Rule
-
-Passing through a feedback learning gate supports this limited claim:
-
-```text
-The behavior update was proposed, evaluated and accepted through a recorded
-governance process.
-```
-
-It does not prove the updated behavior is universally correct.

package/standard/goal-vector-quality-control.md

@@ -1,128 +0,0 @@
-# Goal Vector Quality Control
-
-Status: 1.0 release-candidate extension contract
-
-## Purpose
-
-Goal Vector Quality Control checks whether meaningful work moves toward the
-declared final outcome instead of only producing useful-looking activity.
-
-It is an extension contract, not a standalone Mirai Graph profile. It composes
-project management, implementation control, technology quality feedback,
-dynamic episode evidence and semantic intent resolution.
-
-## Core Pattern
-
-Goal Vector Quality Control combines forward execution and reverse audit.
-
-Forward execution:
-
-```text
-start state
--> final outcome
--> current goal
--> stages
--> batches
--> evidence
--> completion claim
-```
-
-Reverse audit:
-
-```text
-final outcome
--> required qualities
--> checks and evidence
--> actual result
--> workflow decisions
--> drift findings
--> correction route
-```
-
-Every meaningful batch should be able to state:
-
-```text
-This batch advances <goal/final outcome> by <specific contribution>.
-```
-
-If that link is missing, the work may be drift even when it produced files,
-tests or reports.
-
-## Boundary
-
-Goal Vector Quality Control is not authorization.
-
-```text
-goal vector != approval
-reverse audit != release permission
-evidence != acceptance
-tests != semantic acceptance
-correction route != canonical update
-```
-
-The contract may produce quality evidence, drift findings, correction routes,
-Kaizen items and graph proposals. It must not grant production permission,
-approve deployment, mutate source systems or update canonical graph state.
-
-## Required Fields
-
-- `start_state`
-- `final_outcome`
-- `work_scale`
-- `goal_vector`
-- `vector_segments`
-- `batch_vector_links`
-- `required_qualities`
-- `quality_evidence`
-- `reverse_audit`
-- `drift_findings`
-- `correction_routes`
-- `quality_verdict`
-- `completion_claim`
-- `canonical_write_allowed`
-
-## Verdicts
-
-- `PASS`
-- `PASS_WITH_NOTES`
-- `PARTIAL`
-- `CORRECTION_REQUIRED`
-- `BLOCKED`
-- `FAIL`
-
-`PASS` and `PASS_WITH_NOTES` require evidence, reverse audit and no unresolved
-blocking drift findings. `PARTIAL` is suitable for in-progress work when the
-vector is visible but the final outcome is not yet complete.
-
-## Integration Points
-
-- `project_management`: owns start state, final outcome, goal vector, stages,
-  tasks and batch movement.
-- `implementation_control`: owns launch/completion guards, work states,
-  evidence boundaries and false completion guards.
-- `technology_quality_feedback`: owns reverse audit, finding classification,
-  semantic acceptance and correction routing.
-- `dynamic_episode_layer`: records what happened, which path was selected and
-  why alternatives were blocked.
-- `semantic_intent_resolution`: captures intended final outcome and missing
-  context before execution starts.
-
-## Public Safety
-
-Public examples must be synthetic. Do not publish private project workflow
-contents, private runtime traces, customer messages, access details, tokens,
-internal handoff payloads or raw logs.
-
-## Conformance
-
-Initial public conformance is synthetic:
-
-- `G0_concept`: extension contract only.
-- `G1_synthetic_fixture`: synthetic example and negative fixtures.
-- `G2_internal_pilot`: private pilot evidence with public-safe summary.
-- `G3_replay_regression`: replay/regression evidence for drift reduction.
-- `G4_audited_runtime`: audited operational use with retention and review
-  policy.
-
-The public `1.0` release-candidate layer should claim no more than
-`G1_synthetic_fixture` until sanitized pilots and replay evidence are available.