litopencode 0.0.0

package/docs/migration.md

@@ -0,0 +1,51 @@
+# LitOpenCode Migration Guide
+
+This guide describes the supported migration shape for moving an OpenCode workflow adapter to LitOpenCode. Keep this document brand-clean for public package payloads.
+
+## Package
+
+- Use `litopencode` as the npm package name, OpenCode plugin id, and CLI binary name.
+- Configure OpenCode plugin loading with `litopencode`; do not carry old adapter package names into new runtime config.
+- Treat upstream or sibling repositories as behavior references only. Product code in this package is OpenCode-native TypeScript authored for this repo.
+
+## Environment And Config
+
+- Use the `LITOPENCODE_` prefix for LitOpenCode-owned environment variables.
+- Keep OpenCode plugin configuration in `opencode.json`.
+- Keep LitOpenCode runtime config in `.litopencode/config.json` when project-local config is needed.
+- Use `litopencode doctor --root <workspace>` to inspect package metadata, config source, runtime paths, and ledger location without writing files.
+- Use `litopencode install --dry-run --root <workspace>` to preview the `opencode.json` plugin mutation before applying it manually or through a future write-enabled installer.
+
+## Durable State
+
+LitOpenCode runtime state is intentionally separated from planning and agent evidence:
+
+- project runtime root: `.litopencode/`
+- durable goal root: `.litopencode/litgoal/`
+- durable ledger: `.litopencode/litgoal/lit-loop/ledger.jsonl`
+- user/global root: `~/.litopencode`
+- implementation evidence root: `.litcodex/lit-loop/evidence/`
+
+The durable ledger uses atomic write behavior and recovery for partial temporary files. Existing state from a previous adapter should be copied only after a deliberate review, then represented as LitOpenCode ledger events rather than mixed directly into the new ledger file.
+
+## Vocabulary
+
+Use LitOpenCode vocabulary in docs, config, runtime output, and issue reports:
+
+- product: `LitOpenCode`
+- package, plugin, and binary: `litopencode`
+- activation commands/tools: `lit`, `litwork`
+- durable loop: `lit-loop`
+- durable goal manager: `litgoal`
+- planning/research workflow names: `lit-plan`, `litresearch`, `start-work`, `review-work`, `deep-interview`, `dynamic-workflow`
+
+Legacy vocabulary may appear only in retained provenance files covered by the scanner allowlist and removal conditions. Do not introduce old package names, host claims, or environment prefixes into new product docs, tests, source, or release payloads.
+
+## Migration Checklist
+
+- Replace package/config references with `litopencode`.
+- Move LitOpenCode-owned environment settings to `LITOPENCODE_` names.
+- Keep runtime state under `.litopencode/litgoal` and implementation evidence under `.litcodex`.
+- Keep visible static skills under `skills/*/SKILL.md`; they document workflow loop, durable litgoal, agent roster, doctor installer, release guardrails, litwork activation, and tool guards without dynamic execution.
+- Run `npm run scan:legacy-tokens` after any migration wording change.
+- Run `npm run check:pack-payload` and `npm pack --dry-run --json` before sharing a package artifact.

package/docs/release-checklist.md

