@gluecharm-lab/easyspecs-cli 0.0.3

package/resources/schemas/context-lists/use-cases-list.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.ai/schemas/context-lists/use-cases-list.schema.json",
+  "title": "FE-nn-use-cases-list",
+  "$defs": {
+    "sourceReference": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "startLine", "endLine"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[^/]+(/[^/]+)*$",
+          "description": "Repo-relative path to a single file (forward slashes). Not a directory: no trailing slash; list each file in a folder as its own sourceReferences entry."
+        },
+        "startLine": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based inclusive start line."
+        },
+        "endLine": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based inclusive end line; should be >= startLine."
+        },
+        "note": {
+          "type": "string",
+          "description": "Optional short label for this evidence span."
+        }
+      }
+    },
+    "sourceReferenceList": {
+      "type": "array",
+      "description": "Evidence spans: each item references one file + line range, never a folder path.",
+      "items": { "$ref": "#/$defs/sourceReference" }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["featureCode", "useCases"],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "easyspecs.use-cases-list",
+      "description": "Optional coordination document id; when present must be this value."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Optional coordination format version when present."
+    },
+    "featureCode": {
+      "type": "string",
+      "pattern": "^FE-[0-9]+$",
+      "description": "Feature code from features-list.json."
+    },
+    "useCases": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["code", "name", "sourceReferences"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^UC-[0-9]+$"
+          },
+          "name": { "type": "string", "minLength": 1 },
+          "slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "description": "Optional; for FE-nn_UC-uu-<slug>.md if PLAN uses slugs on use cases."
+          },
+          "description": { "type": "string" },
+          "order": { "type": "integer" },
+          "sourceReferences": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Required: at least one file + line range per use case row.",
+            "items": { "$ref": "#/$defs/sourceReference" }
+          }
+        }
+      }
+    },
+    "revisionLog": {
+      "type": "array",
+      "description": "Append-only log of substantive edits; add an entry whenever this pass changes rows, merges, or refines the coordination file.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["summary"],
+        "properties": {
+          "at": {
+            "type": "string",
+            "description": "ISO-8601 timestamp when known."
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000,
+            "description": "What was added, changed, or refined in this write."
+          }
+        }
+      }
+    }
+  }
+}

package/resources/schemas/context-lists/zero-reference-classifier-record.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.ai/schemas/context-lists/zero-reference-classifier-record.schema.json",
+  "title": "zero-reference-classifier-record",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["filePath", "fileKind", "projectRelationSummary", "routing"],
+  "properties": {
+    "filePath": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Repo-relative POSIX path (forward slashes), consistent with SRS-29."
+    },
+    "fileKind": {
+      "type": "string",
+      "enum": [
+        "source",
+        "test",
+        "config",
+        "script",
+        "data",
+        "documentation",
+        "asset_excluded_by_srs29",
+        "unknown"
+      ],
+      "description": "data = CSV/TSV/spreadsheets/dataset exports; documentation = standalone prose (.md/.txt) not yet cited."
+    },
+    "projectRelationSummary": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4000
+    },
+    "routing": {
+      "type": "string",
+      "enum": [
+        "project",
+        "architecture",
+        "feature",
+        "experiences",
+        "services",
+        "data_models",
+        "no_action"
+      ],
+      "description": "Top-level remediation bucket (SRS-30 v0.6). ORM/table units → data_models; product overview → project; system structure → architecture."
+    },
+    "rationale": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4000
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "routing": { "const": "no_action" } },
+        "required": ["routing"]
+      },
+      "then": { "required": ["rationale"] }
+    }
+  ]
+}

package/resources/schemas/context-lists/zero-reference-routing.schema.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.ai/schemas/context-lists/zero-reference-routing.schema.json",
+  "title": "zero-reference-routing",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "records"],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "1"
+    },
+    "coverageReferenceGeneratedAt": {
+      "type": "string",
+      "description": "ISO-8601 from coverage-reference-validation.json when last aligned."
+    },
+    "records": {
+      "type": "object",
+      "description": "Keys are repo-relative file paths; values are classifier records plus merge metadata.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "filePath",
+          "fileKind",
+          "projectRelationSummary",
+          "routing",
+          "generatedAt",
+          "classifierAgentStem"
+        ],
+        "properties": {
+          "filePath": { "type": "string", "minLength": 1 },
+          "fileKind": {
+            "type": "string",
+            "enum": [
+              "source",
+              "test",
+              "config",
+              "script",
+              "data",
+              "documentation",
+              "asset_excluded_by_srs29",
+              "unknown"
+            ]
+          },
+          "projectRelationSummary": { "type": "string", "minLength": 1, "maxLength": 4000 },
+          "routing": {
+            "type": "string",
+            "enum": [
+              "project",
+              "architecture",
+              "feature",
+              "experiences",
+              "services",
+              "data_models",
+              "no_action",
+              "document_project_md",
+              "document_architecture_md",
+              "coordination_follow_up"
+            ]
+          },
+          "coordinationScope": {
+            "type": "string",
+            "enum": [
+              "feature",
+              "use_case",
+              "scenario",
+              "service",
+              "experience",
+              "behavior",
+              "data_model",
+              "field_domain"
+            ]
+          },
+          "rationale": { "type": "string", "minLength": 1, "maxLength": 4000 },
+          "generatedAt": { "type": "string", "minLength": 1 },
+          "classifierAgentStem": { "type": "string", "minLength": 1 }
+        },
+        "allOf": [
+          {
+            "if": {
+              "properties": { "routing": { "const": "no_action" } },
+              "required": ["routing"]
+            },
+            "then": { "required": ["rationale"] }
+          },
+          {
+            "if": {
+              "properties": { "routing": { "const": "coordination_follow_up" } },
+              "required": ["routing"]
+            },
+            "then": { "required": ["coordinationScope"] }
+          }
+        ]
+      }
+    }
+  }
+}

