hadara 0.3.2 → 0.3.3-rc.0

package/dist/schemas/context-graph.schema.json

@@ -0,0 +1,286 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "hadara.contextGraph.v1",
+    "x-hadara-schema-id": "hadara.contextGraph.v1",
+    "title": "HADARA Context Graph Report",
+    "type": "object",
+    "additionalProperties": true,
+    "required": [
+        "schemaVersion",
+        "command",
+        "ok",
+        "generatedAt",
+        "projectRoot",
+        "sourceHash",
+        "mode",
+        "nodes",
+        "edges",
+        "stateProjection",
+        "summary",
+        "issues"
+    ],
+    "properties": {
+        "schemaVersion": { "const": "hadara.contextGraph.v1" },
+        "command": { "const": "context.graph" },
+        "ok": { "type": "boolean" },
+        "generatedAt": { "type": "string" },
+        "projectRoot": { "type": "string" },
+        "sourceHash": { "type": "string", "minLength": 1 },
+        "mode": { "enum": ["full", "task"] },
+        "taskId": { "type": "string" },
+        "nodes": { "type": "array", "items": { "$ref": "#/$defs/node" } },
+        "edges": { "type": "array", "items": { "$ref": "#/$defs/edge" } },
+        "taskContext": { "$ref": "#/$defs/taskContext" },
+        "stateProjection": { "$ref": "#/$defs/stateProjection" },
+        "summary": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["nodeCounts", "edgeCounts", "sourcesRead", "degraded"],
+            "properties": {
+                "nodeCounts": { "type": "object" },
+                "edgeCounts": { "type": "object" },
+                "sourcesRead": { "type": "number" },
+                "degraded": { "type": "boolean" }
+            }
+        },
+        "cache": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["used", "hit"],
+            "properties": {
+                "used": { "type": "boolean" },
+                "hit": { "type": "boolean" },
+                "manifestHash": { "type": "string" },
+                "createdAt": { "type": "string" },
+                "cachePath": { "type": "string" },
+                "mode": { "type": "string" },
+                "readShardCount": { "type": "number" },
+                "hitShardCount": { "type": "number" },
+                "missShardCount": { "type": "number" },
+                "staleShardCount": { "type": "number" },
+                "corruptShardCount": { "type": "number" },
+                "schemaMismatchShardCount": { "type": "number" },
+                "shardPaths": {
+                    "type": "array",
+                    "items": { "type": "string" }
+                },
+                "staleExtractorKeys": {
+                    "type": "array",
+                    "items": { "type": "string" }
+                }
+            }
+        },
+        "issues": { "type": "array", "items": { "$ref": "#/$defs/graphIssue" } }
+    },
+    "$defs": {
+        "confidence": { "enum": ["explicit", "derived", "heuristic"] },
+        "nodeType": {
+            "enum": [
+                "Task",
+                "Document",
+                "ManagedSection",
+                "Evidence",
+                "Command",
+                "ReleaseCheck",
+                "Decision",
+                "KnownProblem",
+                "SourceFile",
+                "TestFile",
+                "FixtureFile",
+                "ConfigFile",
+                "Symbol"
+            ]
+        },
+        "edgeType": {
+            "enum": [
+                "HAS_EVIDENCE",
+                "CLOSES_WITH",
+                "REFERENCES_DOC",
+                "REQUIRED_FOR",
+                "SUPERSEDES",
+                "DESCRIBES_COMMAND",
+                "BELONGS_TO_DOCUMENT",
+                "CHECKS_COMMAND",
+                "AFFECTS_SURFACE",
+                "DEPENDS_ON_EVIDENCE",
+                "HAS_DECISION",
+                "HAS_KNOWN_PROBLEM",
+                "IMPORTS",
+                "EXPORTS",
+                "DEFINES_SYMBOL",
+                "TESTS_FILE",
+                "IMPLEMENTS_COMMAND",
+                "REFERENCED_BY_DOC",
+                "VALIDATED_BY_EVIDENCE"
+            ]
+        },
+        "source": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["path", "extractor"],
+            "properties": {
+                "path": { "type": "string", "minLength": 1 },
+                "line": { "type": "number" },
+                "hash": { "type": "string" },
+                "extractor": { "type": "string", "minLength": 1 }
+            }
+        },
+        "node": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["id", "type", "label", "source"],
+            "properties": {
+                "id": { "type": "string", "minLength": 1 },
+                "type": { "$ref": "#/$defs/nodeType" },
+                "label": { "type": "string", "minLength": 1 },
+                "path": { "type": "string" },
+                "status": { "type": "string" },
+                "kind": { "type": "string" },
+                "owner": { "type": "string" },
+                "metadata": { "type": "object" },
+                "source": { "$ref": "#/$defs/source" }
+            }
+        },
+        "edge": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["id", "from", "to", "type", "confidence", "reason", "source"],
+            "properties": {
+                "id": { "type": "string", "minLength": 1 },
+                "from": { "type": "string", "minLength": 1 },
+                "to": { "type": "string", "minLength": 1 },
+                "type": { "$ref": "#/$defs/edgeType" },
+                "confidence": { "$ref": "#/$defs/confidence" },
+                "reason": { "type": "string", "minLength": 1 },
+                "source": { "$ref": "#/$defs/source" }
+            }
+        },
+        "candidate": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["id", "type", "reason", "confidence"],
+            "properties": {
+                "id": { "type": "string", "minLength": 1 },
+                "type": { "$ref": "#/$defs/nodeType" },
+                "path": { "type": "string" },
+                "reason": { "type": "string", "minLength": 1 },
+                "confidence": { "$ref": "#/$defs/confidence" },
+                "sourceHash": { "type": "string" }
+            }
+        },
+        "taskContext": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": [
+                "schemaVersion",
+                "taskId",
+                "readFirst",
+                "readIfNeeded",
+                "doNotReadByDefault",
+                "relatedEvidence",
+                "relatedCommands",
+                "knownProblems",
+                "validationSuggestions",
+                "stateIssues",
+                "issues"
+            ],
+            "properties": {
+                "schemaVersion": { "const": "hadara.taskContext.v1" },
+                "taskId": { "type": "string", "minLength": 1 },
+                "task": { "$ref": "#/$defs/node" },
+                "readFirst": { "type": "array", "items": { "$ref": "#/$defs/candidate" } },
+                "readIfNeeded": { "type": "array", "items": { "$ref": "#/$defs/candidate" } },
+                "doNotReadByDefault": { "type": "array", "items": { "$ref": "#/$defs/candidate" } },
+                "relatedEvidence": { "type": "array", "items": { "$ref": "#/$defs/candidate" } },
+                "relatedCommands": { "type": "array", "items": { "$ref": "#/$defs/candidate" } },
+                "knownProblems": { "type": "array", "items": { "$ref": "#/$defs/candidate" } },
+                "validationSuggestions": { "type": "array", "items": { "type": "string" } },
+                "stateIssues": { "type": "array", "items": { "$ref": "#/$defs/stateIssue" } },
+                "issues": { "type": "array", "items": { "$ref": "#/$defs/graphIssue" } }
+            }
+        },
+        "stateProjection": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["schemaVersion", "command", "ok", "generatedAt", "summary", "sources", "issues"],
+            "properties": {
+                "schemaVersion": { "const": "hadara.stateProjection.v1" },
+                "command": { "const": "state.projection" },
+                "ok": { "type": "boolean" },
+                "generatedAt": { "type": "string" },
+                "summary": {
+                    "type": "object",
+                    "additionalProperties": true,
+                    "required": ["stateConsistency"],
+                    "properties": {
+                        "latestCompletedTask": { "type": "string" },
+                        "activeTask": { "type": "string" },
+                        "latestClosedTask": { "type": "string" },
+                        "releaseState": { "type": "string" },
+                        "stateConsistency": { "enum": ["consistent", "warning", "error", "unknown"] }
+                    }
+                },
+                "sources": { "type": "array", "items": { "$ref": "#/$defs/stateSource" } },
+                "issues": { "type": "array", "items": { "$ref": "#/$defs/stateIssue" } }
+            }
+        },
+        "stateSource": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["id", "path", "kind", "extracted"],
+            "properties": {
+                "id": { "type": "string", "minLength": 1 },
+                "path": { "type": "string", "minLength": 1 },
+                "kind": {
+                    "enum": ["task-board", "task-capsule", "project-state", "agent-handoff", "docs-registry", "release-readiness", "evidence", "code-index"]
+                },
+                "hash": { "type": "string" },
+                "extracted": { "type": "object" }
+            }
+        },
+        "stateIssue": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["severity", "code", "message", "paths"],
+            "properties": {
+                "severity": { "enum": ["info", "warning", "error"] },
+                "code": {
+                    "enum": [
+                        "STATE_LATEST_TASK_MISMATCH",
+                        "STATE_ACTIVE_TASK_MISMATCH",
+                        "STATE_TASK_BOARD_MISSING_ROW",
+                        "STATE_TASK_CAPSULE_MISSING",
+                        "STATE_CLOSE_PROOF_STALE",
+                        "STATE_RELEASE_EVIDENCE_STALE",
+                        "STATE_DOC_REQUIRED_READING_DRIFT",
+                        "STATE_UNKNOWN"
+                    ]
+                },
+                "message": { "type": "string", "minLength": 1 },
+                "paths": { "type": "array", "items": { "type": "string" } },
+                "fixHint": { "type": "string" }
+            }
+        },
+        "graphIssue": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["severity", "code", "message"],
+            "properties": {
+                "severity": { "enum": ["info", "warning", "error"] },
+                "code": {
+                    "enum": [
+                        "CONTEXT_GRAPH_SOURCE_MISSING",
+                        "CONTEXT_GRAPH_PARSE_FAILED",
+                        "CONTEXT_GRAPH_DOC_REGISTRY_MISSING",
+                        "CONTEXT_GRAPH_COMMAND_REGISTRY_MISSING",
+                        "CONTEXT_GRAPH_EVIDENCE_READ_FAILED",
+                        "CONTEXT_GRAPH_DEGRADED"
+                    ]
+                },
+                "message": { "type": "string", "minLength": 1 },
+                "path": { "type": "string" },
+                "fixHint": { "type": "string" }
+            }
+        }
+    }
+}