@@ -0,0 +1,120 @@
+# LitOpenCode Release Checklist
+
+This checklist is a readiness gate, not an instruction to distribute. The current CI and local workflow are no-publication by default.
+
+## Preflight
+
+- Confirm `package.json` name, binary, and plugin id are `litopencode`.
+- Confirm `package.json` and `package-lock.json` versions are in lockstep.
+- Confirm `README.md`, `docs/migration.md`, `docs/release-checklist.md`, and `HANDOFF.md` describe the current implementation state.
+- Confirm `.litopencode/`, `.litcodex/`, generated evidence, reference archives, fixture-only paths, and package archives are excluded from the packed payload.
+
+## Required Gates
+
+Run these commands from the repository root:
+
+```sh
+npm run build
+npm test
+npm test
+npm run typecheck
+npm run scan:legacy-tokens
+npm run check:version
+npm run check:pack-payload
+npm pack --dry-run --json
+```
+
+Expected results:
+
+- tests pass twice to reduce stale or misleading success output risk
+- build emits `dist/*.js` and `dist/*.d.ts`
+- typecheck exits cleanly
+- scanner exits cleanly with only current allowlisted provenance hits
+- version lockstep exits cleanly
+- payload guard exits cleanly
+- dry pack emits a manifest and leaves no root package archive behind
+
+## Packed Artifact Probe
+
+After the source gates pass, verify the packed artifact in a temporary directory:
+
+```sh
+tmp="$(mktemp -d)"
+npm pack --pack-destination "$tmp"
+tar -xzf "$tmp"/litopencode-0.0.0.tgz -C "$tmp"
+node --input-type=module -e "import('$tmp/package/dist/index.js').then((m) => console.log(m.default?.id ?? m.pluginId))"
+(
+  cd "$tmp/package"
+  npm run scan:legacy-tokens
+  npm run check:version
+  npm run check:pack-payload
+  npm run typecheck
+)
+rm -rf "$tmp"
+```
+
+Expected results:
+
+- plugin import prints `litopencode`
+- package payload includes compiled `dist/*.js` and `dist/*.d.ts` files, not `src/*.ts`
+- `scan:legacy-tokens` runs with an empty allowlist when the source-only allowlist is absent from the packed artifact
+- `check:version` skips lockstep when the source-only lockfile is absent from the packed artifact
+- `typecheck` skips when TypeScript dev dependencies are not installed in the packed artifact
+- `check:pack-payload` still validates the packed manifest
+
+## Installed Package Probe
+
+After the packed artifact probe, verify the public install surface in a clean temporary npm project:
+
+```sh
+tmp="$(mktemp -d)"
+npm pack --pack-destination "$tmp"
+mkdir "$tmp/consumer"
+(
+  cd "$tmp/consumer"
+  npm init -y
+  npm install "$tmp"/litopencode-0.0.0.tgz
+  npm ls litopencode @opencode-ai/plugin --all
+  node --input-type=module -e "import('litopencode').then((m) => console.log(m.default.id))"
+  node_modules/.bin/litopencode --help
+  node_modules/.bin/litopencode doctor --root .
+  node_modules/.bin/litopencode install --dry-run --root .
+)
+rm -rf "$tmp"
+```
+
+Expected results:
+
+- `@opencode-ai/plugin` is installed as a runtime dependency below `litopencode`
+- package import prints `litopencode`
+- CLI help, doctor, and install dry-run exit 0
+- temporary project cleanup removes the probe directory
+
+## OpenCode Host Probe
+
+Use the installed temp-project package, not the source tree, to import `litopencode`, call the default plugin module\'s `server()` function, invoke the config hook, command hook, `lit` and `litwork` tools, and before/after tool guard hooks. Expected results:
+
+- `server()` exposes config, tool, command activation, dispose, and non-enumerable tool guard hooks
+- config registers the LitOpenCode agent roster
+- `/litwork` command activation records a durable redacted ledger event
+- `lit` and `litwork` tools record durable ledger events
+- malformed LitOpenCode tool args are denied fail-closed
+
+## No-Publication Guardrails
+
+- Do not run the npm registry publication command in this workflow.
+- Do not push repository refs from this workflow.
+- Do not create or move repository tags from this workflow.
+- Do not add npm or node auth token values, token variables, or registry credentials to local files, CI, evidence, or docs.
+- Do not add a release job, deploy job, publication secret, write permission, or history rewrite step without explicit user authorization.
+- CI must keep `permissions: contents: read` and must continue to run tests, typecheck, scanner, version lockstep, dry pack, and payload guard.
+
+## Payload Review
+
+Use `npm pack --dry-run --json --ignore-scripts` after `npm run build` as the observable package surface for payload checking. The manifest must include only public package files required for the compiled JavaScript plugin, type declarations, CLI, docs, and guard scripts. It must not include local state, implementation evidence, reference archives, temporary fixtures, dependency folders, source TypeScript, or generated package archives. Source-only guard inputs such as `package-lock.json` and `tools/legacy-token-allowlist.json` stay out of the public payload; their scripts must degrade explicitly and safely when those inputs are absent in the packed artifact.
+
+## Final Verification Reminder
+
+FV-ALL is complete from `.litcodex/plans/litopencode-rebrand-sdd.md`. Final evidence is recorded at `.litcodex/lit-loop/evidence/start-work/FV-ALL-final.txt`.
+
+The completed final wave drove the package through an OpenCode-matching plugin surface and included `npm test`, `npm run typecheck`, `npm run scan:legacy-tokens`, `npm run check:version`, `npm run check:pack-payload`, `npm pack --dry-run --json`, CLI dry-run probes, durable ledger probes, docs tests, and runtime skills coverage.

package/generate_cover.py