package/resources/schemas/context-lists/zero-reference-triage-record.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.ai/schemas/context-lists/zero-reference-triage-record.schema.json",
+  "title": "zero-reference-triage-record",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["filePath", "coordinationScope", "decision", "evidenceNotes"],
+  "properties": {
+    "filePath": { "type": "string", "minLength": 1 },
+    "coordinationScope": {
+      "type": "string",
+      "enum": ["feature", "experience", "service", "data_model"],
+      "description": "Must match stage-1 routing: feature | experiences | services | data_models → feature | experience | service | data_model."
+    },
+    "decision": {
+      "type": "string",
+      "enum": ["new_item", "enrich_existing", "defer", "no_action"]
+    },
+    "targetItemRef": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable id e.g. FE-01 when decision is enrich_existing."
+    },
+    "proposedSummary": { "type": "string", "minLength": 1, "maxLength": 4000 },
+    "proposedCode": {
+      "type": "string",
+      "pattern": "^(FE|XP|SV|DM)-[0-9]+$",
+      "description": "Optional explicit list code for new_item (FE/XP/SV/DM prefix matches scope)."
+    },
+    "proposedSlug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "description": "Kebab-case slug for new feature row."
+    },
+    "evidenceNotes": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "minItems": 0
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "decision": { "const": "enrich_existing" } },
+        "required": ["decision"]
+      },
+      "then": { "required": ["targetItemRef"] }
+    },
+    {
+      "if": {
+        "properties": { "decision": { "const": "new_item" } },
+        "required": ["decision"]
+      },
+      "then": { "required": ["proposedSummary"] }
+    }
+  ]
+}

package/resources/schemas/context-lists/zero-reference-triage.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.ai/schemas/context-lists/zero-reference-triage.schema.json",
+  "title": "zero-reference-triage",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "records"],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "1"
+    },
+    "records": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "filePath",
+          "coordinationScope",
+          "decision",
+          "evidenceNotes",
+          "generatedAt",
+          "triageAgentStem"
+        ],
+        "properties": {
+          "filePath": { "type": "string", "minLength": 1 },
+          "coordinationScope": {
+            "type": "string",
+            "enum": ["feature", "experience", "service", "data_model"]
+          },
+          "decision": {
+            "type": "string",
+            "enum": ["new_item", "enrich_existing", "defer", "no_action"]
+          },
+          "targetItemRef": { "type": "string", "minLength": 1 },
+          "proposedSummary": { "type": "string", "minLength": 1, "maxLength": 4000 },
+          "proposedCode": { "type": "string", "pattern": "^(FE|XP|SV|DM)-[0-9]+$" },
+          "proposedSlug": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+          },
+          "evidenceNotes": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "generatedAt": { "type": "string", "minLength": 1 },
+          "triageAgentStem": { "type": "string", "minLength": 1 }
+        },
+        "allOf": [
+          {
+            "if": {
+              "properties": { "decision": { "const": "enrich_existing" } },
+              "required": ["decision"]
+            },
+            "then": { "required": ["targetItemRef"] }
+          },
+          {
+            "if": {
+              "properties": { "decision": { "const": "new_item" } },
+              "required": ["decision"]
+            },
+            "then": { "required": ["proposedSummary"] }
+          }
+        ]
+      }
+    }
+  }
+}

package/resources/schemas/index-application-context.schema.json

