@osovv/vv-opencode 1.3.6-rc.6 → 1.3.6-rc.8

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## <small>1.3.6-rc.8 (2026-08-29)</small>
+
+### Summary
+
+This release fixes a reliability issue in the spec-guard plugin and corrects the documented GRACE CLI workflow. Read-path validation previously linted the tool's rendered output, which hosts may decorate with envelope tags and line-number prefixes, causing false well-formedness errors on valid spec files; read verdicts are now derived from the actual artifact file on disk, so validation results are accurate and independent of host rendering. In addition, the agent documentation now directs users to invoke the installed stable `grace` binary directly rather than the stale `rc` dist-tag, ensuring linting and status checks run against the correct validator version.
+
+* docs(agents): invoke the installed grace binary instead of the stale rc tag ([8e59a00](https://github.com/osovv/vv-opencode/commit/8e59a00))
+* fix(spec-guard): derive read verdicts from the artifact file, not the tool rendering ([ea8bd52](https://github.com/osovv/vv-opencode/commit/ea8bd52))
+
+## <small>1.3.6-rc.7 (2026-08-29)</small>
+
+### Summary
+
+This release introduces deterministic, host-side verification for spec-package artifacts with a new COMPONENT identity format: spec, plan, and design-context components now share element-name identities across documents, fields are unified to snake_case, and the plan-subset-of-spec traceability rule is enforced mechanically rather than left to convention. A new strict lint engine checks well-formedness, template contracts, identity uniqueness, references, and lifecycle-aware severity, with results cached content-addressed under the XDG cache home. Users get a new `vvoc lint` command that targets files, packages, or whole specs trees with stable exit codes plus strict, JSON, no-cache, and archive flags (archived packages are skipped by default), and a new SpecGuardPlugin that appends lint verdicts to reads of active artifacts and validates writes through the same cache, defaulting to warn mode while enforce only refuses ERROR-severity writes so in-progress draft composition is never blocked and internal failures degrade fail-open. Schema v3, plugin toggles, exports, templates, skills, and README stay synchronized with the new format and command.
+
+* feat(spec-lint): add COMPONENT identity format, vvoc lint, and spec-guard ([a28cde6](https://github.com/osovv/vv-opencode/commit/a28cde6))
+
 ## <small>1.3.6-rc.6 (2026-08-27)</small>
 
 ### Summary

package/README.md

@@ -146,12 +146,13 @@ All artifacts for one feature live together:
 
 Package ids are date-prefixed (`YYYY-MM-DD-<slug>`, for example `2026-06-24-cache-store`) so active packages sort by creation date; the prefix is date-only, never a full timestamp. Spec and plan lifecycle runs through a top-level status: `draft` while being written, `approved` after explicit user approval, `applied` after successful execution. `vv-execute` archives applied packages by moving the whole directory to `.vvoc/specs/archive/YYYY-MM-DD-<slug>-<timestamp>/`.
 
-Specs and plans are XML, so requirements, tasks, acceptance criteria, and dependencies stay grep-able. Task and wave identity lives in unique element names (`<TASK-T-001>…</TASK-T-001>`, `<WAVE-1>…</WAVE-1>`), so grep/sed extraction stays exact without a separate query language:
+Specs and plans are XML, so requirements, tasks, acceptance criteria, and dependencies stay grep-able. Identity lives in unique element names — tasks and waves as `<TASK-T-001>…</TASK-T-001>` and `<WAVE-1>…</WAVE-1>`, spec and plan components as `<COMPONENT-CACHE-STORE>…</COMPONENT-CACHE-STORE>` — so grep/sed extraction stays exact without a separate query language. Field names use snake_case; component references are bare slugs; plan architecture components always reuse the exact identities declared in spec.xml, so a plan component without a spec component is a lint error, not a convention breach:
 
 ```bash
 grep '<TASK-T-' .vvoc/specs/*/plan.xml      # task ids
 grep '<criterion>' .vvoc/specs/*/plan.xml   # acceptance criteria
 grep '<task_id>' .vvoc/specs/*/plan.xml     # dependency graph
+grep '<COMPONENT-' .vvoc/specs/*/*.xml      # component map across spec and plan
 ```
 
 `vv-controller` explicitly routes `vv-spec`, `vv-plan`, and `vv-review`; `vv-execute`, `vv-reflect`, and `vv-handoff` are available as managed skills for plan execution, durable repository memory, and end-of-session handoff notes.
@@ -160,7 +161,7 @@ grep '<task_id>' .vvoc/specs/*/plan.xml     # dependency graph
 
 ## What's inside
 
-### The eleven plugins
+### The twelve plugins
 
 | Plugin | What it does |
 |---|---|
@@ -174,6 +175,7 @@ grep '<task_id>' .vvoc/specs/*/plan.xml     # dependency graph
 | **ToolHistoryCompactionPlugin** | Shrinks the context replayed to the model by compacting old tool outputs non-destructively, without touching on-disk history. |
 | **AnalyticsPlugin** | Local-only token and cache telemetry per model step, a live `cache NN%` indicator in the TUI, and `vvoc analytics cache-hit-rate` for retrospective comparison. |
 | **PeakHoursPlugin** | Warns or blocks models whose provider is in peak-priced hours right now, suggests connected off-peak providers, and shows a persistent orange banner in the TUI. |
+| **SpecGuardPlugin** | Deterministic host-side verification of spec-package artifacts: annotates reads with lint verdicts and validates writes; in enforce mode refuses writes that would break the format. |
 | **ContextTuiPlugin** | The `/context` inspector: an honest, scrollable TUI dialog showing context-window usage by category, tool, and MCP server. |
 
 ### Managed agents
@@ -541,6 +543,34 @@ Config lives in `vvoc.json` under `plugins["peak-hours"]` and is conservatively
 
 Windows use `HH:MM` in an explicit timezone (default UTC), may cross midnight (`"start": "22:00", "end": "02:00"`), and accept an optional `days` restriction (0=Sunday … 6=Saturday, default all days). A provider entry may override the global mode with `"mode": "hard"`. Set the top-level `"mode": "hard"` to enforce blocking everywhere, or `"enabled": false` to disable the plugin entirely. Changes require an OpenCode restart, like other runtime plugin settings.
 
+### Spec lint and spec-guard
+
+The spec-package format is verified by deterministic host-side tooling, not by model discipline: models keep grep/sed as their query layer, and `vvoc lint` plus `SpecGuardPlugin` enforce the invariants in code.
+
+```bash
+vvoc lint                                    # lint .vvoc/specs (active packages only)
+vvoc lint .vvoc/specs/2026-08-24-cache/      # one package directory
+vvoc lint .vvoc/specs/2026-08-24-cache/plan.xml   # one file (its sibling spec joins for cross-file rules)
+vvoc lint --archive                          # include archived packages for migration audits
+vvoc lint --strict                           # exit 1 on warnings, not only errors
+vvoc lint --format json --no-cache           # one JSON verdict object; bypass the cache
+```
+
+The engine checks well-formedness, the attribute ban, the template contract per artifact type, `COMPONENT-UPPER-SLUG` / `TASK-T-NNN` / `WAVE-N` identity patterns and uniqueness, reference integrity (component slugs, task ids), the **plan-components-subset-of-spec-components** rule, lifecycle vocabulary, and package layout. Severity is lifecycle-aware: a `draft` document may have empty sections mid-interview and is never an error; `approved`/`applied` documents must be complete. Exit codes are stable for scripts: `0` without errors, `1` with errors, `--strict` escalates warnings. Results are cached content-addressed under `$XDG_CACHE_HOME/vvoc/lint/` — a verdict is recomputed whenever any input byte or the lint rule version changes.
+
+`SpecGuardPlugin` brings the same verdicts into the session:
+
+- **reads**: reading an active `spec.xml` / `plan.xml` / `design-context.xml` appends a bounded `[spec-guard]` verdict to the tool result, so agents see drift before trusting the file; archived files are never annotated;
+- **writes**: `warn` (default) appends the verdict after a write; `enforce` additionally refuses writes whose result would contain ERROR-severity findings — incremental draft editing is never blocked, because draft incompleteness is never an error.
+
+```json
+"plugins": {
+  "spec-guard": { "enabled": true, "mode": "warn" }
+}
+```
+
+Conservatively materialized by `vvoc sync`/`init`; `enforce` blocks only ERROR states; internal failures degrade to a warning log and never break a tool call. Changes require an OpenCode restart, like other runtime plugin settings.
+
 ### Web tools
 
 `WebToolsPlugin` exposes exactly two canonical model-facing tools:

package/dist/cli.js

@@ -3,8 +3,8 @@
 // VERSION: 0.2.10
 // START_MODULE_CONTRACT
 //   PURPOSE: Assemble and run the vvoc CLI entrypoint.
-//   SCOPE: Package version lookup, top-level command registration, and main command execution.
-//   DEPENDS: [citty, src/commands/analytics.ts, src/commands/completion.ts, src/commands/config.ts, src/commands/doctor.ts, src/commands/guardian.ts, src/commands/init.ts, src/commands/install.ts, src/commands/launch.ts, src/commands/orchestration.ts, src/commands/patch-provider.ts, src/commands/preset.ts, src/commands/plugin.ts, src/commands/role.ts, src/commands/status.ts, src/commands/sync.ts, src/commands/upgrade.ts, src/commands/version.ts, src/lib/package.ts]
+//   SCOPE: Package version lookup, top-level command registration including the lint command, and main command execution.
+//   DEPENDS: [citty, src/commands/analytics.ts, src/commands/completion.ts, src/commands/config.ts, src/commands/doctor.ts, src/commands/guardian.ts, src/commands/init.ts, src/commands/install.ts, src/commands/launch.ts, src/commands/orchestration.ts, src/commands/lint.ts, src/commands/patch-provider.ts, src/commands/preset.ts, src/commands/plugin.ts, src/commands/role.ts, src/commands/status.ts, src/commands/sync.ts, src/commands/upgrade.ts, src/commands/version.ts, src/lib/package.ts]
 //   LINKS: [M-CLI-COMMANDS]
 //   ROLE: SCRIPT
 //   MAP_MODE: LOCALS
@@ -16,7 +16,7 @@
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [2026-08-19-cache-hit-rate-analytics - Registered the analytics command in the CLI tree.]
+//   LAST_CHANGE: [C-SPEC-IDENTITY-LINT - Registered the lint command in the CLI tree.]
 // END_CHANGE_SUMMARY
 import { defineCommand, runMain } from "citty";
 import analytics from "./commands/analytics.js";
@@ -27,6 +27,7 @@ import guardian from "./commands/guardian.js";
 import init from "./commands/init.js";
 import install from "./commands/install.js";
 import launch from "./commands/launch.js";
+import lint from "./commands/lint.js";
 import orchestration from "./commands/orchestration.js";
 import patchProvider from "./commands/patch-provider.js";
 import preset from "./commands/preset.js";
@@ -54,6 +55,7 @@ const main = defineCommand({
         init,
         install,
         launch,
+        lint,
         orchestration,
         "patch-provider": patchProvider,
         preset,

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,mBAAmB;AACnB,kBAAkB;AAClB,wBAAwB;AACxB,uDAAuD;AACvD,+FAA+F;AAC/F,sdAAsd;AACtd,4BAA4B;AAC5B,iBAAiB;AACjB,qBAAqB;AACrB,sBAAsB;AACtB,EAAE;AACF,mBAAmB;AACnB,oEAAoE;AACpE,wCAAwC;AACxC,iBAAiB;AACjB,EAAE;AACF,uBAAuB;AACvB,2GAA2G;AAC3G,qBAAqB;AAErB,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAC/C,OAAO,SAAS,MAAM,yBAAyB,CAAC;AAChD,OAAO,UAAU,MAAM,0BAA0B,CAAC;AAClD,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,QAAQ,MAAM,wBAAwB,CAAC;AAC9C,OAAO,IAAI,MAAM,oBAAoB,CAAC;AACtC,OAAO,OAAO,MAAM,uBAAuB,CAAC;AAC5C,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,aAAa,MAAM,6BAA6B,CAAC;AACxD,OAAO,aAAa,MAAM,8BAA8B,CAAC;AACzD,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,IAAI,MAAM,oBAAoB,CAAC;AACtC,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,IAAI,MAAM,oBAAoB,CAAC;AACtC,OAAO,OAAO,MAAM,uBAAuB,CAAC;AAC5C,OAAO,OAAO,MAAM,uBAAuB,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,iCAAiC;AACjC,MAAM,cAAc,GAAG,MAAM,iBAAiB,EAAE,CAAC;AAEjD,MAAM,IAAI,GAAG,aAAa,CAAC;IACzB,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,cAAc;QACvB,WAAW,EACT,+HAA+H;KAClI;IACD,WAAW,EAAE;QACX,SAAS;QACT,UAAU;QACV,MAAM;QACN,MAAM;QACN,QAAQ;QACR,IAAI;QACJ,OAAO;QACP,MAAM;QACN,aAAa;QACb,gBAAgB,EAAE,aAAa;QAC/B,MAAM;QACN,MAAM;QACN,IAAI;QACJ,MAAM;QACN,IAAI;QACJ,OAAO;QACP,OAAO;KACR;CACF,CAAC,CAAC;AACH,+BAA+B;AAE/B,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,mBAAmB;AACnB,kBAAkB;AAClB,wBAAwB;AACxB,uDAAuD;AACvD,0HAA0H;AAC1H,4eAA4e;AAC5e,4BAA4B;AAC5B,iBAAiB;AACjB,qBAAqB;AACrB,sBAAsB;AACtB,EAAE;AACF,mBAAmB;AACnB,oEAAoE;AACpE,wCAAwC;AACxC,iBAAiB;AACjB,EAAE;AACF,uBAAuB;AACvB,uFAAuF;AACvF,qBAAqB;AAErB,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAC/C,OAAO,SAAS,MAAM,yBAAyB,CAAC;AAChD,OAAO,UAAU,MAAM,0BAA0B,CAAC;AAClD,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,QAAQ,MAAM,wBAAwB,CAAC;AAC9C,OAAO,IAAI,MAAM,oBAAoB,CAAC;AACtC,OAAO,OAAO,MAAM,uBAAuB,CAAC;AAC5C,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,IAAI,MAAM,oBAAoB,CAAC;AACtC,OAAO,aAAa,MAAM,6BAA6B,CAAC;AACxD,OAAO,aAAa,MAAM,8BAA8B,CAAC;AACzD,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,IAAI,MAAM,oBAAoB,CAAC;AACtC,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,IAAI,MAAM,oBAAoB,CAAC;AACtC,OAAO,OAAO,MAAM,uBAAuB,CAAC;AAC5C,OAAO,OAAO,MAAM,uBAAuB,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,iCAAiC;AACjC,MAAM,cAAc,GAAG,MAAM,iBAAiB,EAAE,CAAC;AAEjD,MAAM,IAAI,GAAG,aAAa,CAAC;IACzB,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,cAAc;QACvB,WAAW,EACT,+HAA+H;KAClI;IACD,WAAW,EAAE;QACX,SAAS;QACT,UAAU;QACV,MAAM;QACN,MAAM;QACN,QAAQ;QACR,IAAI;QACJ,OAAO;QACP,MAAM;QACN,IAAI;QACJ,aAAa;QACb,gBAAgB,EAAE,aAAa;QAC/B,MAAM;QACN,MAAM;QACN,IAAI;QACJ,MAAM;QACN,IAAI;QACJ,OAAO;QACP,OAAO;KACR;CACF,CAAC,CAAC;AACH,+BAA+B;AAE/B,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/commands/lint.d.ts

@@ -0,0 +1,74 @@
+import { type SpecLintVerdict } from "../lib/spec-lint.js";
+export declare const ARTIFACT_FILE_NAMES: readonly ["spec.xml", "plan.xml", "design-context.xml"];
+export interface LintCommandOptions {
+    /** File, package directory, or specs tree to lint. Defaults to .vvoc/specs. */
+    target: string;
+    /** Include archived packages instead of skipping them. */
+    includeArchive: boolean;
+    /** Escalate warnings to exit failure. */
+    strict: boolean;
+    /** Bypass the lint cache entirely. */
+    noCache: boolean;
+}
+export interface LintArtifactResult {
+    verdict: SpecLintVerdict;
+    cached: boolean;
+}
+export interface LintRunResult {
+    lintVersion: number;
+    target: string;
+    skippedArchived: number;
+    packages: Array<{
+        dir: string;
+        artifacts: LintArtifactResult[];
+    }>;
+}
+export declare const DEFAULT_LINT_TARGET = ".vvoc/specs";
+/**
+ * Resolve a lint target into package groups. A file target becomes its own
+ * group (plus the sibling spec as a cross-file input for plan targets) with
+ * the requested file marked as the reporting primary; a directory target
+ * walks recursively and groups artifacts by containing directory. Archived
+ * files are counted and skipped unless included explicitly.
+ */
+export declare function collectLintTargets(target: string, includeArchive: boolean): Promise<{
+    groups: Array<{
+        dir: string;
+        files: string[];
+        primary?: string;
+    }>;
+    skippedArchived: number;
+}>;
+/** Execute one lint run over resolved targets through the content-addressed cache. */
+export declare function runLint(options: LintCommandOptions, cacheRoot?: string): Promise<LintRunResult>;
+export declare function renderLintReport(result: LintRunResult, strict: boolean): string;
+export declare function computeLintExitCode(result: LintRunResult, strict: boolean): 0 | 1;
+declare const _default: import("citty").CommandDef<{
+    readonly path: {
+        readonly type: "positional";
+        readonly description: "File, package directory, or specs tree to lint (default: .vvoc/specs)";
+        readonly fallback: ".vvoc/specs";
+    };
+    readonly strict: {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly description: "Fail on warnings, not only errors.";
+    };
+    readonly format: {
+        readonly type: "enum";
+        readonly options: ["text", "json"];
+        readonly default: "text";
+        readonly description: "Output format.";
+    };
+    readonly "no-cache": {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly description: "Bypass the content-addressed lint cache.";
+    };
+    readonly archive: {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly description: "Include archived packages instead of skipping them.";
+    };
+}>;
+export default _default;

package/dist/commands/lint.js

@@ -0,0 +1,269 @@
+// FILE: src/commands/lint.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Lint .vvoc spec-package XML artifacts (spec.xml, plan.xml, design-context.xml) with lifecycle-aware severity and stable exit codes.
+//   SCOPE: Target resolution for a file, package directory, or specs tree; package grouping with cross-file sibling spec inputs; archive skipping with a visible count unless --archive; cache-backed lint runs; text and JSON output; exit code 0 without errors, 1 with errors, --strict escalating warnings.
+//   DEPENDS: [citty, node:fs/promises, node:path, src/lib/spec-lint.ts, src/lib/spec-lint-cache.ts]
+//   LINKS: [M-CLI-COMMANDS, M-SPEC-LINT]
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   LintCommandOptions - Core lint-run options shared by the CLI and tests.
+//   LintArtifactResult - One artifact's verdict plus its cache-hit flag.
+//   LintRunResult - Structured result of one lint run over resolved targets.
+//   ARTIFACT_FILE_NAMES - Recognized spec-package artifact file names.
+//   DEFAULT_LINT_TARGET - Default lint target path (.vvoc/specs).
+//   collectLintTargets - Resolve a path into package groups plus an archive skip count.
+//   runLint - Execute the lint run over resolved targets through the cache.
+//   renderLintReport - Render the text report for a lint run result.
+//   computeLintExitCode - Map a run result to the stable exit-code contract.
+//   default - vvoc lint command definition.
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [C-SPEC-IDENTITY-LINT - Initial command: file/package/tree targets, lifecycle-aware severity, archive skip, cache integration, strict/json flags.]
+// END_CHANGE_SUMMARY
+import { defineCommand } from "citty";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { isSpecArchivePath, LINT_VERSION, } from "../lib/spec-lint.js";
+import { createSpecLintCache } from "../lib/spec-lint-cache.js";
+// START_BLOCK_TYPES
+export const ARTIFACT_FILE_NAMES = ["spec.xml", "plan.xml", "design-context.xml"];
+export const DEFAULT_LINT_TARGET = ".vvoc/specs";
+// END_BLOCK_TYPES
+// START_BLOCK_TARGET_RESOLUTION
+async function walkXmlArtifacts(root, base, found) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = join(root, entry.name);
+        if (entry.isDirectory()) {
+            await walkXmlArtifacts(full, base, found);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        if (!ARTIFACT_FILE_NAMES.includes(entry.name))
+            continue;
+        const relativePath = relative(base, full).replace(/\\/g, "/");
+        found.push({ path: full, archived: isSpecArchivePath(relativePath) });
+    }
+}
+/**
+ * Resolve a lint target into package groups. A file target becomes its own
+ * group (plus the sibling spec as a cross-file input for plan targets) with
+ * the requested file marked as the reporting primary; a directory target
+ * walks recursively and groups artifacts by containing directory. Archived
+ * files are counted and skipped unless included explicitly.
+ */
+export async function collectLintTargets(target, includeArchive) {
+    const absolute = resolve(target);
+    let targetStat;
+    try {
+        targetStat = await stat(absolute);
+    }
+    catch {
+        throw new Error(`lint target not found: ${target}`);
+    }
+    if (targetStat.isFile()) {
+        const fileName = absolute.split(/[/\\]/).pop() ?? "";
+        if (!ARTIFACT_FILE_NAMES.includes(fileName)) {
+            throw new Error(`not a spec-package artifact: ${fileName} (expected ${ARTIFACT_FILE_NAMES.join(", ")})`);
+        }
+        const files = [absolute];
+        if (fileName === "plan.xml") {
+            const sibling = join(dirname(absolute), "spec.xml");
+            try {
+                await stat(sibling);
+                files.push(sibling);
+            }
+            catch {
+                // Missing sibling degrades to the engine's spec-missing warning.
+            }
+        }
+        return {
+            groups: [{ dir: dirname(absolute), files, primary: absolute.replace(/\\/g, "/") }],
+            skippedArchived: 0,
+        };
+    }
+    const found = [];
+    await walkXmlArtifacts(absolute, absolute, found);
+    const groups = new Map();
+    let skippedArchived = 0;
+    for (const item of found) {
+        if (item.archived && !includeArchive) {
+            skippedArchived++;
+            continue;
+        }
+        const dir = dirname(item.path);
+        const bucket = groups.get(dir) ?? [];
+        bucket.push(item.path);
+        groups.set(dir, bucket);
+    }
+    return {
+        groups: [...groups.entries()]
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([dir, files]) => ({ dir, files })),
+        skippedArchived,
+    };
+}
+// END_BLOCK_TARGET_RESOLUTION
+// START_BLOCK_RUN
+async function readArtifactInputs(files) {
+    const inputs = [];
+    for (const file of files.sort()) {
+        try {
+            const content = await readFile(file, "utf8");
+            inputs.push({ file: file.replace(/\\/g, "/"), content });
+        }
+        catch {
+            // Unreadable files degrade to an explicit finding through the engine's unknown path.
+            inputs.push({ file: file.replace(/\\/g, "/"), content: "" });
+        }
+    }
+    return inputs;
+}
+/** Execute one lint run over resolved targets through the content-addressed cache. */
+export async function runLint(options, cacheRoot) {
+    const cache = await createSpecLintCache({ cacheRoot, bypass: options.noCache });
+    const { groups, skippedArchived } = await collectLintTargets(options.target, options.includeArchive);
+    const packages = [];
+    for (const group of groups) {
+        const inputs = await readArtifactInputs(group.files);
+        const result = await cache.lint(inputs);
+        const byFile = new Map(result.verdicts.map((v) => [v.file, v]));
+        const reportFiles = group.primary
+            ? group.files.filter((file) => file.replace(/\\/g, "/") === group.primary)
+            : group.files;
+        const artifacts = reportFiles
+            .map((file) => file.replace(/\\/g, "/"))
+            .filter((file) => byFile.has(file))
+            .map((file) => ({ verdict: byFile.get(file), cached: result.hit }));
+        packages.push({ dir: group.dir.replace(/\\/g, "/"), artifacts });
+    }
+    return { lintVersion: LINT_VERSION, target: options.target, skippedArchived, packages };
+}
+// END_BLOCK_RUN
+// START_BLOCK_REPORT
+export function renderLintReport(result, strict) {
+    const lines = [];
+    let artifacts = 0;
+    let errors = 0;
+    let warnings = 0;
+    for (const pkg of result.packages) {
+        const pkgErrors = pkg.artifacts.reduce((sum, a) => sum + a.verdict.findings.filter((f) => f.severity === "error").length, 0);
+        const pkgWarnings = pkg.artifacts.reduce((sum, a) => sum + a.verdict.findings.filter((f) => f.severity === "warning").length, 0);
+        artifacts += pkg.artifacts.length;
+        errors += pkgErrors;
+        warnings += pkgWarnings;
+        lines.push(`${pkg.dir}: ${pkg.artifacts.length} artifact(s), ${pkgErrors} error(s), ${pkgWarnings} warning(s)`);
+        for (const artifact of pkg.artifacts) {
+            const name = artifact.verdict.file.split("/").pop() ?? artifact.verdict.file;
+            if (artifact.verdict.findings.length === 0) {
+                lines.push(`  ${name}: OK${artifact.cached ? " (cached)" : ""}`);
+                continue;
+            }
+            lines.push(`  ${name}:${artifact.cached ? " (cached)" : ""}`);
+            for (const finding of artifact.verdict.findings) {
+                lines.push(`    ${artifact.verdict.file}:${finding.line} ${finding.severity} [${finding.rule}]: ${finding.message}`);
+            }
+        }
+    }
+    if (result.skippedArchived > 0) {
+        lines.push(`Skipped ${result.skippedArchived} archived artifact(s); use --archive to include them.`);
+    }
+    const fail = errors > 0 || (strict && warnings > 0);
+    lines.push(`${artifacts} artifact(s) checked: ${errors} error(s), ${warnings} warning(s) — ${fail ? "FAIL" : "OK"}${strict ? " (strict)" : ""}`);
+    return lines.join("\n");
+}
+export function computeLintExitCode(result, strict) {
+    const hasErrors = result.packages.some((pkg) => pkg.artifacts.some((a) => a.verdict.findings.some((f) => f.severity === "error")));
+    if (hasErrors)
+        return 1;
+    if (strict) {
+        const hasWarnings = result.packages.some((pkg) => pkg.artifacts.some((a) => a.verdict.findings.some((f) => f.severity === "warning")));
+        if (hasWarnings)
+            return 1;
+    }
+    return 0;
+}
+// END_BLOCK_REPORT
+// defineCommand wrapper: the run body is the RUN_LINT_COMMAND block below
+export default defineCommand({
+    meta: {
+        name: "lint",
+        description: "Lint .vvoc spec-package artifacts (spec.xml, plan.xml, design-context.xml).",
+    },
+    args: {
+        path: {
+            type: "positional",
+            description: `File, package directory, or specs tree to lint (default: ${DEFAULT_LINT_TARGET})`,
+            fallback: DEFAULT_LINT_TARGET,
+        },
+        strict: {
+            type: "boolean",
+            default: false,
+            description: "Fail on warnings, not only errors.",
+        },
+        format: {
+            type: "enum",
+            options: ["text", "json"],
+            default: "text",
+            description: "Output format.",
+        },
+        "no-cache": {
+            type: "boolean",
+            default: false,
+            description: "Bypass the content-addressed lint cache.",
+        },
+        archive: {
+            type: "boolean",
+            default: false,
+            description: "Include archived packages instead of skipping them.",
+        },
+    },
+    async run({ args }) {
+        // START_BLOCK_RUN_LINT_COMMAND
+        const options = {
+            target: typeof args.path === "string" && args.path ? args.path : DEFAULT_LINT_TARGET,
+            includeArchive: args.archive === true,
+            strict: args.strict === true,
+            noCache: args["no-cache"] === true,
+        };
+        const result = await runLint(options);
+        const strict = options.strict;
+        if (args.format === "json") {
+            console.log(JSON.stringify({
+                lintVersion: result.lintVersion,
+                target: result.target,
+                ok: computeLintExitCode(result, strict) === 0,
+                strict,
+                skippedArchived: result.skippedArchived,
+                packages: result.packages.map((pkg) => ({
+                    dir: pkg.dir,
+                    artifacts: pkg.artifacts.map((a) => ({
+                        file: a.verdict.file,
+                        kind: a.verdict.kind,
+                        ok: a.verdict.ok,
+                        cached: a.cached,
+                        findings: a.verdict.findings,
+                    })),
+                })),
+            }, null, 2));
+        }
+        else {
+            console.log(renderLintReport(result, strict));
+        }
+        process.exitCode = computeLintExitCode(result, strict);
+        // END_BLOCK_RUN_LINT_COMMAND
+    },
+});
+//# sourceMappingURL=lint.js.map

package/dist/commands/lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.js","sourceRoot":"","sources":["../../src/commands/lint.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -8,3 +8,4 @@ export { WebToolsPlugin } from "./plugins/web-tools/index.js";
 export { ToolHistoryCompactionPlugin } from "./plugins/tool-history-compaction/index.js";
 export { AnalyticsPlugin } from "./plugins/analytics/index.js";
 export { PeakHoursPlugin } from "./plugins/peak-hours/index.js";
+export { SpecGuardPlugin } from "./plugins/spec-guard/index.js";

package/dist/index.js

@@ -2,19 +2,19 @@
 // VERSION: 1.0.0
 // START_MODULE_CONTRACT
 //   PURPOSE: Re-export the public vv-opencode plugin entrypoints from the package root.
-//   SCOPE: Package-root exports for GuardianPlugin, HashlineEditPlugin, ModelRolesPlugin, SystemContextInjectionPlugin, WorkflowPlugin, SecretsRedactionPlugin, WebToolsPlugin, ToolHistoryCompactionPlugin, AnalyticsPlugin, and PeakHoursPlugin.
-//   DEPENDS: [src/plugins/guardian/index.ts, src/plugins/hashline-edit/index.ts, src/plugins/model-roles/index.ts, src/plugins/system-context-injection/index.ts, src/plugins/workflow/index.ts, src/plugins/secrets-redaction.ts, src/plugins/web-tools/index.ts, src/plugins/tool-history-compaction/index.ts, src/plugins/analytics/index.ts, src/plugins/peak-hours/index.ts]
-//   LINKS: [M-PLUGIN-GUARDIAN, M-PLUGIN-HASHLINE-EDIT, M-PLUGIN-MODEL-ROLES, M-PLUGIN-SYSTEM-CONTEXT-INJECTION, M-PLUGIN-WORKFLOW, M-PLUGIN-SECRETS-REDACTION, M-PLUGIN-WEB-TOOLS, M-PLUGIN-TOOL-HISTORY-COMPACTION, M-PLUGIN-ANALYTICS, M-PLUGIN-PEAK-HOURS]
+//   SCOPE: Package-root exports for GuardianPlugin, HashlineEditPlugin, ModelRolesPlugin, SystemContextInjectionPlugin, WorkflowPlugin, SecretsRedactionPlugin, WebToolsPlugin, ToolHistoryCompactionPlugin, AnalyticsPlugin, PeakHoursPlugin, and SpecGuardPlugin.
+//   DEPENDS: [src/plugins/guardian/index.ts, src/plugins/hashline-edit/index.ts, src/plugins/model-roles/index.ts, src/plugins/system-context-injection/index.ts, src/plugins/workflow/index.ts, src/plugins/secrets-redaction.ts, src/plugins/web-tools/index.ts, src/plugins/tool-history-compaction/index.ts, src/plugins/analytics/index.ts, src/plugins/peak-hours/index.ts, src/plugins/spec-guard/index.ts]
+//   LINKS: [M-PLUGIN-GUARDIAN, M-PLUGIN-HASHLINE-EDIT, M-PLUGIN-MODEL-ROLES, M-PLUGIN-SYSTEM-CONTEXT-INJECTION, M-PLUGIN-WORKFLOW, M-PLUGIN-SECRETS-REDACTION, M-PLUGIN-WEB-TOOLS, M-PLUGIN-TOOL-HISTORY-COMPACTION, M-PLUGIN-ANALYTICS, M-PLUGIN-PEAK-HOURS, M-PLUGIN-SPEC-GUARD]
 //   ROLE: BARREL
 //   MAP_MODE: SUMMARY
 // END_MODULE_CONTRACT
 //
 // START_MODULE_MAP
-//   GuardianPlugin, HashlineEditPlugin, ModelRolesPlugin, SystemContextInjectionPlugin, WorkflowPlugin, SecretsRedactionPlugin, WebToolsPlugin, ToolHistoryCompactionPlugin, AnalyticsPlugin, PeakHoursPlugin - Public plugin exports available from @osovv/vv-opencode.
+//   GuardianPlugin, HashlineEditPlugin, ModelRolesPlugin, SystemContextInjectionPlugin, WorkflowPlugin, SecretsRedactionPlugin, WebToolsPlugin, ToolHistoryCompactionPlugin, AnalyticsPlugin, PeakHoursPlugin, SpecGuardPlugin - Public plugin exports available from @osovv/vv-opencode.
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [C-PLUGIN-PEAK-HOURS - Added PeakHoursPlugin to the package-root exports.]
+//   LAST_CHANGE: [C-SPEC-IDENTITY-LINT - Added SpecGuardPlugin to the package-root exports.]
 // END_CHANGE_SUMMARY
 export { GuardianPlugin } from "./plugins/guardian/index.js";
 export { HashlineEditPlugin } from "./plugins/hashline-edit/index.js";
@@ -26,4 +26,5 @@ export { WebToolsPlugin } from "./plugins/web-tools/index.js";
 export { ToolHistoryCompactionPlugin } from "./plugins/tool-history-compaction/index.js";
 export { AnalyticsPlugin } from "./plugins/analytics/index.js";
 export { PeakHoursPlugin } from "./plugins/peak-hours/index.js";
+export { SpecGuardPlugin } from "./plugins/spec-guard/index.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qBAAqB;AACrB,iBAAiB;AACjB,wBAAwB;AACxB,wFAAwF;AACxF,mPAAmP;AACnP,kXAAkX;AAClX,8PAA8P;AAC9P,iBAAiB;AACjB,sBAAsB;AACtB,sBAAsB;AACtB,EAAE;AACF,mBAAmB;AACnB,yQAAyQ;AACzQ,iBAAiB;AACjB,EAAE;AACF,uBAAuB;AACvB,4FAA4F;AAC5F,qBAAqB;AAErB,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,4BAA4B,EAAE,MAAM,6CAA6C,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,2BAA2B,EAAE,MAAM,4CAA4C,CAAC;AACzF,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qBAAqB;AACrB,iBAAiB;AACjB,wBAAwB;AACxB,wFAAwF;AACxF,oQAAoQ;AACpQ,mZAAmZ;AACnZ,mRAAmR;AACnR,iBAAiB;AACjB,sBAAsB;AACtB,sBAAsB;AACtB,EAAE;AACF,mBAAmB;AACnB,0RAA0R;AAC1R,iBAAiB;AACjB,EAAE;AACF,uBAAuB;AACvB,6FAA6F;AAC7F,qBAAqB;AAErB,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,4BAA4B,EAAE,MAAM,6CAA6C,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,2BAA2B,EAAE,MAAM,4CAA4C,CAAC;AACzF,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/lib/opencode.js

@@ -65,7 +65,7 @@
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [C-PLUGIN-PEAK-HOURS - Materialized the conservative peak-hours plugin entry during install, init, and sync writes.]
+//   LAST_CHANGE: [C-SPEC-IDENTITY-LINT - Materialized the conservative spec-guard plugin entry during install, init, and sync writes.]
 // END_CHANGE_SUMMARY
 import { applyEdits, format, modify, parse } from "jsonc-parser";
 import { lstat, mkdir, readFile, readlink, symlink, unlink, writeFile } from "node:fs/promises";
@@ -77,7 +77,7 @@ import { resolveOrchestrationPolicy } from "./orchestration.js";
 import { createDefaultVvocConfig, createGuardianConfig, parseVvocConfigText, parseVersionedVvocConfigText, renderVvocConfig, } from "./vvoc-config.js";
 import { getPinnedPackageSpecifier, PACKAGE_NAME, PACKAGE_VERSION } from "./package.js";
 import { resolveConfigWriteTargets, resolveOpenCodeConfigSource, resolveOpenCodeTuiConfigSource, resolveVvocConfigSource, } from "./config-layers.js";
-import { materializeHashlineEditEntry, materializeToolHistoryCompactionEntry, materializePeakHoursEntry, } from "./plugin-toggle-config.js";
+import { materializeHashlineEditEntry, materializeToolHistoryCompactionEntry, materializePeakHoursEntry, materializeSpecGuardEntry, } from "./plugin-toggle-config.js";
 import { getConfigHome, getGlobalOpencodeSkillsDir, getGlobalVvocDir, getVvocAgentsDir, getVvocSkillsDir, } from "./vvoc-paths.js";
 export const CLI_NAME = "vvoc";
 export { PACKAGE_NAME };
@@ -616,6 +616,7 @@ export async function syncVvocConfig(paths) {
     nextConfig.plugins["hashline-edit"] = materializeHashlineEditEntry(nextConfig.plugins["hashline-edit"]);
     nextConfig.plugins["tool-history-compaction"] = materializeToolHistoryCompactionEntry(nextConfig.plugins["tool-history-compaction"]);
     nextConfig.plugins["peak-hours"] = materializePeakHoursEntry(nextConfig.plugins["peak-hours"]);
+    nextConfig.plugins["spec-guard"] = materializeSpecGuardEntry(nextConfig.plugins["spec-guard"]);
     return writeResolvedVvocConfig(paths.vvocConfigPath, currentText, nextConfig);
 }
 export async function writeGuardianConfig(paths, overrides, options = {}) {