@@ -0,0 +1,127 @@
+"""
+Generate the LitOpenCode cover image (2560x1280).
+
+The visual style follows the sibling cover scripts in this workspace: a dark
+gradient field, soft glow, monospace product title, and a compact subtitle.
+"""
+
+from pathlib import Path
+
+import numpy as np
+from PIL import Image, ImageDraw, ImageFilter, ImageFont
+
+
+W, H = 2560, 1280
+CORNER_RADIUS = 80
+ROOT = Path(__file__).resolve().parent
+OUT_PATH = ROOT / "cover.png"
+
+
+def make_blob(size, color_rgba, cx, cy, rx, ry):
+    layer = Image.new("RGBA", size, (0, 0, 0, 0))
+    draw = ImageDraw.Draw(layer)
+    draw.ellipse([cx - rx, cy - ry, cx + rx, cy + ry], fill=color_rgba)
+    return layer
+
+
+def load_font(size, bold=False):
+    try:
+        return ImageFont.truetype("/System/Library/Fonts/Menlo.ttc", size, index=1 if bold else 0)
+    except Exception:
+        fallback = "/System/Library/Fonts/Supplemental/Courier New Bold.ttf"
+        return ImageFont.truetype(fallback, size)
+
+
+def draw_text_layer(text, x, y, font, color):
+    layer = Image.new("RGBA", (W, H), (0, 0, 0, 0))
+    ImageDraw.Draw(layer).text((x, y), text, font=font, fill=color)
+    return layer
+
+
+base = Image.new("RGBA", (W, H), (9, 11, 18, 255))
+
+blobs = [
+    (37, 99, 235, 150, 620, 360, 720, 520, 125),
+    (245, 158, 11, 150, 1880, 400, 620, 460, 105),
+    (20, 184, 166, 120, 1320, 1040, 980, 360, 95),
+    (168, 85, 247, 105, 1420, 650, 560, 380, 85),
+]
+
+canvas = base.copy()
+for r, g, b, a, cx, cy, rx, ry, blur in blobs:
+    blob = make_blob((W, H), (r, g, b, a), cx, cy, rx, ry)
+    blob = blob.filter(ImageFilter.GaussianBlur(radius=blur))
+    canvas = Image.alpha_composite(canvas, blob)
+
+canvas = canvas.filter(ImageFilter.GaussianBlur(radius=8))
+
+rng = np.random.default_rng(42)
+noise = rng.integers(0, 255, (H, W), dtype=np.uint8)
+grain_alpha = (noise * 0.16).astype(np.uint8)
+grain_layer = np.stack([noise, noise, noise, grain_alpha], axis=-1).astype(np.uint8)
+canvas = Image.alpha_composite(canvas, Image.fromarray(grain_layer, "RGBA"))
+
+TITLE_TEXT = "litopencode"
+SUBTITLE_TEXT = "OpenCode plugin for lit-plan, lit-loop, and durable release gates."
+
+tmp = Image.new("RGBA", (W, H), (0, 0, 0, 0))
+d = ImageDraw.Draw(tmp)
+
+font_title = load_font(224, bold=True)
+font_subtitle = load_font(64)
+
+t_bbox = d.textbbox((0, 0), TITLE_TEXT, font=font_title)
+t_w = t_bbox[2] - t_bbox[0]
+t_h = t_bbox[3] - t_bbox[1]
+
+max_subtitle_width = W - 360
+while True:
+    s_bbox = d.textbbox((0, 0), SUBTITLE_TEXT, font=font_subtitle)
+    s_w = s_bbox[2] - s_bbox[0]
+    if s_w <= max_subtitle_width:
+        break
+    current_size = getattr(font_subtitle, "size", 64)
+    if current_size <= 42:
+        break
+    font_subtitle = load_font(current_size - 2)
+
+s_bbox = d.textbbox((0, 0), SUBTITLE_TEXT, font=font_subtitle)
+s_w = s_bbox[2] - s_bbox[0]
+s_h = s_bbox[3] - s_bbox[1]
+
+gap = 52
+total_h = t_h + gap + s_h
+block_top = (H - total_h) // 2 - 20
+
+title_x = (W - t_w) // 2 - t_bbox[0]
+title_y = block_top - t_bbox[1]
+subtitle_x = (W - s_w) // 2 - s_bbox[0]
+subtitle_y = title_y + t_h + gap
+
+for color, blur_r in [
+    ((96, 165, 250, 70), 22),
+    ((20, 184, 166, 90), 11),
+    ((251, 191, 36, 110), 5),
+]:
+    glow = draw_text_layer(TITLE_TEXT, title_x, title_y, font_title, color)
+    glow = glow.filter(ImageFilter.GaussianBlur(radius=blur_r))
+    canvas = Image.alpha_composite(canvas, glow)
+
+canvas = Image.alpha_composite(
+    canvas,
+    draw_text_layer(TITLE_TEXT, title_x, title_y, font_title, (248, 250, 252, 246)),
+)
+canvas = Image.alpha_composite(
+    canvas,
+    draw_text_layer(SUBTITLE_TEXT, subtitle_x, subtitle_y, font_subtitle, (203, 213, 225, 222)),
+)
+
+mask = Image.new("L", (W, H), 0)
+ImageDraw.Draw(mask).rounded_rectangle([(0, 0), (W - 1, H - 1)], radius=CORNER_RADIUS, fill=255)
+canvas.putalpha(mask)
+canvas = canvas.filter(ImageFilter.GaussianBlur(radius=1))
+
+canvas.save(OUT_PATH, "PNG", dpi=(400, 400))
+print(f"Saved: {OUT_PATH}")
+print(f"Size: {canvas.size}")
+print(f"Mode: {canvas.mode}")

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "litopencode",
+  "version": "0.0.0",
+  "description": "LitOpenCode OpenCode plugin bootstrap package.",
+  "type": "module",
+  "bin": {
+    "litopencode": "bin/litopencode"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "node tools/run-build.mjs",
+    "check:pack-payload": "npm run build && npm pack --dry-run --json --ignore-scripts | node tools/check-pack-payload.mjs --stdin",
+    "check:version": "node tools/check-version-lockstep.mjs",
+    "prepack": "npm run build",
+    "scan:legacy-tokens": "node tools/scan-legacy-tokens.mjs",
+    "test": "node --test",
+    "typecheck": "node tools/run-typecheck.mjs"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.17.6"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.2",
+    "typescript": "^5.9.3"
+  }
+}