@@ -0,0 +1,202 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.ai/schemas/index-application-context.schema.json",
+  "title": "index-application-context",
+  "description": "Application-wide scope aggregate for `.gluecharm/context/index-application-context.json` (srs-4). Optional `detailMarkdownPaths` on nodes: srs-10. Optional root `repository` (Git provenance): srs-15. Optional `indexSrsDiscoveryId` / node `srsDiscoveryId`: srs-26.",
+  "$defs": {
+    "repositoryProvenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Git / remote identity for the worktree that produced this index (srs-15).",
+      "required": ["localName", "remoteProvider", "remoteRepository", "commit"],
+      "properties": {
+        "localName": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Basename of `git rev-parse --show-toplevel`."
+        },
+        "remoteProvider": {
+          "type": "string",
+          "enum": ["github", "gitlab", "bitbucket", "azure_devops", "other", "unknown"],
+          "description": "Derived from `origin` URL hostname; `unknown` when missing or unparseable."
+        },
+        "remoteRepository": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Canonical path on host (e.g. org/repo), or the literal `unknown`."
+        },
+        "commit": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{40}$",
+          "description": "Full SHA-1 of `HEAD` at index generation (lowercase hex)."
+        },
+        "branch": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Primary repository branch short name when the analysis worktree was created (EasySpecs `git worktree add --detach` source); not the temp worktree’s later checkout. Omitted if primary `HEAD` was detached at creation or unknown."
+        },
+        "originUrl": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Raw `git remote get-url origin` when available."
+        }
+      }
+    },
+    "contextRelativeMarkdownPath": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Path relative to `.gluecharm/context/` (same folder as this index). Forward slashes only; must not contain `..` or backslashes; must end with `.md`.",
+      "pattern": "^(?!/)(?!.*\\.\\./)[^\\\\\\u0000-\\u001f]+\\.md$"
+    },
+    "impactNode": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "name"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Node kind in the five-scope tree (e.g. Feature, UseCase, Scenario, View, Interaction, Service, Method, Entity, Field, Relationship, Tool)."
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "code": {
+          "type": "string",
+          "description": "Stable id prefix conventions: FE-*, UC-*, SC-*, XP-*, BH-*, SV-*, ME-*, DM-*, FD-*, RL-*, TS-*."
+        },
+        "drift": {
+          "type": "boolean",
+          "description": "When true, UI may show a drift tag (srs-3 / srs-4)."
+        },
+        "detailMarkdownPaths": {
+          "type": "array",
+          "description": "Optional pointers to detail markdown under `.gluecharm/context/` (srs-10). Omitted or empty when not used.",
+          "items": {
+            "$ref": "#/$defs/contextRelativeMarkdownPath"
+          }
+        },
+        "detailMarkdownFile": {
+          "description": "Single detail markdown reference (UI / tooling). Legacy: `filename` + `path`. SRS-26: `path` only with optional `srsDiscoveryId` after upload.",
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "Legacy srs-10 shape (basename duplicated from path).",
+              "required": ["filename", "path"],
+              "properties": {
+                "filename": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Markdown filename (typically basename of `path`)."
+                },
+                "path": {
+                  "$ref": "#/$defs/contextRelativeMarkdownPath",
+                  "description": "Path relative to `.gluecharm/context/` (same folder as this index)."
+                }
+              }
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "SRS-26: one authoritative path; optional CMS id after srs_discovery upload.",
+              "required": ["path"],
+              "properties": {
+                "path": {
+                  "$ref": "#/$defs/contextRelativeMarkdownPath",
+                  "description": "Path relative to `.gluecharm/context/` (same folder as this index)."
+                },
+                "srsDiscoveryId": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
+                  "description": "`srs_discovery` row id (client-sent `item.id` on upload) for this detail file."
+                }
+              }
+            }
+          ]
+        },
+        "children": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/impactNode"
+          }
+        }
+      }
+    },
+    "scopeBlock": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["nodes"],
+      "properties": {
+        "nodes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/impactNode"
+          }
+        }
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["kind", "version", "title", "driftCount", "scopes"],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "easyspecs.application-context"
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Schema/document version. srs-10: use 2 when any node includes `detailMarkdownPaths` and/or `detailMarkdownFile`."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Panel header title (e.g. Application context)."
+    },
+    "generatedAt": {
+      "type": "string",
+      "description": "ISO-8601 timestamp when the file was produced (recommended). srs-15: required when programmatic writer emits `repository` (same instant as assembly)."
+    },
+    "repository": {
+      "$ref": "#/$defs/repositoryProvenance",
+      "description": "Optional Git provenance for the analysis worktree (srs-15)."
+    },
+    "indexSrsDiscoveryId": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
+      "description": "Optional `srs_discovery` id for this index file after upload (srs-26). Omitted in Phase A."
+    },
+    "driftCount": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Non-negative aggregate for row badge semantics (srs-4)."
+    },
+    "scopes": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Five scope keys; each block may be omitted in minimal JSON but this object is required (may be empty object for edge cases — prefer omitting empty scopes in writers).",
+      "properties": {
+        "Feature": {
+          "$ref": "#/$defs/scopeBlock"
+        },
+        "Experience": {
+          "$ref": "#/$defs/scopeBlock"
+        },
+        "Service": {
+          "$ref": "#/$defs/scopeBlock"
+        },
+        "DataModel": {
+          "$ref": "#/$defs/scopeBlock"
+        },
+        "TechStack": {
+          "$ref": "#/$defs/scopeBlock"
+        }
+      }
+    }
+  }
+}