opencode-orchestrator-uni 0.3.0 → 0.4.0

package/lib/report-schema.ts

@@ -352,6 +352,42 @@ export function reportWarnings(schemaId: string, value: unknown): string[] {
     }
   }
 
+  if (schemaId === "context-lint/v1") {
+    const files = list("files").filter(isPlainObject)
+    const findings = files.flatMap((file) => (Array.isArray(file.findings) ? file.findings.filter(isPlainObject) : []))
+    const majorIds = findings
+      .filter((finding) => finding.severity === "MAJOR")
+      .map((finding) => finding.id)
+      .filter((id): id is string => typeof id === "string")
+    const closing = strings("closing_list")
+    // The verdict is a function of the findings, and `closing_list` is the set of
+    // MAJOR ids: a report that claims `pass` over its own MAJOR finding, or that
+    // lists something else, is a report whose closing_list cannot be trusted.
+    if (value.verdict === "pass" && majorIds.length > 0) {
+      warnings.push("verdict=pass with a MAJOR finding: verdict must be fail")
+    }
+    // Set equality, not just containment: a repeated id hides a missing one.
+    const uniqueClosing = new Set(closing)
+    if (
+      uniqueClosing.size !== closing.length ||
+      closing.length !== majorIds.length ||
+      closing.some((id) => !majorIds.includes(id))
+    ) {
+      warnings.push(`closing_list must equal the MAJOR finding ids (${majorIds.join(", ") || "none"})`)
+    }
+    if (value.verdict === "pass" && files.length === 0) {
+      warnings.push("verdict=pass with files=[]: no file was measured")
+    }
+    if (value.truncated === true) {
+      warnings.push(
+        "truncated=true: the finding list is capped; MAJOR findings are prioritized and a dropped MAJOR leaves a MAJOR marker, MINOR/INFO may be missing",
+      )
+      if (value.verdict === "pass") {
+        warnings.push("truncated=true with verdict=pass: the capped list may hide a later finding; re-run after fixes")
+      }
+    }
+  }
+
   return warnings
 }
 

package/lib/tools.ts

@@ -1,12 +1,16 @@
 /**
  * tools — registration of the kit's deterministic, read-only audit tools.
  *
- * `registerAuditTools(ctx)` publishes three tools in the `orch_uni` namespace
- * (effective names `orch_uni_validate_report`, `orch_uni_snapshot`, `orch_uni_sessions`)
- * and returns a cleanup that stops the background session-index subscription:
+ * `registerAuditTools(ctx)` publishes four tools in the `orch_uni` namespace
+ * (effective names `orch_uni_validate_report`, `orch_uni_context_lint`,
+ * `orch_uni_snapshot`, `orch_uni_sessions`) and returns a cleanup that stops the
+ * background session-index subscription:
  *
  * - `validate_report` — extract the SGR JSON block of an agent report, resolve
  *   its schema, validate it and report prompt-level warnings;
+ * - `context_lint` — deterministic, read-only checks for AGENTS.md/SPEC.md/CLAUDE.md:
+ *   budget, vague phrases, duplicates, broken relative links, placeholders,
+ *   dates in the first lines, required sections;
  * - `snapshot` — deterministic revision of a directory tree (per-file sha256 +
  *   aggregate hash) for "the state the verdict was fixed on";
  * - `sessions` — child sessions of a session (agent, model, cost, tokens, time),
@@ -14,7 +18,7 @@
  *
  * Every tool answers with a JSON text body. Failures are typed (`E_*`) codes in
  * the body rather than thrown tool errors, so an agent can branch on the code.
- * All three are read-only: they never write to the workspace or the config; the
+ * All four are read-only: they never write to the workspace or the config; the
  * only state `sessions` keeps is a plugin-scoped session index in `ctx.storage`
  * (see the `sessions` tool notes below).
  */
@@ -22,6 +26,7 @@ import { readdir, readFile } from "node:fs/promises"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
 import type { Plugin } from "@opencode/plugin"
+import { lintContext } from "./context-lint"
 import { checkReport, type JsonSchemaNode, type ValidationCode } from "./report-schema"
 import { DEFAULT_EXCLUDE, isSnapshotFailure, snapshotTree } from "./snapshot"
 
@@ -29,7 +34,12 @@ import { DEFAULT_EXCLUDE, isSnapshotFailure, snapshotTree } from "./snapshot"
 export const TOOL_NAMESPACE = "orch_uni"
 
 /** Effective tool names as they appear to a model. */
-export const TOOL_IDS: readonly string[] = ["orch_uni_validate_report", "orch_uni_snapshot", "orch_uni_sessions"]
+export const TOOL_IDS: readonly string[] = [
+  "orch_uni_validate_report",
+  "orch_uni_context_lint",
+  "orch_uni_snapshot",
+  "orch_uni_sessions",
+]
 
 /** Directory holding the shipped report schemas (`schemas/*.json`). */
 export const SCHEMAS_DIRECTORY = fileURLToPath(new URL("../schemas/", import.meta.url))
@@ -144,6 +154,36 @@ const VALIDATE_REPORT_INPUT = {
   },
 } as const
 