package/skills/agent-roster/SKILL.md

@@ -0,0 +1,26 @@
+# Agent Roster
+
+Use this LitOpenCode skill when a contributor needs the static agent-roster map for `agent-roster`.
+
+## Covers
+
+- Provide the two primary user-facing agents: `lit-plan` and `lit-loop`.
+- Keep recommended role aliases available as explicit subagent choices.
+- Keep specialist agents available as advanced explicit choices.
+- Merge agent definitions through the OpenCode config hook without overwriting host agents.
+- Keep prompts brand-clean and OpenCode-native.
+
+## OpenCode Surfaces
+
+- Config hook: LitOpenCode agent merge
+- Primary default agents: `lit-plan`, `lit-loop`
+- Recommended role aliases: `lit-architect`, `lit-forge`, `lit-oracle`, `lit-prover`, `lit-sentinel`, `lit-librarian`
+- Specialist agents: explorer, archive researcher, verdict oracle, strategy planner, forge worker, systems architect, critical reviewer, context cartographer, persistence runner
+- Runtime feature id: `agent-roster`
+- Runtime feature id: `planning-start-work-loop`
+
+## Safety
+
+- This file is static documentation.
+- Do not execute commands from this file automatically.
+- Preserve existing host agent entries during registration.

package/skills/doctor-installer/SKILL.md

@@ -0,0 +1,22 @@
+# Doctor Installer
+
+Use this LitOpenCode skill when a contributor needs the static CLI health and installer map for `doctor-install`.
+
+## Covers
+
+- Inspect package metadata, config source, runtime paths, and state presence.
+- Preview OpenCode plugin configuration changes without writing files.
+- Keep malformed config handling fail-closed.
+- Keep installer output bounded and avoid leaking existing user config content.
+
+## OpenCode Surfaces
+
+- CLI: `litopencode doctor`
+- CLI: `litopencode install --dry-run`
+- Runtime feature id: `doctor-install`
+
+## Safety
+
+- This file is static documentation.
+- Do not execute commands from this file automatically.
+- Treat dry-run output as a summary of intended mutation, not as a full config dump.

package/skills/durable-litgoal/SKILL.md

@@ -0,0 +1,22 @@
+# Durable LitGoal
+
+Use this LitOpenCode skill when a contributor needs the static durable-goal map for `durable-ledger`.
+
+## Covers
+
+- Store resumable goal and loop state under `.litopencode/litgoal`.
+- Append durable JSONL events for command, tool, and goal activity.
+- Recover temporary ledger files before status reads.
+- Fail closed when durable ledger lines are malformed.
+
+## OpenCode Surfaces
+
+- Tool: `litwork` with `status`
+- Runtime state: `.litopencode/litgoal/lit-loop/ledger.jsonl`
+- Runtime feature id: `durable-ledger`
+
+## Safety
+
+- This file is static documentation.
+- Do not execute commands from this file automatically.
+- Keep ledger events JSON-serializable and redact command arguments before persistence.