package/dist/schemas/context-pack.schema.json

@@ -0,0 +1,246 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "hadara.contextPack.v1",
+    "x-hadara-schema-id": "hadara.contextPack.v1",
+    "title": "HADARA Context Pack Report",
+    "type": "object",
+    "additionalProperties": true,
+    "required": [
+        "schemaVersion",
+        "command",
+        "ok",
+        "generatedAt",
+        "projectRoot",
+        "budget",
+        "readFirst",
+        "readIfNeeded",
+        "doNotReadByDefault",
+        "validateWith",
+        "writeBoundaries",
+        "sliceCandidates",
+        "knownProblems",
+        "stateProjection",
+        "sourceSummary",
+        "cache",
+        "issues"
+    ],
+    "properties": {
+        "schemaVersion": { "const": "hadara.contextPack.v1" },
+        "command": { "const": "context.pack" },
+        "ok": { "type": "boolean" },
+        "generatedAt": { "type": "string" },
+        "taskId": { "type": "string" },
+        "projectRoot": { "type": "string" },
+        "budget": { "$ref": "#/$defs/budget" },
+        "readFirst": { "type": "array", "items": { "$ref": "#/$defs/item" } },
+        "readIfNeeded": { "type": "array", "items": { "$ref": "#/$defs/item" } },
+        "doNotReadByDefault": { "type": "array", "items": { "$ref": "#/$defs/item" } },
+        "validateWith": { "type": "array", "items": { "$ref": "#/$defs/validationSuggestion" } },
+        "writeBoundaries": { "type": "array", "items": { "$ref": "#/$defs/writeBoundary" } },
+        "sliceCandidates": { "type": "array", "items": { "$ref": "#/$defs/sliceCandidate" } },
+        "knownProblems": { "type": "array", "items": { "$ref": "#/$defs/item" } },
+        "stateProjection": { "$ref": "#/$defs/stateProjection" },
+        "sourceSummary": { "$ref": "#/$defs/sourceSummary" },
+        "cache": { "$ref": "#/$defs/cache" },
+        "issues": { "type": "array", "items": { "$ref": "#/$defs/issue" } }
+    },
+    "$defs": {
+        "confidence": { "enum": ["explicit", "derived", "heuristic"] },
+        "itemType": {
+            "enum": [
+                "Task",
+                "Document",
+                "ManagedSection",
+                "Evidence",
+                "Command",
+                "ReleaseCheck",
+                "Decision",
+                "KnownProblem",
+                "SourceFile",
+                "TestFile",
+                "FixtureFile",
+                "ConfigFile",
+                "Symbol"
+            ]
+        },
+        "budget": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["maxReadFirstItems", "mode"],
+            "properties": {
+                "targetTokens": { "type": "number" },
+                "maxItems": { "type": "number" },
+                "maxReadFirstItems": { "type": "number" },
+                "mode": { "enum": ["minimal", "bounded", "expanded"] }
+            }
+        },
+        "item": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["id", "type", "reason", "confidence", "required"],
+            "properties": {
+                "id": { "type": "string", "minLength": 1 },
+                "type": { "$ref": "#/$defs/itemType" },
+                "path": { "type": "string" },
+                "lineStart": { "type": "number" },
+                "lineEnd": { "type": "number" },
+                "title": { "type": "string" },
+                "reason": { "type": "string", "minLength": 1 },
+                "confidence": { "$ref": "#/$defs/confidence" },
+                "sourceHash": {
+                    "type": "string",
+                    "description": "Hash of the raw-sliceable item file text when available, otherwise the graph node source hash."
+                },
+                "estimatedTokens": { "type": "number" },
+                "required": { "type": "boolean" },
+                "sourceAccess": { "$ref": "#/$defs/sourceAccess" }
+            }
+        },
+        "sourceAccess": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["rawSlice", "reason"],
+            "properties": {
+                "rawSlice": { "enum": ["sliceable", "not-sliceable", "not-applicable"] },
+                "reason": { "type": "string", "minLength": 1 }
+            }
+        },
+        "validationSuggestion": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["command", "reason", "requiredForClose", "source"],
+            "properties": {
+                "command": { "type": "string", "minLength": 1 },
+                "reason": { "type": "string", "minLength": 1 },
+                "requiredForClose": { "type": "boolean" },
+                "source": { "enum": ["task-tests", "command-registry", "evidence-history", "release-readiness", "heuristic"] }
+            }
+        },
+        "writeBoundary": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["path", "boundary", "reason"],
+            "properties": {
+                "path": { "type": "string", "minLength": 1 },
+                "boundary": {
+                    "enum": ["read-only", "agent-freeform", "managed-section", "append-only", "dry-run-first", "release-mutation"]
+                },
+                "reason": { "type": "string", "minLength": 1 }
+            }
+        },
+        "sliceCandidate": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["id", "path", "strategy", "reason", "suggestedCommand", "suggestedCommandArgs"],
+            "properties": {
+                "id": { "type": "string", "minLength": 1 },
+                "path": { "type": "string", "minLength": 1 },
+                "strategy": {
+                    "enum": ["explicit-range", "symbol-neighborhood", "keyword-window", "tail-window", "diff-hunk", "managed-section"]
+                },
+                "lineStart": { "type": "number" },
+                "lineEnd": { "type": "number" },
+                "symbol": { "type": "string" },
+                "managedSection": { "type": "string" },
+                "reason": { "type": "string", "minLength": 1 },
+                "suggestedCommand": { "type": "string", "minLength": 1 },
+                "suggestedCommandArgs": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": { "type": "string", "minLength": 1 }
+                }
+            }
+        },
+        "stateProjection": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["stateConsistency", "issues"],
+            "properties": {
+                "latestCompletedTask": { "type": "string" },
+                "activeTask": { "type": "string" },
+                "latestClosedTask": { "type": "string" },
+                "releaseState": { "type": "string" },
+                "stateConsistency": { "enum": ["consistent", "warning", "error", "unknown"] },
+                "issues": { "type": "array", "items": { "$ref": "#/$defs/stateIssue" } }
+            }
+        },
+        "sourceSummary": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": [
+                "graphAvailable",
+                "codeIndexAvailable",
+                "stateProjectionAvailable",
+                "docsRegistryAvailable",
+                "commandRegistryAvailable",
+                "degraded"
+            ],
+            "properties": {
+                "graphAvailable": { "type": "boolean" },
+                "codeIndexAvailable": { "type": "boolean" },
+                "stateProjectionAvailable": { "type": "boolean" },
+                "docsRegistryAvailable": { "type": "boolean" },
+                "commandRegistryAvailable": { "type": "boolean" },
+                "degraded": { "type": "boolean" },
+                "graphSourceHash": { "type": "string" },
+                "sourcesRead": { "type": "number" }
+            }
+        },
+        "cache": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["used", "hit"],
+            "properties": {
+                "used": { "type": "boolean" },
+                "hit": { "type": "boolean" },
+                "manifestHash": { "type": "string" },
+                "createdAt": { "type": "string" },
+                "cachePath": { "type": "string" }
+            }
+        },
+        "stateIssue": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["severity", "code", "message", "paths"],
+            "properties": {
+                "severity": { "enum": ["info", "warning", "error"] },
+                "code": {
+                    "enum": [
+                        "STATE_LATEST_TASK_MISMATCH",
+                        "STATE_ACTIVE_TASK_MISMATCH",
+                        "STATE_TASK_BOARD_MISSING_ROW",
+                        "STATE_TASK_CAPSULE_MISSING",
+                        "STATE_CLOSE_PROOF_STALE",
+                        "STATE_RELEASE_EVIDENCE_STALE",
+                        "STATE_DOC_REQUIRED_READING_DRIFT",
+                        "STATE_UNKNOWN"
+                    ]
+                },
+                "message": { "type": "string", "minLength": 1 },
+                "paths": { "type": "array", "items": { "type": "string" } },
+                "fixHint": { "type": "string" }
+            }
+        },
+        "issue": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["severity", "code", "message"],
+            "properties": {
+                "severity": { "enum": ["info", "warning", "error"] },
+                "code": {
+                    "enum": [
+                        "CONTEXT_PACK_TASK_NOT_FOUND",
+                        "CONTEXT_PACK_GRAPH_UNAVAILABLE",
+                        "CONTEXT_PACK_CODE_INDEX_UNAVAILABLE",
+                        "CONTEXT_PACK_STATE_PROJECTION_UNAVAILABLE",
+                        "CONTEXT_PACK_BUDGET_TRUNCATED",
+                        "CONTEXT_PACK_DEGRADED"
+                    ]
+                },
+                "message": { "type": "string", "minLength": 1 },
+                "path": { "type": "string" },
+                "fixHint": { "type": "string" }
+            }
+        }
+    }
+}

