@mikenguyen69/harness 0.1.0-beta.1

package/dist/internal/system/spec/index.js

@@ -0,0 +1,212 @@
+/**
+ * spec — the `spec` gate. Lints specs/*.yaml against schema/spec.schema.json
+ * (every acceptance criterion names a verifier or is explicitly
+ * manual-with-reason) and then cross-checks the set: unique ids, an acyclic
+ * dep DAG, and every `consumes` artifact produced by an upstream unit.
+ *
+ * This mechanizes the FORM of specs (principle 2, one layer up). Whether the
+ * criteria capture the right intent stays human judgment upstream; the
+ * defect→spec calibration loop is what ratchets that over time.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import addFormatsDefault from "ajv-formats";
+import { parse as parseYaml } from "yaml";
+import { packageSchemaDir } from "../assets.js";
+const addFormats = addFormatsDefault;
+function schemaPath() {
+    return join(packageSchemaDir(), "spec.schema.json");
+}
+let _validate;
+function specValidator() {
+    if (!_validate) {
+        const ajv = new Ajv2020({ allErrors: true, strict: false });
+        addFormats(ajv);
+        _validate = ajv.compile(JSON.parse(readFileSync(schemaPath(), "utf8")));
+    }
+    return _validate;
+}
+export function loadSpecs(specsDir) {
+    const files = readdirSync(specsDir).filter((n) => n.endsWith(".yaml") || n.endsWith(".yml"));
+    return files.map((f) => ({
+        path: join(specsDir, f),
+        spec: parseYaml(readFileSync(join(specsDir, f), "utf8")),
+    }));
+}
+/**
+ * The canonical unit identifier is the globally unique bare spec id. Component
+ * identity is a separate field; a `component#id` dependency is accepted only
+ * as an explicit cross-component reference and normalizes to this value.
+ */
+export function canonicalUnitId(ref) {
+    return ref.includes("#") ? ref.slice(ref.indexOf("#") + 1) : ref;
+}
+/** Full check: schema + uniqueness + acyclic DAG + consumes⊆upstream-produces + system.toml cross-refs. */
+export function checkSpecs(specsDir, opts = {}) {
+    const findings = [];
+    let loaded;
+    try {
+        loaded = loadSpecs(specsDir);
+    }
+    catch (e) {
+        return [
+            {
+                specPath: specsDir,
+                level: "error",
+                message: `cannot read specs: ${e.message}`,
+            },
+        ];
+    }
+    const validate = specValidator();
+    for (const { path, spec } of loaded) {
+        if (!validate(spec)) {
+            for (const err of validate.errors ?? []) {
+                findings.push({
+                    specPath: path,
+                    level: "error",
+                    message: `${err.instancePath || "/"} ${err.message ?? "invalid"}`,
+                });
+            }
+        }
+        if (typeof spec?.id === "string" && spec.id.includes("#")) {
+            findings.push({
+                specPath: path,
+                level: "error",
+                message: `spec id "${spec.id}" must be the bare canonical unit id; put component identity in "component"`,
+            });
+        }
+        if (opts.systemComponents &&
+            spec?.component &&
+            !opts.systemComponents.includes(spec.component)) {
+            findings.push({
+                specPath: path,
+                level: "error",
+                message: `component "${spec.component}" is not declared in system.toml`,
+            });
+        }
+        for (const out of spec?.outputs ?? []) {
+            const producer = opts.artifactProducers?.[out];
+            if (opts.artifactProducers && producer === undefined) {
+                findings.push({
+                    specPath: path,
+                    level: "error",
+                    message: `output artifact "${out}" is not declared in system.toml`,
+                });
+            }
+            else if (producer !== undefined && producer !== spec.component) {
+                findings.push({
+                    specPath: path,
+                    level: "error",
+                    message: `output "${out}" is produced by "${producer}" in system.toml, not "${spec.component}"`,
+                });
+            }
+        }
+    }
+    // uniqueness
+    const byId = new Map();
+    for (const ls of loaded) {
+        const id = canonicalUnitId(ls.spec?.id ?? "");
+        if (id === "")
+            continue;
+        if (byId.has(id)) {
+            findings.push({
+                specPath: ls.path,
+                level: "error",
+                message: `duplicate unit id "${id}" (also in ${byId.get(id).path})`,
+            });
+        }
+        else {
+            byId.set(id, ls);
+        }
+    }
+    // dep graph: unknown refs + cycles
+    const deps = new Map();
+    for (const ls of loaded) {
+        const id = canonicalUnitId(ls.spec?.id ?? "");
+        const ds = (ls.spec?.deps ?? []).map(canonicalUnitId);
+        deps.set(id, ds);
+        for (const [index, d] of ds.entries()) {
+            if (!byId.has(d)) {
+                findings.push({
+                    specPath: ls.path,
+                    level: "error",
+                    message: `dep "${d}" refers to no known spec`,
+                });
+            }
+            else {
+                const raw = ls.spec.deps?.[index];
+                const separator = raw?.indexOf("#") ?? -1;
+                if (raw && separator >= 0) {
+                    const declaredComponent = raw.slice(0, separator);
+                    const actualComponent = byId.get(d)?.spec.component;
+                    if (actualComponent && declaredComponent !== actualComponent) {
+                        findings.push({
+                            specPath: ls.path,
+                            level: "error",
+                            message: `dep "${raw}" names component "${declaredComponent}" but unit "${d}" belongs to "${actualComponent}"`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    const WHITE = 0, GREY = 1, BLACK = 2;
+    const color = new Map();
+    const cycleFrom = (n) => {
+        color.set(n, GREY);
+        for (const d of deps.get(n) ?? []) {
+            if (!byId.has(d))
+                continue;
+            const c = color.get(d) ?? WHITE;
+            if (c === GREY)
+                return true;
+            if (c === WHITE && cycleFrom(d))
+                return true;
+        }
+        color.set(n, BLACK);
+        return false;
+    };
+    for (const id of byId.keys()) {
+        if ((color.get(id) ?? WHITE) === WHITE && cycleFrom(id)) {
+            findings.push({
+                specPath: byId.get(id).path,
+                level: "error",
+                message: `dependency cycle through "${id}"`,
+            });
+        }
+    }
+    // consumes ⊆ artifacts produced by a transitive upstream unit
+    const upstream = (id, seen = new Set()) => {
+        for (const d of deps.get(id) ?? []) {
+            if (seen.has(d))
+                continue;
+            seen.add(d);
+            upstream(d, seen);
+        }
+        return seen;
+    };
+    for (const ls of loaded) {
+        const id = canonicalUnitId(ls.spec?.id ?? "");
+        const up = upstream(id);
+        const producedUpstream = new Set();
+        for (const u of up)
+            for (const o of byId.get(u)?.spec.outputs ?? [])
+                producedUpstream.add(o);
+        for (const c of ls.spec?.consumes ?? []) {
+            if (!producedUpstream.has(c)) {
+                findings.push({
+                    specPath: ls.path,
+                    level: "error",
+                    message: `consumes "${c}" but no upstream unit in its dep chain produces it`,
+                });
+            }
+        }
+    }
+    return findings;
+}
+/** @deprecated criterion-level subset kept for the gate runner's original contract */
+export function lintSpecs(specsDir) {
+    return checkSpecs(specsDir).filter((f) => f.specPath.endsWith(".yaml") || f.specPath.endsWith(".yml"));
+}
+//# sourceMappingURL=index.js.map

package/dist/internal/system/spec/materialize.js

@@ -0,0 +1,111 @@
+/**
+ * Accepted spec DAG -> durable `unit.planned` facts.
+ *
+ * Materialization is deliberately two phase: validate the whole input and
+ * detect every conflict before the first append. Re-running identical input is
+ * a no-op; changing an already-materialized unit fails closed.
+ */
+import { relative } from "node:path";
+import { append, canonicalJSON, read as ledgerRead, } from "../ledger/index.js";
+import { loadSystem } from "../system/index.js";
+import { canonicalUnitId, checkSpecs, loadSpecs, } from "./index.js";
+function checkOptions(opts) {
+    const manifest = loadSystem(opts.systemToml);
+    return {
+        systemComponents: manifest.component.map((component) => component.id),
+        artifactProducers: Object.fromEntries(manifest.artifact.map((artifact) => [artifact.name, artifact.producer])),
+    };
+}
+/** Complete, deterministic ledger body for one accepted spec. */
+export function plannedBody(spec, specPath, specsDir) {
+    return {
+        unit_id: canonicalUnitId(spec.id),
+        component: spec.component,
+        mode: spec.mode ?? "build",
+        deps: (spec.deps ?? []).map(canonicalUnitId),
+        intent: spec.intent,
+        acceptance_criteria: spec.acceptance_criteria,
+        scope: spec.scope,
+        ...(spec.size_budget ? { size_budget: spec.size_budget } : {}),
+        ...(spec.door ? { door: spec.door } : {}),
+        merge_facts: {
+            adds_dependency: spec.merge_facts?.adds_dependency ?? false,
+            schema_change: spec.merge_facts?.schema_change ?? false,
+            security: spec.merge_facts?.security ?? false,
+            gate_external: spec.merge_facts?.gate_external ?? false,
+            artifact_producer_change: spec.merge_facts?.artifact_producer_change ?? false,
+        },
+        outputs: spec.outputs ?? [],
+        consumes: spec.consumes ?? [],
+        spec_path: relative(specsDir, specPath).replaceAll("\\", "/"),
+    };
+}
+export function materializeSpecs(opts) {
+    let validationOptions;
+    try {
+        validationOptions = checkOptions(opts);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            units: [],
+            findings: [{
+                    specPath: opts.systemToml,
+                    level: "error",
+                    message: `cannot read system manifest: ${error.message}`,
+                }],
+            conflicts: [],
+        };
+    }
+    const findings = checkSpecs(opts.specsDir, validationOptions);
+    if (findings.some((finding) => finding.level === "error")) {
+        return { ok: false, units: [], findings, conflicts: [] };
+    }
+    const manifest = loadSystem(opts.systemToml);
+    const candidates = loadSpecs(opts.specsDir)
+        .map((loaded) => ({
+        id: canonicalUnitId(loaded.spec.id),
+        body: plannedBody(loaded.spec, loaded.path, opts.specsDir),
+    }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+    const existing = new Map();
+    for (const event of ledgerRead(opts.ledgerDir)) {
+        if (event.type !== "unit.planned")
+            continue;
+        const id = event.body.unit_id;
+        if (typeof id === "string")
+            existing.set(canonicalUnitId(id), event.body);
+    }
+    const conflicts = candidates
+        .filter(({ id, body }) => {
+        const current = existing.get(id);
+        return current !== undefined && canonicalJSON(current) !== canonicalJSON(body);
+    })
+        .map(({ id }) => ({
+        id,
+        message: `unit "${id}" is already materialized with a different contract`,
+    }));
+    if (conflicts.length > 0)
+        return { ok: false, units: [], findings, conflicts };
+    const units = [];
+    for (const candidate of candidates) {
+        if (existing.has(candidate.id)) {
+            units.push({ id: candidate.id, status: "already_materialized" });
+            continue;
+        }
+        const event = append(opts.ledgerDir, {
+            system: manifest.system.id,
+            actor: { kind: "harness", id: "spec-materializer" },
+            type: "unit.planned",
+            body: candidate.body,
+        });
+        units.push({
+            id: candidate.id,
+            status: "materialized",
+            seq: event.seq,
+            hash: event.hash,
+        });
+    }
+    return { ok: true, units, findings, conflicts: [] };
+}
+//# sourceMappingURL=materialize.js.map

package/dist/internal/system/spec/openspec-parse.js

@@ -0,0 +1,83 @@
+/**
+ * Minimal OpenSpec capability-spec parser for harness spec projection.
+ *
+ * Parses `### Requirement:` blocks and optional `#### Scenario:` sub-blocks
+ * from markdown spec files under openspec/specs/ and change deltas.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+const REQUIREMENT = /^### Requirement:\s*(.+)$/m;
+const SCENARIO = /^#### Scenario:\s*(.+)$/m;
+/** Split markdown into requirement blocks after the first `### Requirement:` header. */
+export function parseCapabilityMarkdown(content) {
+    const start = content.search(/^### Requirement:/m);
+    if (start < 0)
+        return [];
+    const tail = content.slice(start);
+    const chunks = tail.split(/\n(?=### Requirement:)/);
+    const requirements = [];
+    for (const chunk of chunks) {
+        const header = chunk.match(REQUIREMENT);
+        if (!header)
+            continue;
+        const name = header[1].trim();
+        const afterHeader = chunk.slice(header.index + header[0].length).trim();
+        const scenarioParts = afterHeader.split(/\n(?=#### Scenario:)/);
+        const bodyPart = scenarioParts[0].trim();
+        const scenarios = [];
+        for (let i = 1; i < scenarioParts.length; i++) {
+            const part = scenarioParts[i];
+            const scenarioHeader = part.match(SCENARIO);
+            if (!scenarioHeader)
+                continue;
+            scenarios.push({
+                name: scenarioHeader[1].trim(),
+                body: part.slice(scenarioHeader.index + scenarioHeader[0].length).trim(),
+            });
+        }
+        requirements.push({ name, body: bodyPart, scenarios });
+    }
+    return requirements;
+}
+function normalizeName(name) {
+    return name.trim().toLowerCase();
+}
+/** Merge ADDED requirement blocks from a change delta into a requirement map. */
+export function mergeAddedRequirements(base, delta) {
+    const byName = new Map(base.map((r) => [normalizeName(r.name), r]));
+    const addedSection = delta.match(/## ADDED Requirements\s*\n([\s\S]*?)(?:\n## (?:MODIFIED|REMOVED|RENAMED) Requirements|\s*$)/);
+    if (!addedSection)
+        return base;
+    for (const req of parseCapabilityMarkdown(addedSection[1])) {
+        byName.set(normalizeName(req.name), req);
+    }
+    return [...byName.values()];
+}
+export function loadCapabilityRequirements(openspecRoot, capability, changeDir) {
+    const segments = capability.split("/");
+    const mainPath = join(openspecRoot, "specs", ...segments, "spec.md");
+    let requirements = [];
+    if (existsSync(mainPath)) {
+        requirements = parseCapabilityMarkdown(readFileSync(mainPath, "utf8"));
+    }
+    if (changeDir) {
+        const deltaPath = join(changeDir, "specs", ...segments, "spec.md");
+        if (existsSync(deltaPath)) {
+            requirements = mergeAddedRequirements(requirements, readFileSync(deltaPath, "utf8"));
+        }
+    }
+    return new Map(requirements.map((r) => [normalizeName(r.name), r]));
+}
+export function resolveRequirementStatement(req, scenarioName) {
+    if (!scenarioName)
+        return req.body.trim();
+    const scenario = req.scenarios.find((s) => normalizeName(s.name) === normalizeName(scenarioName));
+    if (!scenario) {
+        throw new Error(`scenario "${scenarioName}" not found on requirement "${req.name}"`);
+    }
+    const scenarioText = scenario.body.trim();
+    if (!req.body.trim())
+        return scenarioText;
+    return `${req.body.trim()}\n${scenarioText}`;
+}
+//# sourceMappingURL=openspec-parse.js.map

package/dist/internal/system/spec/project.js

@@ -0,0 +1,208 @@
+/**
+ * OpenSpec → harness unit projector.
+ *
+ * Reads a change's harness.projection.yaml sidecar, resolves acceptance
+ * criteria from OpenSpec capability specs, and emits harness unit YAML files.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { checkSpecs, } from "./index.js";
+import { loadCapabilityRequirements, resolveRequirementStatement, } from "./openspec-parse.js";
+function loadProjection(changeDir) {
+    const path = join(changeDir, "harness.projection.yaml");
+    const raw = parseYaml(readFileSync(path, "utf8"));
+    if (raw.schema !== "harness.projection/v1") {
+        throw new Error(`unsupported projection schema "${raw.schema}" (expected harness.projection/v1)`);
+    }
+    if (!raw.change || !raw.component || !Array.isArray(raw.units)) {
+        throw new Error("harness.projection.yaml missing change, component, or units");
+    }
+    return raw;
+}
+function capabilityCache() {
+    return new Map();
+}
+function requirementsFor(cache, openspecRoot, changeDir, capability) {
+    let loaded = cache.get(capability);
+    if (!loaded) {
+        loaded = loadCapabilityRequirements(openspecRoot, capability, changeDir);
+        cache.set(capability, loaded);
+    }
+    return loaded;
+}
+function resolveAcceptance(entry, cache, openspecRoot, changeDir, unitId, index) {
+    if (entry.statement) {
+        const criterion = { statement: entry.statement.trim() };
+        if (entry.verifier)
+            criterion.verifier = entry.verifier;
+        if (entry.manual)
+            criterion.manual = entry.manual.trim();
+        return { criterion };
+    }
+    const reqs = requirementsFor(cache, openspecRoot, changeDir, entry.source.capability);
+    const key = entry.source.requirement.trim().toLowerCase();
+    const req = reqs.get(key);
+    if (!req) {
+        return {
+            criterion: { statement: "UNRESOLVED" },
+            finding: {
+                specPath: join(changeDir, "harness.projection.yaml"),
+                level: "error",
+                message: `unit "${unitId}" acceptance[${index}]: requirement "${entry.source.requirement}" not found in capability "${entry.source.capability}"`,
+                criterionIndex: index,
+            },
+        };
+    }
+    try {
+        const statement = resolveRequirementStatement(req, entry.source.scenario);
+        const criterion = { statement };
+        if (entry.verifier)
+            criterion.verifier = entry.verifier;
+        if (entry.manual)
+            criterion.manual = entry.manual.trim();
+        if (!criterion.verifier && !criterion.manual) {
+            return {
+                criterion,
+                finding: {
+                    specPath: join(changeDir, "harness.projection.yaml"),
+                    level: "error",
+                    message: `unit "${unitId}" acceptance[${index}]: must name verifier or manual`,
+                    criterionIndex: index,
+                },
+            };
+        }
+        return { criterion };
+    }
+    catch (error) {
+        return {
+            criterion: { statement: "UNRESOLVED" },
+            finding: {
+                specPath: join(changeDir, "harness.projection.yaml"),
+                level: "error",
+                message: `unit "${unitId}" acceptance[${index}]: ${error.message}`,
+                criterionIndex: index,
+            },
+        };
+    }
+}
+function toHarnessSpec(projection, unit, cache, openspecRoot, changeDir) {
+    const findings = [];
+    const acceptance_criteria = [];
+    for (const [index, entry] of unit.acceptance.entries()) {
+        const { criterion, finding } = resolveAcceptance(entry, cache, openspecRoot, changeDir, unit.id, index);
+        acceptance_criteria.push(criterion);
+        if (finding)
+            findings.push(finding);
+    }
+    const spec = {
+        id: unit.id,
+        component: projection.component,
+        intent: unit.intent.trim(),
+        acceptance_criteria,
+        scope: unit.scope,
+        ...(unit.mode ? { mode: unit.mode } : {}),
+        ...(unit.size_budget ? { size_budget: unit.size_budget } : {}),
+        ...(unit.door ? { door: unit.door } : {}),
+        merge_facts: {
+            adds_dependency: unit.merge_facts?.adds_dependency ?? false,
+            ...(unit.merge_facts?.schema_change ? { schema_change: true } : {}),
+            ...(unit.merge_facts?.security ? { security: true } : {}),
+            ...(unit.merge_facts?.gate_external ? { gate_external: true } : {}),
+            ...(unit.merge_facts?.artifact_producer_change
+                ? { artifact_producer_change: true }
+                : {}),
+        },
+        ...(unit.deps?.length ? { deps: unit.deps } : {}),
+        ...(unit.outputs?.length ? { outputs: unit.outputs } : {}),
+        ...(unit.consumes?.length ? { consumes: unit.consumes } : {}),
+    };
+    return { spec, findings };
+}
+export function emitUnitYamlPretty(spec) {
+    const acLines = spec.acceptance_criteria
+        .map((ac) => {
+        const parts = [`  - statement: >`, ...indentBlock(ac.statement, 6)];
+        if (ac.verifier)
+            parts.push(`    verifier: ${ac.verifier}`);
+        if (ac.manual) {
+            parts.push(`    manual: >`, ...indentBlock(ac.manual, 6));
+        }
+        return parts.join("\n");
+    })
+        .join("\n");
+    const lines = [
+        `id: ${spec.id}`,
+        `component: ${spec.component}`,
+        `intent: >`,
+        ...indentBlock(spec.intent.trim(), 2),
+        `acceptance_criteria:`,
+        acLines,
+        `scope:`,
+        ...spec.scope.map((s) => `  - ${s}`),
+    ];
+    if (spec.size_budget) {
+        lines.push(`size_budget:`);
+        if (spec.size_budget.max_changed_lines !== undefined) {
+            lines.push(`  max_changed_lines: ${spec.size_budget.max_changed_lines}`);
+        }
+        if (spec.size_budget.max_changed_files !== undefined) {
+            lines.push(`  max_changed_files: ${spec.size_budget.max_changed_files}`);
+        }
+    }
+    if (spec.deps?.length) {
+        lines.push(`deps:`);
+        for (const dep of spec.deps)
+            lines.push(`  - ${dep}`);
+    }
+    if (spec.door)
+        lines.push(`door: ${spec.door}`);
+    const mf = spec.merge_facts;
+    if (mf) {
+        lines.push(`merge_facts:`);
+        lines.push(`  adds_dependency: ${mf.adds_dependency ?? false}`);
+        if (mf.schema_change)
+            lines.push(`  schema_change: true`);
+        if (mf.security)
+            lines.push(`  security: true`);
+        if (mf.gate_external)
+            lines.push(`  gate_external: true`);
+        if (mf.artifact_producer_change) {
+            lines.push(`  artifact_producer_change: true`);
+        }
+    }
+    if (spec.outputs?.length) {
+        lines.push(`outputs:`);
+        for (const o of spec.outputs)
+            lines.push(`  - ${o}`);
+    }
+    if (spec.consumes?.length) {
+        lines.push(`consumes:`);
+        for (const c of spec.consumes)
+            lines.push(`  - ${c}`);
+    }
+    return lines.join("\n") + "\n";
+}
+function indentBlock(text, spaces) {
+    const pad = " ".repeat(spaces);
+    return text.trim().split("\n").map((line) => `${pad}${line}`);
+}
+export function projectSpecs(opts) {
+    const projection = loadProjection(opts.changeDir);
+    const cache = capabilityCache();
+    mkdirSync(opts.outDir, { recursive: true });
+    const findings = [];
+    const units = [];
+    for (const unit of projection.units) {
+        const { spec, findings: unitFindings } = toHarnessSpec(projection, unit, cache, opts.openspecRoot, opts.changeDir);
+        findings.push(...unitFindings);
+        const outPath = join(opts.outDir, `${unit.id}.yaml`);
+        writeFileSync(outPath, emitUnitYamlPretty(spec), "utf8");
+        units.push({ id: unit.id, path: outPath });
+    }
+    const checkFindings = checkSpecs(opts.outDir);
+    findings.push(...checkFindings);
+    const errors = findings.filter((f) => f.level === "error");
+    return { ok: errors.length === 0, units, findings };
+}
+//# sourceMappingURL=project.js.map

package/dist/internal/system/substrate/index.js

@@ -0,0 +1,14 @@
+/**
+ * substrate — applies and audits the agent-blind guarantee layer: branch
+ * protection (nothing lands without a green envelope; no client-side
+ * --no-verify bypass because enforcement isn't client-side), required
+ * workflows, merge-queue settings.
+ *
+ * `harness init` applies it; `harness verify` includes an audit that the
+ * substrate is still configured — a guardrail is only as strong as the
+ * lowest layer that enforces it, and this IS the lowest layer.
+ */
+export function audit(_projectRoot) {
+    throw new Error("not implemented (skeleton)");
+}
+//# sourceMappingURL=index.js.map