package/skills/litwork-activation/SKILL.md

@@ -0,0 +1,25 @@
+# Litwork Activation
+
+Use this LitOpenCode skill when a contributor needs the static activation-surface map for `lit-litwork-activation`.
+
+## Covers
+
+- Expose `/lit` and `/litwork` as command activation points.
+- Expose `lit` and `litwork` as OpenCode tools.
+- Record activation as durable ledger metadata without persisting raw command arguments.
+- Keep activation text observable through command hooks.
+
+## OpenCode Surfaces
+
+- Command: `/lit`
+- Command: `/litwork`
+- Tool: `lit`
+- Tool: `litwork`
+- Hook: `command.execute.before`
+- Runtime feature id: `lit-litwork-activation`
+
+## Safety
+
+- This file is static documentation.
+- Do not execute commands from this file automatically.
+- Persist redacted argument metadata only.

package/skills/release-guardrails/SKILL.md

@@ -0,0 +1,23 @@
+# Release Guardrails
+
+Use this LitOpenCode skill when a contributor needs the static release-readiness map for `guardrails`.
+
+## Covers
+
+- Run scanner, version lockstep, payload guard, dry pack, typecheck, and tests before release-oriented work.
+- Keep CI no-publication by default.
+- Keep package payloads free of local state, evidence, reference archives, fixtures, dependency folders, and package archives.
+- Keep guarded vocabulary exceptions exact, reviewed, and removal-conditioned.
+
+## OpenCode Surfaces
+
+- npm script: `scan:legacy-tokens`
+- npm script: `check:version`
+- npm script: `check:pack-payload`
+- Runtime feature id: `guardrails`
+
+## Safety
+
+- This file is static documentation.
+- Do not execute commands from this file automatically.
+- Do not publish, push refs, create tags, or add auth tokens without explicit authorization.

package/skills/tool-guards/SKILL.md

@@ -0,0 +1,22 @@
+# Tool Guards
+
+Use this LitOpenCode skill when a contributor needs the static tool-guard map for OpenCode hook behavior.
+
+## Covers
+
+- Inspect tool execution before and after supported tool calls.
+- Allow unrelated tool calls to pass through unchanged.
+- Deny unsafe guarded tool requests fail-closed.
+- Add structured metadata after supported tool calls complete.
+
+## OpenCode Surfaces
+
+- Hook: `tool.execute.before`
+- Hook: `tool.execute.after`
+- Runtime feature area: tool guards
+
+## Safety
+
+- This file is static documentation.
+- Do not execute commands from this file automatically.
+- Keep guard decisions explicit and auditable.

package/skills/workflow-loop/SKILL.md

@@ -0,0 +1,24 @@
+# Workflow Loop
+
+Use this LitOpenCode skill when a contributor needs the static workflow-loop map for `planning-start-work-loop`.
+
+## Covers
+
+- Start with a concrete plan before implementation work begins.
+- Keep implementation slices scoped to the active task.
+- Record observable progress through evidence and durable ledger entries.
+- Pair worker changes with independent verification before completion claims.
+
+## OpenCode Surfaces
+
+- Command: `/litwork`
+- Primary agents: `lit-plan`, `lit-loop`
+- Recommended role aliases: `lit-architect`, `lit-forge`, `lit-oracle`, `lit-prover`, `lit-sentinel`, `lit-librarian`
+- Runtime feature id: `planning-start-work-loop`
+- Runtime feature id: `lit-litwork-activation`
+
+## Safety
+
+- This file is static documentation.
+- Do not execute commands from this file automatically.
+- Keep project progress in durable state rather than chat-only notes.

