project-tiny-context-harness 0.2.84 → 0.6.0

package/dist/lib/context-manifest-schema.js

@@ -0,0 +1,150 @@
+import { parse } from "smol-toml";
+const TOP_LEVEL_FIELDS = new Set(["areas", "context"]);
+const AREA_FIELDS = new Set([
+    "id",
+    "root",
+    "context",
+    "kind",
+    "default",
+    "forbidden_runtime_dependencies",
+]);
+const CONTEXT_FIELDS = new Set([
+    "path",
+    "role",
+    "read_when",
+    "read_policy",
+    "triggers",
+    "default_children",
+]);
+export function parseContextManifest(content, file = "project_context/context.toml") {
+    const errors = [];
+    let parsed;
+    try {
+        parsed = parse(content);
+    }
+    catch (error) {
+        return {
+            errors: [
+                `${file} is not valid TOML: ${error instanceof Error ? error.message : String(error)}`,
+            ],
+        };
+    }
+    rejectUnknownFields(parsed, TOP_LEVEL_FIELDS, file, errors);
+    const rawAreas = tableArray(parsed.areas, "[[areas]]", file, errors);
+    const rawContexts = tableArray(parsed.context, "[[context]]", file, errors);
+    const areaLines = tableLines(content, "areas");
+    const contextLines = tableLines(content, "context");
+    const areas = [];
+    for (const [index, value] of rawAreas.entries()) {
+        const location = `${file} line ${areaLines[index] ?? 1}`;
+        rejectUnknownFields(value, AREA_FIELDS, location, errors);
+        const id = requiredString(value, "id", location, errors);
+        const root = requiredString(value, "root", location, errors);
+        const context = requiredString(value, "context", location, errors);
+        const kind = optionalString(value, "kind", location, errors);
+        const defaultArea = optionalBoolean(value, "default", location, errors) ?? false;
+        const forbiddenRuntimeDependencies = optionalStringArray(value, "forbidden_runtime_dependencies", location, errors);
+        if (id && root && context) {
+            areas.push({
+                line: areaLines[index] ?? 1,
+                id,
+                root,
+                context,
+                kind,
+                default: defaultArea,
+                forbidden_runtime_dependencies: forbiddenRuntimeDependencies,
+            });
+        }
+    }
+    const contexts = [];
+    for (const [index, value] of rawContexts.entries()) {
+        const location = `${file} line ${contextLines[index] ?? 1}`;
+        rejectUnknownFields(value, CONTEXT_FIELDS, location, errors);
+        const path = requiredString(value, "path", location, errors);
+        const role = requiredString(value, "role", location, errors);
+        const readWhen = optionalString(value, "read_when", location, errors);
+        const readPolicy = optionalString(value, "read_policy", location, errors);
+        const triggers = optionalStringArray(value, "triggers", location, errors);
+        const defaultChildren = optionalStringArray(value, "default_children", location, errors);
+        if (path && role) {
+            contexts.push({
+                line: contextLines[index] ?? 1,
+                path,
+                role,
+                read_when: readWhen,
+                read_policy: readPolicy,
+                triggers,
+                default_children: defaultChildren,
+            });
+        }
+    }
+    return { manifest: { areas, contexts }, errors };
+}
+function tableArray(value, label, file, errors) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value) || value.some((entry) => !isRecord(entry))) {
+        errors.push(`${file} field ${label} must be an array of TOML tables`);
+        return [];
+    }
+    return value;
+}
+function rejectUnknownFields(value, allowed, location, errors) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) {
+            errors.push(`${location} has unknown field ${key}`);
+        }
+    }
+}
+function requiredString(value, key, location, errors) {
+    const candidate = value[key];
+    if (typeof candidate === "string" && candidate.trim()) {
+        return candidate;
+    }
+    errors.push(`${location} must include non-empty string field ${key}`);
+    return undefined;
+}
+function optionalString(value, key, location, errors) {
+    const candidate = value[key];
+    if (candidate === undefined) {
+        return undefined;
+    }
+    if (typeof candidate === "string" && candidate.trim()) {
+        return candidate;
+    }
+    errors.push(`${location} field ${key} must be a non-empty string`);
+    return undefined;
+}
+function optionalBoolean(value, key, location, errors) {
+    const candidate = value[key];
+    if (candidate === undefined || typeof candidate === "boolean") {
+        return candidate;
+    }
+    errors.push(`${location} field ${key} must be a boolean`);
+    return undefined;
+}
+function optionalStringArray(value, key, location, errors) {
+    const candidate = value[key];
+    if (candidate === undefined) {
+        return [];
+    }
+    if (Array.isArray(candidate) &&
+        candidate.every((entry) => typeof entry === "string" && entry.trim())) {
+        return candidate;
+    }
+    errors.push(`${location} field ${key} must be an array of non-empty strings`);
+    return [];
+}
+function tableLines(content, table) {
+    const lines = [];
+    for (const [index, line] of content.split(/\r?\n/).entries()) {
+        if (line.trim() === `[[${table}]]`) {
+            lines.push(index + 1);
+        }
+    }
+    return lines;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/lib/context-manifest.js

@@ -12,25 +12,25 @@ export function defaultContextManifestTemplate() {
         "# every Markdown file as an [[areas]] product owner.",
         "",
         "[[areas]]",
-        "id = \"main\"",
-        "root = \".\"",
-        "context = \"project_context/areas/main.md\"",
-        "kind = \"app\"",
+        'id = "main"',
+        'root = "."',
+        'context = "project_context/areas/main.md"',
+        'kind = "app"',
         "default = true",
         "",
         "[[context]]",
-        "path = \"project_context/areas/main/verification.md\"",
-        "role = \"verification\"",
-        "read_policy = \"default\"",
-        "triggers = [\"test\", \"verify\", \"verification\", \"smoke\", \"ci\"]",
+        'path = "project_context/areas/main/verification.md"',
+        'role = "verification"',
+        'read_policy = "default"',
+        'triggers = ["test", "verify", "verification", "smoke", "ci"]',
         "",
         "# Example optional node:",
         "# [[context]]",
-        "# path = \"project_context/areas/main/deployment.md\"",
-        "# role = \"deployment\"",
-        "# read_policy = \"on-demand\"",
-        "# triggers = [\"deploy\", \"deployment\", \"runtime\", \"cloud\", \"docker\"]",
-        ""
+        '# path = "project_context/areas/main/deployment.md"',
+        '# role = "deployment"',
+        '# read_policy = "on-demand"',
+        '# triggers = ["deploy", "deployment", "runtime", "cloud", "docker"]',
+        "",
     ].join("\n");
 }
 export async function contextManifestFromExistingAreas(projectRoot) {
@@ -47,12 +47,15 @@ export async function contextManifestFromExistingAreas(projectRoot) {
         "# Review deep or non-area context and move it to explicit [[context]] role entries",
         "# such as subdomain, contract, foundation, verification, deployment, archive,",
         "# implementation-index or decision-rationale when needed.",
-        ""
+        "",
     ];
     const areaEntries = [];
     const contextEntries = [];
     for (const areaPath of areas) {
-        const relativeToAreas = path.relative(areasRoot, areaPath).split(path.sep).join("/");
+        const relativeToAreas = path
+            .relative(areasRoot, areaPath)
+            .split(path.sep)
+            .join("/");
         const contextPath = `project_context/areas/${relativeToAreas}`;
         const id = contextUnitId(relativeToAreas);
         const role = inferredRoleContext(relativeToAreas);
@@ -62,25 +65,30 @@ export async function contextManifestFromExistingAreas(projectRoot) {
                 role,
                 triggers: role === "verification"
                     ? ["test", "verify", "verification", "smoke", "ci"]
-                    : ["deploy", "deployment", "runtime", "cloud", "docker"]
+                    : ["deploy", "deployment", "runtime", "cloud", "docker"],
             });
         }
         else {
             areaEntries.push({ contextPath, id });
         }
     }
