@event4u/agent-config 2.26.0 → 3.0.0

package/docs/contracts/decision-trace-v1.md

@@ -10,7 +10,7 @@ runs emit when the user opts into trace surfacing. The trace is the
 audit substrate for the rule-interaction matrix
 ([`rule-interactions.md`](rule-interactions.md)) and feeds the
 showcase-session capture pipeline
-([`outcome-baseline.md`](../../agents/contexts/outcome-baseline.md)).
+([`outcome-baseline.md`](../../agents/settings/contexts/outcome-baseline.md)).
 
 **Scope.** Defines the JSON envelope written next to a `WorkState`
 file when `decision_engine.surface_traces: true`. Does **not**
@@ -34,7 +34,7 @@ boundaries and emit one trace file per phase when set.
 ## File location
 
 ```
-agents/state/work/<work-id>/decision-trace-<phase>.json
+agents/runtime/state/work/<work-id>/decision-trace-<phase>.json
 ```
 
 `work-id` matches the `WorkState` directory; `phase` is one of
@@ -58,7 +58,7 @@ agents/state/work/<work-id>/decision-trace-<phase>.json
       "applied": true,
       "skipped": false,
       "conflicted_with": [],
-      "evidence_refs": ["agents/state/work/.../verify.log"]
+      "evidence_refs": ["agents/runtime/state/work/.../verify.log"]
     }
   ],
   "memory": {
@@ -89,7 +89,7 @@ compat extensions and MUST NOT raise on them.
 | `rules[].applied` | True if the rule's Iron Law fired and changed engine behaviour this phase. |
 | `rules[].skipped` | True if the rule was checked but produced no effect (no trigger match). |
 | `rules[].conflicted_with` | List of rule_ids that fired against this one. Reduction handled per `rule-interactions.md`. |
-| `rules[].evidence_refs` | Optional list of paths under `agents/state/` or `tests/` that back the `applied` claim. |
+| `rules[].evidence_refs` | Optional list of paths under `agents/runtime/state/` or `tests/` that back the `applied` claim. |
 | `memory.asks` | Count of `memory_retrieve` calls during the phase. |
 | `memory.hits` | Count of calls that returned ≥ 1 result. |
 | `memory.ids` | Stable memory entry ids returned. Bounded to ≤ 32 ids per phase; remainder dropped silently. |
@@ -174,4 +174,4 @@ majors.
   `work_engine/scoring/decision_trace.py` and exercised by
   `tests/work_engine/scoring/test_decision_trace_scoring.py`.
 - Outcome metrics consume `verify.first_try_passes`:
-  [`outcome-baseline.md`](../../agents/contexts/outcome-baseline.md).
+  [`outcome-baseline.md`](../../agents/settings/contexts/outcome-baseline.md).

package/docs/contracts/discovery-manifest.schema.json

@@ -0,0 +1,146 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://event4u.app/agent-config/schemas/discovery-manifest.schema.json",
+  "title": "Discovery Manifest",
+  "description": "Release-time scan output for @event4u/agent-config. See ADR-013 and agents/roadmaps/archive/automated-pack-workspace-and-skill-discovery.md (archived, status: completed).",
+  "type": "object",
+  "required": ["version", "generated_at", "scanner_version", "checksum", "workspaces", "packs", "artefacts", "unassigned"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "const": 1,
+      "description": "Manifest schema version. Bump on breaking change."
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "UTC ISO-8601 timestamp; the only field allowed to differ between determinism runs."
+    },
+    "scanner_version": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{12}$",
+      "description": "First 12 hex chars of sha256(scripts/build_discovery_manifest.py)."
+    },
+    "checksum": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$",
+      "description": "sha256 of the JSON file with the checksum field zeroed out."
+    },
+    "workspaces": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/workspace" },
+      "minItems": 1
+    },
+    "packs": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/pack" },
+      "minItems": 1
+    },
+    "artefacts": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/artefact" }
+    },
+    "unassigned": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/unassigned" },
+      "description": "Artefacts that failed assignment. Each entry MUST carry a reason."
+    },
+    "documented_unassigned": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/unassigned" },
+      "description": "Artefacts explicitly skipped via config/discovery/unassigned-artefacts.yml. Each entry MUST carry a reason."
+    }
+  },
+  "$defs": {
+    "workspace_id": {
+      "type": "string",
+      "enum": ["engineering", "product", "finance", "founder", "gtm", "ops", "small-business", "construction", "agent-config-maintainer"]
+    },
+    "pack_id": {
+      "type": "string",
+      "enum": [
+        "engineering-base", "php", "laravel", "symfony", "javascript", "typescript", "react", "nextjs", "python",
+        "product-basic", "product-discovery",
+        "finance-basic", "finance-advanced",
+        "gtm-sales", "gtm-marketing",
+        "ops-people", "founder-strategy", "small-business", "construction", "ai-video", "meta"
+      ]
+    },
+    "lifecycle": {
+      "type": "string",
+      "enum": ["active", "deprecated", "experimental", "archived"]
+    },
+    "trust_level": {
+      "type": "string",
+      "enum": ["core", "professional", "experimental", "advisory", "restricted"]
+    },
+    "workspace": {
+      "type": "object",
+      "required": ["id", "label", "description", "default_packs"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "#/$defs/workspace_id" },
+        "label": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 },
+        "default_packs": { "type": "array", "items": { "$ref": "#/$defs/pack_id" } },
+        "optional_packs": { "type": "array", "items": { "$ref": "#/$defs/pack_id" } }
+      }
+    },
+    "pack": {
+      "type": "object",
+      "required": ["id", "label", "description", "workspaces", "trust_level_default", "artefact_count"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "#/$defs/pack_id" },
+        "label": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 },
+        "workspaces": { "type": "array", "items": { "$ref": "#/$defs/workspace_id" }, "minItems": 1 },
+        "requires_hint": { "type": "array", "items": { "$ref": "#/$defs/pack_id" } },
+        "trust_level_default": { "$ref": "#/$defs/trust_level" },
+        "artefact_count": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "artefact": {
+      "type": "object",
+      "required": ["path", "category", "workspaces", "packs", "lifecycle", "trust", "install"],
+      "additionalProperties": false,
+      "properties": {
+        "path": { "type": "string", "minLength": 1, "description": "POSIX path relative to repo root." },
+        "category": { "type": "string", "enum": ["skill", "rule", "command", "template"] },
+        "name": { "type": "string" },
+        "workspaces": { "type": "array", "items": { "$ref": "#/$defs/workspace_id" }, "minItems": 1 },
+        "packs": { "type": "array", "items": { "$ref": "#/$defs/pack_id" }, "minItems": 1 },
+        "lifecycle": { "$ref": "#/$defs/lifecycle" },
+        "trust": {
+          "type": "object",
+          "required": ["level", "confidence", "human_review_required"],
+          "additionalProperties": false,
+          "properties": {
+            "level": { "$ref": "#/$defs/trust_level" },
+            "confidence": { "type": "string", "enum": ["high", "medium", "low"] },
+            "human_review_required": { "type": "boolean" }
+          }
+        },
+        "install": {
+          "type": "object",
+          "required": ["default", "removable"],
+          "additionalProperties": false,
+          "properties": {
+            "default": { "type": "boolean" },
+            "removable": { "type": "boolean" }
+          }
+        }
+      }
+    },
+    "unassigned": {
+      "type": "object",
+      "required": ["path", "category", "reason"],
+      "additionalProperties": false,
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "category": { "type": "string", "enum": ["skill", "rule", "command", "template", "unknown"] },
+        "reason": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/docs/contracts/explain-trace.schema.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://event4u.app/agent-config/schemas/explain-trace.schema.json",
+  "title": "ExplainTrace v1",
+  "description": "Execution-trace contract emitted by `agent-config explain last`. The CLI's --json output is the wire format; the Markdown renderer is a deterministic projection of this same object. See agents/roadmaps/explainability-v2-explain-last.md and the in-tree builder at scripts/_cli/explain_last/.",
+  "type": "object",
+  "required": [
+    "version",
+    "generated_at",
+    "run_id",
+    "subject",
+    "inputs",
+    "route",
+    "council",
+    "memory",
+    "pack",
+    "assumptions",
+    "halt",
+    "provider"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Schema version. Bumps require a sibling roadmap; readers MUST refuse unknown versions."
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 UTC timestamp at which the trace was built (renderer-deterministic only when fixed by the test harness)."
+    },
+    "run_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Identifier of the originating /work run. Pulled from state.input.data.id, with fallback to the state file mtime serialised as ISO-8601."
+    },
+    "subject": {
+      "type": "string",
+      "enum": ["work", "implement-ticket", "council", "video", "unknown"],
+      "description": "Originating directive set. `unknown` fires when state.directive_set is absent or unrecognised."
+    },
+    "inputs": {
+      "type": ["object", "null"],
+      "description": "Profile / preset / cost_profile resolution chain. Null when the loader could not resolve any of them (broken settings).",
+      "required": ["profile", "preset", "cost_profile", "source_per_knob"],
+      "additionalProperties": false,
+      "properties": {
+        "profile": {"type": ["string", "null"]},
+        "preset": {"type": ["string", "null"]},
+        "cost_profile": {"type": ["string", "null"]},
+        "source_per_knob": {
+          "type": "object",
+          "description": "Map<knob, source>; source ∈ pack | profile | preset | user | env | runtime | default.",
+          "additionalProperties": {"type": "string"}
+        }
+      }
+    },
+    "route": {
+      "type": ["object", "null"],
+      "description": "Rule-router activation snapshot. Null when router.json is absent.",
+      "required": ["matched_rules", "kernel_rules", "persona"],
+      "additionalProperties": false,
+      "properties": {
+        "matched_rules": {"type": "array", "items": {"type": "string"}},
+        "kernel_rules": {"type": "array", "items": {"type": "string"}},
+        "persona": {"type": ["string", "null"]}
+      }
+    },
+    "council": {
+      "type": ["array", "null"],
+      "description": "List of council member responses attached to this run. Null when no session file matched the run window.",
+      "items": {
+        "type": "object",
+        "required": ["member_id", "verdict", "citations"],
+        "additionalProperties": false,
+        "properties": {
+          "member_id": {"type": "string"},
+          "verdict": {"type": "string"},
+          "citations": {"type": "array", "items": {"type": "string"}}
+        }
+      }
+    },
+    "memory": {
+      "type": ["array", "null"],
+      "description": "Memory-MCP hits that influenced this run. Null when no memory layer was consulted.",
+      "items": {
+        "type": "object",
+        "required": ["entry_id", "hit_score", "used_in"],
+        "additionalProperties": false,
+        "properties": {
+          "entry_id": {"type": "string"},
+          "hit_score": {"type": "number"},
+          "used_in": {"type": "string"}
+        }
+      }
+    },
+    "pack": {
+      "type": ["object", "null"],
+      "description": "Active workspace pack selection. Null when no pack was active.",
+      "required": ["id", "reason"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {"type": "string"},
+        "reason": {"type": "string"}
+      }
+    },
+    "assumptions": {
+      "type": "array",
+      "description": "Assumptions the engine recorded; empty list when none were captured.",
+      "items": {
+        "type": "object",
+        "required": ["id", "accepted", "source"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {"type": "string"},
+          "accepted": {"type": "boolean"},
+          "source": {"type": "string"}
+        }
+      }
+    },
+    "halt": {
+      "type": ["object", "null"],
+      "description": "Most recent halt persisted by the engine. Null on clean runs.",
+      "required": ["reason", "step", "surface"],
+      "additionalProperties": false,
+      "properties": {
+        "reason": {"type": "string"},
+        "step": {"type": "string"},
+        "surface": {"type": "array", "items": {"type": "string"}}
+      }
+    },
+    "provider": {
+      "type": ["object", "null"],
+      "description": "Video provider selection record. Non-null only when state.directive_set == 'video' AND state.video_provider was written.",
+      "required": ["id", "selection_reason"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {"type": "string"},
+        "selection_reason": {"type": "string"}
+      }
+    }
+  }
+}