package/tools/check-pack-payload.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+const FORBIDDEN_PATH_RULES = [
+  { label: "original prompt provenance", pattern: /^INITIAL_PROMPT\.md$/u },
+  { label: "handoff state document", pattern: /^HANDOFF\.md$/u },
+  { label: "repository automation", pattern: /(^|\/)\.github(\/|$)/u },
+  { label: "internal recon/spec document", pattern: /^docs\/(?:recon|spec)(\/|$)/u },
+  { label: "implementation plan", pattern: /(^|\/)plans(\/|$)/u },
+  { label: ".litcodex runtime state", pattern: /(^|\/)\.litcodex(\/|$)/u },
+  { label: ".litopencode runtime state", pattern: /(^|\/)\.litopencode(\/|$)/u },
+  { label: "evidence artifact", pattern: /(^|\/)evidence(\/|$)/u },
+  { label: "test file", pattern: /(^|\/)tests?(\/|$)/u },
+  { label: "reference archive", pattern: /(^|\/)# REFERENCE(\/|$)/u },
+  { label: "package archive", pattern: /\.tgz$/u },
+  { label: "dependency directory", pattern: /(^|\/)node_modules(\/|$)/u },
+  { label: "git directory", pattern: /(^|\/)\.git(\/|$)/u },
+  { label: "local scanner allowlist", pattern: /^tools\/legacy-token-allowlist\.json$/u }
+];
+
+class PackPayloadError extends Error {
+  constructor(message, exitCode) {
+    super(message);
+    this.name = "PackPayloadError";
+    this.exitCode = exitCode;
+  }
+}
+
+function parseArgs(argv) {
+  const options = {
+    mode: "stdin",
+    filePath: undefined
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const next = argv[index + 1];
+    if (arg === "--stdin") {
+      options.mode = "stdin";
+    } else if (arg === "--file" && next !== undefined) {
+      options.mode = "file";
+      options.filePath = next;
+      index += 1;
+    } else {
+      throw new PackPayloadError(`unknown or incomplete argument: ${arg}`, 2);
+    }
+  }
+
+  return options;
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function readManifestText(options) {
+  if (options.mode === "file") {
+    return fs.readFile(path.resolve(options.filePath), "utf8");
+  }
+  return readStdin();
+}
+
+function parseManifest(text) {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new PackPayloadError(`cannot read or parse manifest: ${detail}`, 2);
+  }
+}
+
+function requireObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new PackPayloadError(`${label} must be a JSON object`, 2);
+  }
+  return value;
+}
+
+function normalizeManifestPath(value) {
+  return value.split(path.sep).join("/");
+}
+
+function readManifestFiles(parsed) {
+  if (!Array.isArray(parsed) || parsed.length !== 1) {
+    throw new PackPayloadError("manifest must be the one-package array emitted by npm pack --dry-run --json", 2);
+  }
+
+  const packageEntry = requireObject(parsed[0], "manifest package");
+  const files = packageEntry.files;
+  if (!Array.isArray(files)) {
+    throw new PackPayloadError("manifest package files must be an array", 2);
+  }
+
+  return files.map((entry, index) => {
+    const fileEntry = requireObject(entry, `manifest package files[${index}]`);
+    if (typeof fileEntry.path !== "string" || fileEntry.path.trim() === "") {
+      throw new PackPayloadError(`manifest package files[${index}].path must be a non-empty string`, 2);
+    }
+    return normalizeManifestPath(fileEntry.path);
+  });
+}
+
+function findForbiddenPaths(paths) {
+  const matches = [];
+  for (const manifestPath of paths) {
+    const rule = FORBIDDEN_PATH_RULES.find((candidate) => candidate.pattern.test(manifestPath));
+    if (rule !== undefined) {
+      matches.push({ path: manifestPath, reason: rule.label });
+    }
+  }
+  return matches;
+}
+
+function printForbiddenPaths(matches) {
+  for (const match of matches) {
+    console.log(`${match.path} :: ${match.reason}`);
+  }
+}
+
+async function main() {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    const manifestText = await readManifestText(options);
+    const manifest = parseManifest(manifestText);
+    const files = readManifestFiles(manifest);
+    const forbidden = findForbiddenPaths(files);
+
+    if (forbidden.length > 0) {
+      const suffix = forbidden.length === 1 ? "path" : "paths";
+      console.log(`pack payload guard failed: ${forbidden.length} forbidden ${suffix}`);
+      printForbiddenPaths(forbidden);
+      process.exitCode = 1;
+      return;
+    }
+
+    const suffix = files.length === 1 ? "file" : "files";
+    console.log(`pack payload guard passed: ${files.length} ${suffix} checked`);
+  } catch (error) {
+    if (error instanceof PackPayloadError) {
+      console.error(`pack payload guard error: ${error.message}`);
+      process.exitCode = error.exitCode;
+      return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`pack payload guard error: ${message}`);
+    process.exitCode = 2;
+  }
+}
+
+await main();