-    const defaultId = areaEntries.some((entry) => entry.id === "main") ? "main" : areaEntries[0]?.id;
+    const defaultId = areaEntries.some((entry) => entry.id === "main")
+        ? "main"
+        : areaEntries[0]?.id;
     for (const { contextPath, id } of areaEntries) {
-        lines.push("[[areas]]", `id = "${id}"`, "root = \".\"", `context = "${contextPath}"`, `kind = "${id === "main" ? "app" : "context-unit"}"`, id === defaultId ? "default = true" : "default = false", "");
+        lines.push("[[areas]]", `id = "${id}"`, 'root = "."', `context = "${contextPath}"`, `kind = "${id === "main" ? "app" : "context-unit"}"`, id === defaultId ? "default = true" : "default = false", "");
     }
     for (const context of contextEntries) {
-        lines.push("[[context]]", `path = "${context.path}"`, `role = "${context.role}"`, context.role === "verification" ? "read_policy = \"default\"" : "read_policy = \"on-demand\"", `triggers = [${context.triggers.map((trigger) => `"${trigger}"`).join(", ")}]`, "");
+        lines.push("[[context]]", `path = "${context.path}"`, `role = "${context.role}"`, context.role === "verification"
+            ? 'read_policy = "default"'
+            : 'read_policy = "on-demand"', `triggers = [${context.triggers.map((trigger) => `"${trigger}"`).join(", ")}]`, "");
     }
     return lines.join("\n");
 }
 function inferredRoleContext(relativeToAreas) {
     const normalized = relativeToAreas.toLowerCase();
-    if (normalized.endsWith("/verification.md") || normalized === "verification.md") {
+    if (normalized.endsWith("/verification.md") ||
+        normalized === "verification.md") {
         return "verification";
     }
     if (normalized.endsWith("/deployment.md") || normalized === "deployment.md") {

package/dist/lib/context-templates.js

@@ -52,7 +52,7 @@ export function globalContextTemplate() {
         "",
         "- [main](areas/main.md)",
         "- [main verification](areas/main/verification.md)",
-        ""
+        "",
     ].join("\n");
 }
 export function architectureContextTemplate() {
@@ -88,7 +88,7 @@ export function architectureContextTemplate() {
         "## Open Risks",
         "",
         "- List unresolved architectural risks or unknowns.",
-        ""
+        "",
     ].join("\n");
 }
 export function areaContextTemplate(areaName) {
@@ -130,7 +130,7 @@ export function areaContextTemplate(areaName) {
         "## Open Risks",
         "",
         "- List unresolved risks or blockers.",
-        ""
+        "",
     ].join("\n");
 }
 export function verificationContextTemplate(areaName) {
@@ -167,7 +167,7 @@ export function verificationContextTemplate(areaName) {
         "## Forbidden Content",
         "",
         "- Do not record one-off logs, full command output, temporary JSON, CI artifacts, test reports, secrets, tokens, cookies, device ids, raw payloads or pass/fail claims.",
-        ""
+        "",
     ].join("\n");
 }
 export function deploymentContextTemplate(areaName) {
@@ -207,6 +207,6 @@ export function deploymentContextTemplate(areaName) {
         "## Forbidden Content",
         "",
         "- Do not record one-off logs, full command output, CI artifacts, release ledgers, secrets, tokens, cookies, device ids, raw payloads or claims that deployment already succeeded.",
-        ""
+        "",
     ].join("\n");
 }

package/dist/lib/design-md.js

@@ -127,6 +127,6 @@ function designMdTemplate() {
         "- When there is a scan target such as UI source, page files, build output or a local/remote URL, run `npx impeccable detect <target>` before finalizing design changes.",
         "- Treat Impeccable findings as design-review signals: fix issues that affect clarity, consistency, accessibility or trust, and note when there is no suitable scan target.",
         "- After design decisions stabilize, update this file with durable tokens, component rules and do/don't guidance so later UI work stays aligned.",
-        ""
+        "",
     ].join("\n");
 }

package/dist/lib/doctor.js

@@ -1,5 +1,8 @@
 import { createRequire } from "node:module";
 import path from "node:path";
+import os from "node:os";
+import { readdir } from "node:fs/promises";
+import { DEFAULT_CONTEXT_FILE_SOFT_BUDGET_BYTES, DEFAULT_CONTEXT_TOTAL_SOFT_BUDGET_BYTES, inspectDefaultContextFootprint, } from "./context-default-footprint.js";
 import { readConfig } from "./config.js";
 import { harnessConfigPath, harnessRoot } from "./harness-root.js";
 import { pathExists } from "./fs.js";
@@ -25,7 +28,12 @@ export async function runDoctor(projectRoot) {
         report.errors.push(unsupportedSchema);
         return report;
     }
-    for (const required of ["project_context/context.toml", "project_context/global.md", "project_context/architecture.md", "project_context/areas"]) {
+    for (const required of [
+        "project_context/context.toml",
+        "project_context/global.md",
+        "project_context/architecture.md",
+        "project_context/areas",
+    ]) {
         if (!(await pathExists(path.join(projectRoot, required)))) {
             report.errors.push(`missing ${required}`);
         }
@@ -36,6 +44,51 @@ export async function runDoctor(projectRoot) {
             report.warnings.push(`managed path missing: ${managed.path}`);
         }
     }
+    try {
+        const footprint = await inspectDefaultContextFootprint(projectRoot);
+        report.info.push(`default Context read path: ${footprint.files.length} file(s), ${footprint.total_bytes} bytes`);
+        if (footprint.total_bytes > DEFAULT_CONTEXT_TOTAL_SOFT_BUDGET_BYTES) {
+            report.warnings.push(`default Context read path is ${footprint.total_bytes} bytes, above the ${DEFAULT_CONTEXT_TOTAL_SOFT_BUDGET_BYTES}-byte soft budget; shorten near-universal facts or move specialized role Context to read_policy=\"on-demand\"`);
+        }
+        for (const file of footprint.files) {
+            if (file.bytes <= DEFAULT_CONTEXT_FILE_SOFT_BUDGET_BYTES)
+                continue;
+            report.warnings.push(`default Context file ${file.path} is ${file.bytes} bytes, above the ${DEFAULT_CONTEXT_FILE_SOFT_BUDGET_BYTES}-byte per-file soft budget`);
+        }
+        for (const group of footprint.duplicate_groups) {
+            report.warnings.push(`default Context contains byte-identical files: ${group.join(", ")}; keep one owning fact source and replace duplicates with a short pointer`);
+        }
+    }
+    catch (error) {
+        report.warnings.push(`default Context footprint unavailable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    for (const location of await findUserSuperpowersSkills()) {
+        report.warnings.push(`user-level using-superpowers Skill detected at ${location}. Tiny Context workflows do not depend on it and doctor will not modify global configuration. To disable it explicitly for Codex, remove/disable that plugin or add a matching [[skills.config]] entry with enabled = false in ${path.join(os.homedir(), ".codex", "config.toml")}.`);
+    }
     report.info.push("doctor complete");
     return report;
 }
+async function findUserSuperpowersSkills() {
+    const home = os.homedir();
+    const direct = path.join(home, ".codex", "skills", "using-superpowers", "SKILL.md");
+    const result = [];
+    if (await pathExists(direct))
+        result.push(direct);
+    const cache = path.join(home, ".codex", "plugins", "cache");
+    try {
+        for (const owner of await readdir(cache)) {
+            const candidateRoot = path.join(cache, owner);
+            for (const plugin of await readdir(candidateRoot)) {
+                if (plugin !== "superpowers")
+                    continue;
+                for (const version of await readdir(path.join(candidateRoot, plugin))) {
+                    const candidate = path.join(candidateRoot, plugin, version, "skills", "using-superpowers", "SKILL.md");
+                    if (await pathExists(candidate))
+                        result.push(candidate);
+                }
+            }
+        }
+    }
+    catch { }
+    return [...new Set(result)].sort();
+}

package/dist/lib/harness-root.js

@@ -6,30 +6,45 @@ export async function readHarnessRootConfig(projectRoot) {
     const candidates = await readHarnessRootConfigCandidates(projectRoot);
     if (candidates.length > 0) {
         const candidate = candidates[0];
-        return { harnessFolderName: candidate.harnessFolderName, source: candidate.source };
+        return {
+            harnessFolderName: candidate.harnessFolderName,
+            source: candidate.source,
+        };
     }
     return { harnessFolderName: DEFAULT_HARNESS_ROOT, source: "default" };
 }
 export async function readHarnessRootConfigCandidates(projectRoot) {
     const candidates = [];
     const packageJson = await readJsonConfig(path.join(projectRoot, "package.json"));
-    const packageConfig = packageJson && typeof packageJson === "object" ? packageJson.tyContext : undefined;
+    const packageConfig = packageJson && typeof packageJson === "object"
+        ? packageJson.tyContext
+        : undefined;
     const packageValue = folderNameFromObject(packageConfig);
     if (packageValue) {
-        candidates.push({ harnessFolderName: normalizeHarnessFolderName(packageValue), source: "package.json#tyContext", legacy: false });
+        candidates.push({
+            harnessFolderName: normalizeHarnessFolderName(packageValue),
+            source: "package.json#tyContext",
+            legacy: false,
+        });
     }
     const explicitConfig = await readJsonConfig(path.join(projectRoot, HARNESS_JSON_CONFIG_PATH));
     const explicitValue = folderNameFromObject(explicitConfig);
     if (explicitValue) {
-        candidates.push({ harnessFolderName: normalizeHarnessFolderName(explicitValue), source: HARNESS_JSON_CONFIG_PATH, legacy: false });
+        candidates.push({
+            harnessFolderName: normalizeHarnessFolderName(explicitValue),
+            source: HARNESS_JSON_CONFIG_PATH,
+            legacy: false,
+        });
     }
-    const legacyPackageConfig = packageJson && typeof packageJson === "object" ? packageJson.sdlcHarness : undefined;
+    const legacyPackageConfig = packageJson && typeof packageJson === "object"
+        ? packageJson.sdlcHarness
+        : undefined;
     const legacyPackageValue = folderNameFromObject(legacyPackageConfig);
     if (legacyPackageValue) {
         candidates.push({
             harnessFolderName: normalizeHarnessFolderName(legacyPackageValue),
             source: "package.json#sdlcHarness",
-            legacy: true
+            legacy: true,
         });
     }
     const legacyExplicitConfig = await readJsonConfig(path.join(projectRoot, LEGACY_HARNESS_JSON_CONFIG_PATH));
@@ -38,7 +53,7 @@ export async function readHarnessRootConfigCandidates(projectRoot) {
         candidates.push({
             harnessFolderName: normalizeHarnessFolderName(legacyExplicitValue),
             source: LEGACY_HARNESS_JSON_CONFIG_PATH,
-            legacy: true
+            legacy: true,
         });
     }
     return candidates;
@@ -58,7 +73,9 @@ function folderNameFromObject(value) {
     }
     const record = value;
     const folderName = record.harnessFolderName ?? record.harnessFloderName;
-    return typeof folderName === "string" && folderName.trim() ? folderName : undefined;
+    return typeof folderName === "string" && folderName.trim()
+        ? folderName
+        : undefined;
 }
 async function readJsonConfig(filePath) {
     if (!(await pathExists(filePath))) {

package/dist/lib/init.js

@@ -1,6 +1,6 @@
 import path from "node:path";
-import { CONTEXT_MANIFEST_PATH, defaultContextManifestTemplate } from "./context-manifest.js";
-import { architectureContextTemplate, areaContextTemplate, globalContextTemplate, verificationContextTemplate } from "./context-templates.js";
+import { CONTEXT_MANIFEST_PATH, defaultContextManifestTemplate, } from "./context-manifest.js";
+import { architectureContextTemplate, areaContextTemplate, globalContextTemplate, verificationContextTemplate, } from "./context-templates.js";
 import { writeConfigIfMissing } from "./config.js";
 import { createDesignMdIfMissing, DESIGN_MD_PATH } from "./design-md.js";
 import { harnessConfigPath } from "./harness-root.js";
@@ -50,7 +50,10 @@ async function createProjectContext(projectRoot, report) {
         ["project_context/global.md", globalContextTemplate()],
         ["project_context/architecture.md", architectureContextTemplate()],
         ["project_context/areas/main.md", areaContextTemplate("main")],
-        ["project_context/areas/main/verification.md", verificationContextTemplate("main")]
+        [
+            "project_context/areas/main/verification.md",
+            verificationContextTemplate("main"),
+        ],
     ];
     for (const [relative, content] of files) {
         const target = path.join(projectRoot, relative);

package/dist/lib/legacy-managed-scan.js

@@ -13,8 +13,14 @@ export async function detectLegacyManagedDirectory(projectRoot, root, migration)
         if (path.basename(file) === ".gitkeep") {
             continue;
         }
-        const relativeToLegacyRoot = path.relative(legacyRoot, file).split(path.sep).join("/");
-        const relativeToProject = path.relative(projectRoot, file).split(path.sep).join("/");
+        const relativeToLegacyRoot = path
+            .relative(legacyRoot, file)
+            .split(path.sep)
+            .join("/");
+        const relativeToProject = path
+            .relative(projectRoot, file)
+            .split(path.sep)
+            .join("/");
         const classification = await classifyLegacyManagedFile(relativeToLegacyRoot);
         if (classification.kind === "override") {
             items.push(item(migration, "manual_required", relativeToProject, "Legacy skill overrides are no longer supported; move rules into a standalone project-local Skill."));
@@ -47,21 +53,31 @@ async function classifyLegacyManagedFile(relative) {
     if (!(await pathExists(assetPath))) {
         return { kind: "unknown" };
     }
-    return { kind: "generated", targetRelative: mapped.targetRelative, assetPath };
+    return {
+        kind: "generated",
+        targetRelative: mapped.targetRelative,
+        assetPath,
+    };
 }
 function legacyGeneratedMapping(relative) {
     if (relative === `make/${LEGACY_MAKEFILE}`) {
-        return { targetRelative: `make/${CURRENT_MAKEFILE}`, assetSegments: ["make", CURRENT_MAKEFILE] };
+        return {
+            targetRelative: `make/${CURRENT_MAKEFILE}`,
+            assetSegments: ["make", CURRENT_MAKEFILE],
+        };
     }
     for (const [prefix, assetPrefix] of [
         ["agents/", "agents"],
         ["context_templates/", "context_templates"],
         ["skills/", "skills"],
-        ["minimal_tools/", "tools"]
+        ["minimal_tools/", "tools"],
     ]) {
         if (relative.startsWith(prefix)) {
             const rest = relative.slice(prefix.length);
-            return { targetRelative: `${prefix}${rest}`, assetSegments: [assetPrefix, ...rest.split("/")] };
+            return {
+                targetRelative: `${prefix}${rest}`,
+                assetSegments: [assetPrefix, ...rest.split("/")],
+            };
         }
     }
     return undefined;
@@ -74,6 +90,6 @@ function item(migration, status, pathLabel, message) {
         scope: migration.scope,
         status,
         path: pathLabel,
-        message
+        message,
     };
 }

package/dist/lib/legacy-sdlc-migration.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { LEGACY_HARNESS_JSON_CONFIG_PATH, readHarnessRootConfigCandidates } from "./harness-root.js";
+import { LEGACY_HARNESS_JSON_CONFIG_PATH, readHarnessRootConfigCandidates, } from "./harness-root.js";
 import { pathExists, readText, writeTextIfChanged } from "./fs.js";
 import { detectLegacyManagedDirectory } from "./legacy-managed-scan.js";
 import { HARNESS_JSON_CONFIG_PATH } from "./paths.js";
@@ -16,7 +16,7 @@ export const legacySdlcHarnessMigration = {
     manualMessage: "Resolve legacy sdlc-harness conflicts or move old override rules into standalone project-local Skills.",
     detect: detectLegacySdlcHarness,
     apply: migrateLegacySdlcHarness,
-    verify: async () => undefined
+    verify: async () => undefined,
 };
 async function detectLegacySdlcHarness(projectRoot, root, migration) {
     const items = [];
@@ -25,7 +25,8 @@ async function detectLegacySdlcHarness(projectRoot, root, migration) {
     const legacyCandidates = candidates.filter((candidate) => candidate.legacy);
     const currentRoot = currentCandidates[0]?.harnessFolderName;
     const distinctLegacyRoots = Array.from(new Set(legacyCandidates.map((candidate) => candidate.harnessFolderName)));
-    if (currentRoot && distinctLegacyRoots.some((legacyRoot) => legacyRoot !== currentRoot)) {
+    if (currentRoot &&
+        distinctLegacyRoots.some((legacyRoot) => legacyRoot !== currentRoot)) {
         items.push(item(migration, "blocked", rootConflictPath(currentCandidates, legacyCandidates), "Current ty-context and legacy sdlc-harness root configuration disagree; choose the harness root manually before upgrade."));
     }
     else if (!currentRoot && distinctLegacyRoots.length > 1) {
@@ -46,7 +47,8 @@ async function migrateLegacySdlcHarness(projectRoot, root, report) {
     await migrateConfigYamlPaths(projectRoot, root, report);
 }
 async function needsLegacySafeMigration(projectRoot, root, hasLegacyRootConfig) {
-    if (hasLegacyRootConfig && (await legacyPackageConfigNeedsCopy(projectRoot))) {
+    if (hasLegacyRootConfig &&
+        (await legacyPackageConfigNeedsCopy(projectRoot))) {
         return true;
     }
     if (await legacyJsonConfigNeedsCopy(projectRoot)) {
@@ -66,7 +68,8 @@ async function legacyPackageConfigNeedsCopy(projectRoot) {
         return false;
     }
     const packageJson = parseJsonRecord(await readText(packagePath), "package.json");
-    return isJsonRecord(packageJson.sdlcHarness) && !isJsonRecord(packageJson.tyContext);
+    return (isJsonRecord(packageJson.sdlcHarness) &&
+        !isJsonRecord(packageJson.tyContext));
 }
 async function legacyJsonConfigNeedsCopy(projectRoot) {
     const legacyPath = path.join(projectRoot, LEGACY_HARNESS_JSON_CONFIG_PATH);
@@ -81,7 +84,11 @@ async function configYamlHasLegacyManagedPaths(projectRoot, root) {
     return hasLegacyManagedPath(await readText(configPath));
 }
 async function hasLegacyManagedMarkers(projectRoot) {
-    for (const relative of ["AGENTS.md", "Makefile", ".github/workflows/harness.yml"]) {
+    for (const relative of [
+        "AGENTS.md",
+        "Makefile",
+        ".github/workflows/harness.yml",
+    ]) {
         const target = path.join(projectRoot, ...relative.split("/"));
         if ((await pathExists(target)) && hasLegacyMarker(await readText(target))) {
             return true;
@@ -96,7 +103,8 @@ async function migratePackageJsonConfig(projectRoot, report) {
         return;
     }
     const packageJson = parseJsonRecord(await readText(packagePath), "package.json");
-    if (!isJsonRecord(packageJson.sdlcHarness) || isJsonRecord(packageJson.tyContext)) {
+    if (!isJsonRecord(packageJson.sdlcHarness) ||
+        isJsonRecord(packageJson.tyContext)) {
         report.skipped.push("package.json#sdlcHarness");
         return;
     }
@@ -147,10 +155,12 @@ async function migrateConfigYamlPaths(projectRoot, root, report) {
     }
 }
 function rewriteLegacyManagedPaths(content) {
-    return content.replaceAll(LEGACY_MANAGED_ROOT, CURRENT_MANAGED_ROOT).replaceAll(LEGACY_MAKEFILE, CURRENT_MAKEFILE);
+    return content
+        .replaceAll(LEGACY_MANAGED_ROOT, CURRENT_MANAGED_ROOT)
+        .replaceAll(LEGACY_MAKEFILE, CURRENT_MAKEFILE);
 }
 function hasLegacyManagedPath(content) {
-    return content.includes(LEGACY_MANAGED_ROOT) || content.includes(LEGACY_MAKEFILE);
+    return (content.includes(LEGACY_MANAGED_ROOT) || content.includes(LEGACY_MAKEFILE));
 }
 function hasLegacyMarker(content) {
     return [
@@ -158,7 +168,7 @@ function hasLegacyMarker(content) {
         "<!-- sdlc-harness:begin -->",
         "# pjsdlc:sdlc-harness:make:begin",
         "# sdlc-harness:make:begin",
-        "# pjsdlc:sdlc-harness:github-workflow:begin"
+        "# pjsdlc:sdlc-harness:github-workflow:begin",
     ].some((marker) => content.includes(marker));
 }
 function rootConflictPath(currentCandidates, legacyCandidates) {
@@ -174,7 +184,7 @@ function item(migrationId, status, pathLabel, message) {
         scope: legacySdlcHarnessMigration.scope,
         status,
         path: pathLabel,
-        message
+        message,
     };
 }
 function parseJsonRecord(content, pathLabel) {

package/dist/lib/long-task-acceptance-reference.d.ts

@@ -0,0 +1,22 @@
+import type { CompiledDeliveryContractV2, DeliveryAssertionV2, DeliveryCheckV2, DeliveryContractV2 } from "./long-task-delivery-types.js";
+export type AcceptanceReference = {
+    scope: "global";
+    check_key: string;
+    assertion_key: string;
+} | {
+    scope: "outcome";
+    outcome_key: string;
+    check_key: string;
+    assertion_key: string;
+};
+export interface ResolvedAcceptanceAssertion {
+    ref: string;
+    scope: AcceptanceReference["scope"];
+    outcome_key: string | null;
+    check_key: string;
+    assertion_key: string;
+    check: DeliveryCheckV2;
+    assertion: DeliveryAssertionV2;
+}
+export declare function parseAcceptanceReference(ref: string): AcceptanceReference;
+export declare function resolveAcceptanceAssertion(contract: DeliveryContractV2 | CompiledDeliveryContractV2, ref: string): ResolvedAcceptanceAssertion | null;