+/** `context_lint` input contract. */
+const CONTEXT_LINT_INPUT = {
+  type: "object",
+  properties: {
+    path: {
+      type: "string",
+      description:
+        "File or directory to inspect, absolute or relative to the location directory. Default: the location directory.",
+    },
+    max_lines: { type: "number", description: "AGENTS/CLAUDE line budget. Default: 200." },
+    max_tokens: { type: "number", description: "AGENTS/CLAUDE estimated token budget. Default: 2500." },
+    max_words: {
+      type: "number",
+      description: "SPEC word budget. Default: 1500 (the authoring target); the documented ceiling is 2000.",
+    },
+    max_file_bytes: { type: "number", description: "Largest file that may be read, in bytes. Default: 2000000." },
+    max_files: { type: "number", description: "Most files a directory target may expand to. Default: 500." },
+    max_findings: {
+      type: "number",
+      description:
+        "Per-file cap: MINOR/INFO findings kept, and the hard cap for MAJOR (excess becomes one MAJOR truncated finding). Default: 100.",
+    },
+    max_total_findings: {
+      type: "number",
+      description:
+        "Global cap for all findings; MAJOR are kept first, the MAJOR overflow becomes one MAJOR truncated marker in closing_list. Default: 1000.",
+    },
+  },
+} as const
+
 /** `snapshot` input contract. */
 const SNAPSHOT_INPUT = {
   type: "object",
@@ -437,6 +477,75 @@ export async function registerAuditTools(
     return json({ root: outcome.root, files: outcome.files, aggregate: outcome.aggregate })
   }
 
+  const contextLintTool = async (
+    input: unknown,
+    toolContext: { readonly signal?: AbortSignal } | undefined,
+  ): Promise<{ content: string }> => {
+    // A failure is not a report: it carries the `context-lint-failure/v1` id so it
+    // validates against that schema and never passes as a `context-lint/v1` report.
+    const lintFailure = (code: string, message: string, extra: Record<string, unknown> = {}) =>
+      failure(code, message, { schema: "context-lint-failure/v1", ...extra })
+    const record = input === undefined ? {} : asRecord(input)
+    if (record === undefined)
+      return lintFailure(
+        "E_INPUT",
+        "input must be an object ({path?, max_lines?, max_tokens?, max_words?, max_file_bytes?, max_files?, max_findings?, max_total_findings?})",
+      )
+    const {
+      path: target,
+      max_lines,
+      max_tokens,
+      max_words,
+      max_file_bytes,
+      max_files,
+      max_findings,
+      max_total_findings,
+    } = record
+    if (target !== undefined && (typeof target !== "string" || target === "")) {
+      return lintFailure("E_INPUT", '"path" must be a non-empty string')
+    }
+    for (const [key, value] of [
+      ["max_lines", max_lines],
+      ["max_tokens", max_tokens],
+      ["max_words", max_words],
+      ["max_file_bytes", max_file_bytes],
+      ["max_files", max_files],
+      ["max_findings", max_findings],
+      ["max_total_findings", max_total_findings],
+    ] as const) {
+      if (value !== undefined && (typeof value !== "number" || !Number.isFinite(value) || value <= 0)) {
+        return lintFailure("E_INPUT", `"${key}" must be a positive number`)
+      }
+    }
+    // The host may call an executor without a context (`execute(input, {})`), and
+    // some builds pass no signal at all: fall back to a local controller instead
+    // of throwing on `undefined.signal`.
+    const controller = new AbortController()
+    const signal = toolContext?.signal ?? controller.signal
+    if (signal.aborted) return lintFailure("E_ABORTED", "context lint aborted")
+    const outcome = await lintContext({
+      root: directory,
+      ...(target === undefined ? {} : { target: target as string }),
+      ...(max_lines === undefined ? {} : { maxLines: max_lines as number }),
+      ...(max_tokens === undefined ? {} : { maxTokens: max_tokens as number }),
+      ...(max_words === undefined ? {} : { maxWords: max_words as number }),
+      ...(max_file_bytes === undefined ? {} : { maxFileBytes: max_file_bytes as number }),
+      ...(max_files === undefined ? {} : { maxFiles: max_files as number }),
+      ...(max_findings === undefined ? {} : { maxFindingsPerFile: max_findings as number }),
+      ...(max_total_findings === undefined ? {} : { maxTotalFindings: max_total_findings as number }),
+      signal,
+    })
+    if (!outcome.ok) {
+      const extra: Record<string, unknown> = {}
+      if (outcome.path !== undefined) extra.path = outcome.path
+      if (outcome.bytes !== undefined) extra.bytes = outcome.bytes
+      if (outcome.files !== undefined) extra.files = outcome.files
+      if (outcome.max !== undefined) extra.max = outcome.max
+      return lintFailure(outcome.code, outcome.message, extra)
+    }
+    return json(outcome)
+  }
+
   const sessionsTool = async (
     input: unknown,
     toolContext: { readonly signal: AbortSignal; readonly sessionID: string },
@@ -548,7 +657,27 @@ export async function registerAuditTools(
     editor.namespace({
       name: TOOL_NAMESPACE,
       description:
-        "Deterministic, read-only tools of the orchestrator agent kit (SGR validation, state snapshots, session accounting).",
+        "Deterministic, read-only tools of the orchestrator agent kit (SGR validation, context-file lint, state snapshots, session accounting).",
+    })
+    editor.add({
+      name: "context_lint",
+      description:
+        "Deterministic, read-only audit of AGENTS.md/SPEC.md/CLAUDE.md: line/token/word budget, distinct vague phrases, duplicate lines, " +
+        "broken relative links, placeholders, dates in the first three lines, required sections, AC test columns. " +
+        "A directory target is scanned to depth 3 and capped at max_files (the walk stops at the first file above the limit); " +
+        "a scan started at the root also picks up fixture trees such as eval/ (pass an explicit path for the canonical files); " +
+        "undocumented directories below depth 3, unclosed fences and links that resolve outside the workspace root are reported " +
+        "as INFO findings and never checked silently. Commands count only inside code, a Task table or a Commands section; " +
+        "tokens are estimated as Cyrillic/3 + the rest/4. " +
+        "Returns JSON {schema, ok, verdict, closing_list, files, summary, truncated?}; each file carries lines, words, chars " +
+        "and tokens_est. A per-file cap drops findings and sets truncated=true, max_total_findings keeps MAJOR first and turns " +
+        "the MAJOR overflow into one MAJOR truncated finding in closing_list. A file target is capped by max_file_bytes, " +
+        'also while it is read. A failure is JSON {schema:"context-lint-failure/v1", ok:false, code, message, path?, bytes?, ' +
+        "files?, max?} with a typed code " +
+        "(E_INPUT|E_NOT_FOUND|E_NO_FILES|E_IO|E_ABORTED|E_LIMIT_FILE|E_LIMIT_FILES|E_OUT_OF_ROOT).",
+      input: CONTEXT_LINT_INPUT,
+      options: { namespace: TOOL_NAMESPACE, codemode: true },
+      execute: contextLintTool,
     })
     editor.add({
       name: "validate_report",

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-orchestrator-uni",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Native OpenCode V2 plugin that registers the orchestrator agent kit (root orchestrator, audit subagents, fix-runner) and exposes the kit's process documents as the audit-kit reference.",
   "type": "module",
   "license": "MIT",

package/schemas/context-lint-failure.v1.json

@@ -0,0 +1,29 @@
+{
+  "id": "context-lint-failure/v1",
+  "schema": {
+    "type": "object",
+    "required": ["schema", "ok", "code", "message"],
+    "properties": {
+      "schema": { "type": "string", "const": "context-lint-failure/v1" },
+      "ok": { "type": "boolean", "const": false },
+      "code": {
+        "type": "string",
+        "enum": [
+          "E_INPUT",
+          "E_NOT_FOUND",
+          "E_NO_FILES",
+          "E_IO",
+          "E_ABORTED",
+          "E_LIMIT_FILE",
+          "E_LIMIT_FILES",
+          "E_OUT_OF_ROOT"
+        ]
+      },
+      "message": { "type": "string" },
+      "path": { "type": "string" },
+      "bytes": { "type": "number" },
+      "files": { "type": "number" },
+      "max": { "type": "number" }
+    }
+  }
+}

package/schemas/context-lint.v1.json

@@ -0,0 +1,58 @@
+{
+  "id": "context-lint/v1",
+  "schema": {
+    "type": "object",
+    "required": ["schema", "verdict", "closing_list", "files", "summary"],
+    "properties": {
+      "schema": { "type": "string", "const": "context-lint/v1" },
+      "ok": { "type": "boolean" },
+      "verdict": { "type": "string", "enum": ["pass", "fail"] },
+      "closing_list": { "type": "array", "items": { "type": "string" } },
+      "truncated": { "type": "boolean" },
+      "files": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "required": ["path", "kind", "lines", "words", "tokens_est", "findings"],
+          "properties": {
+            "path": { "type": "string" },
+            "kind": { "type": "string", "enum": ["agents", "spec", "claude", "other"] },
+            "lines": { "type": "number" },
+            "words": { "type": "number" },
+            "chars": { "type": "number" },
+            "tokens_est": { "type": "number" },
+            "truncated": { "type": "boolean" },
+            "findings": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["id", "severity", "kind", "evidence", "detail", "fix"],
+                "properties": {
+                  "id": { "type": "string" },
+                  "severity": { "type": "string", "enum": ["MAJOR", "MINOR", "INFO"] },
+                  "kind": {
+                    "type": "string",
+                    "enum": [
+                      "budget",
+                      "vague",
+                      "duplicate",
+                      "broken_link",
+                      "missing_section",
+                      "conflict",
+                      "unverified_command",
+                      "other"
+                    ]
+                  },
+                  "evidence": { "type": "string" },
+                  "detail": { "type": "string" },
+                  "fix": { "type": "string" }
+                }
+              }
+            }
+          }
+        }
+      },
+      "summary": { "type": "string" }
+    }
+  }
+}