package/dist/schemas/context-slice.schema.json

@@ -0,0 +1,94 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "hadara.contextSlice.v1",
+    "x-hadara-schema-id": "hadara.contextSlice.v1",
+    "title": "HADARA Context Slice Report",
+    "type": "object",
+    "additionalProperties": true,
+    "required": [
+        "schemaVersion",
+        "command",
+        "ok",
+        "generatedAt",
+        "projectRoot",
+        "path",
+        "sourceHash",
+        "lineCount",
+        "strategy",
+        "slices",
+        "summary",
+        "issues"
+    ],
+    "properties": {
+        "schemaVersion": { "const": "hadara.contextSlice.v1" },
+        "command": { "const": "context.slice" },
+        "ok": { "type": "boolean" },
+        "generatedAt": { "type": "string" },
+        "projectRoot": { "type": "string" },
+        "path": { "type": "string" },
+        "sourceHash": { "type": "string" },
+        "lineCount": { "type": "number" },
+        "strategy": { "$ref": "#/$defs/strategy" },
+        "slices": { "type": "array", "items": { "$ref": "#/$defs/slice" } },
+        "summary": { "$ref": "#/$defs/summary" },
+        "issues": { "type": "array", "items": { "$ref": "#/$defs/issue" } }
+    },
+    "$defs": {
+        "strategy": {
+            "enum": ["explicit-range", "symbol-neighborhood", "keyword-window", "tail-window", "diff-hunk", "managed-section", "context-candidate"]
+        },
+        "slice": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["id", "path", "strategy", "startLine", "endLine", "text", "sourceHash", "reason", "confidence"],
+            "properties": {
+                "id": { "type": "string", "minLength": 1 },
+                "path": { "type": "string", "minLength": 1 },
+                "strategy": { "$ref": "#/$defs/strategy" },
+                "startLine": { "type": "number" },
+                "endLine": { "type": "number" },
+                "text": { "type": "string" },
+                "sourceHash": { "type": "string", "minLength": 1 },
+                "reason": { "type": "string", "minLength": 1 },
+                "confidence": { "enum": ["explicit", "derived", "heuristic"] }
+            }
+        },
+        "summary": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["sliceCount", "totalLines", "totalBytes", "truncated"],
+            "properties": {
+                "sliceCount": { "type": "number" },
+                "totalLines": { "type": "number" },
+                "totalBytes": { "type": "number" },
+                "truncated": { "type": "boolean" }
+            }
+        },
+        "issue": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["severity", "code", "message"],
+            "properties": {
+                "severity": { "enum": ["info", "warning", "error"] },
+                "code": {
+                    "enum": [
+                        "CONTEXT_SLICE_FILE_NOT_FOUND",
+                        "CONTEXT_SLICE_OUTSIDE_PROJECT",
+                        "CONTEXT_SLICE_BINARY_FILE",
+                        "CONTEXT_SLICE_RANGE_INVALID",
+                        "CONTEXT_SLICE_RANGE_CLAMPED",
+                        "CONTEXT_SLICE_SYMBOL_NOT_FOUND",
+                        "CONTEXT_SLICE_KEYWORD_NOT_FOUND",
+                        "CONTEXT_SLICE_CANDIDATE_NOT_FOUND",
+                        "CONTEXT_SLICE_TOO_LARGE",
+                        "CONTEXT_SLICE_UNSUPPORTED_STRATEGY",
+                        "CONTEXT_SLICE_DEGRADED"
+                    ]
+                },
+                "message": { "type": "string", "minLength": 1 },
+                "path": { "type": "string" },
+                "fixHint": { "type": "string" }
+            }
+        }
+    }
+}