harness-everything 0.19.0 → 0.20.0

package/scripts/generate-sbom.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Generate a CycloneDX SBOM from package.json and package-lock.json.
+ *
+ * The file is intentionally generated during semantic-release rather than
+ * committed on every change. npm packs the generated root-level file, so the
+ * published package carries the exact release version and dependency graph.
+ */
+
+const fs = require('fs');
+const crypto = require('crypto');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+const DEFAULT_OUTPUT = path.join(ROOT, 'sbom.cdx.json');
+const PACKAGE_NAME = 'harness-everything';
+const CYCLONEDX_VERSION = '1.7';
+const CYCLONEDX_SCHEMA_URL = `https://cyclonedx.org/schema/bom-${CYCLONEDX_VERSION}.schema.json`;
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function npmPurl(name, version) {
+  const purlName = String(name).startsWith('@') ? `%40${String(name).slice(1)}` : String(name);
+  return `pkg:npm/${purlName}@${encodeURIComponent(version)}`;
+}
+
+function serialNumberFor(name, version) {
+  // UUID v5-shaped, deterministic serial number: release SBOMs remain
+  // comparable without introducing a random value into the generated file.
+  const namespace = Buffer.from('6ba7b8109dad11d180b400c04fd430c8', 'hex');
+  const digest = crypto.createHash('sha1').update(namespace).update(`${name}@${version}`).digest();
+  digest[6] = (digest[6] & 0x0f) | 0x50;
+  digest[8] = (digest[8] & 0x3f) | 0x80;
+  const hex = digest.toString('hex').slice(0, 32);
+  return `urn:uuid:${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+function integrityHash(integrity) {
+  if (typeof integrity !== 'string') return null;
+  const match = integrity.match(/^(sha\d+)-(.+)$/i);
+  if (!match) return null;
+  const algorithm = match[1].toUpperCase().replace(/^SHA(\d+)$/, 'SHA-$1');
+  return { alg: algorithm, content: match[2] };
+}
+
+function packageNameFromKey(key, record) {
+  if (record && record.name) return record.name;
+  const marker = '/node_modules/';
+  const last = key.lastIndexOf(marker);
+  const name = last === -1 ? key.replace(/^node_modules\//, '') : key.slice(last + marker.length);
+  if (name.startsWith('@')) return name;
+  return name.split('/node_modules/').pop();
+}
+
+function componentFor(key, record) {
+  const name = packageNameFromKey(key, record);
+  if (!record || !record.version || !name) return null;
+  const purl = npmPurl(name, record.version);
+  const component = {
+    type: 'library',
+    'bom-ref': purl,
+    name,
+    version: record.version,
+    scope: record.dev ? 'excluded' : (record.optional ? 'optional' : 'required'),
+    purl
+  };
+  const hash = integrityHash(record.integrity);
+  if (hash) component.hashes = [hash];
+  return component;
+}
+
+function resolveDependencyKey(packages, parentKey, dependencyName) {
+  let current = parentKey;
+  while (true) {
+    const candidate = current
+      ? `${current}/node_modules/${dependencyName}`
+      : `node_modules/${dependencyName}`;
+    if (packages[candidate] && packages[candidate].version) return candidate;
+    const marker = '/node_modules/';
+    const markerIndex = current.lastIndexOf(marker);
+    if (markerIndex !== -1) current = current.slice(0, markerIndex);
+    else if (current.startsWith('node_modules/')) current = '';
+    else break;
+  }
+  return null;
+}
+
+function directDependencyNames(packageJson) {
+  return [...new Set([
+    ...Object.keys(packageJson.dependencies || {}),
+    ...Object.keys(packageJson.optionalDependencies || {}),
+    ...Object.keys(packageJson.devDependencies || {})
+  ])].sort();
+}
+
+function buildBom(root = ROOT, options = {}) {
+  const packageJson = readJson(path.join(root, 'package.json'));
+  const lock = readJson(path.join(root, 'package-lock.json'));
+  const version = options.version || packageJson.version;
+  const name = packageJson.name || PACKAGE_NAME;
+  const rootPurl = npmPurl(name, version);
+  const packages = lock.packages || {};
+  const components = [];
+  const componentByKey = new Map();
+
+  for (const [key, record] of Object.entries(packages)) {
+    if (!key) continue;
+    const component = componentFor(key, record);
+    if (!component) continue;
+    components.push(component);
+    componentByKey.set(key, component);
+  }
+
+  components.sort((left, right) => left.purl.localeCompare(right.purl));
+  const dependencyRecords = [];
+  const dependencySources = [['', packages[''] || {}]];
+  for (const [key, record] of Object.entries(packages)) {
+    if (key) dependencySources.push([key, record]);
+  }
+  for (const [key, record] of dependencySources) {
+    const sourceRef = key ? componentByKey.get(key)?.['bom-ref'] : rootPurl;
+    if (!sourceRef) continue;
+    const dependencyNames = key ? Object.keys(record.dependencies || {}) : directDependencyNames(packageJson);
+    const dependsOn = dependencyNames
+      .map(dependencyName => resolveDependencyKey(packages, key, dependencyName))
+      .map(dependencyKey => dependencyKey && componentByKey.get(dependencyKey)?.['bom-ref'])
+      .filter(Boolean)
+      .sort();
+    if (dependsOn.length) dependencyRecords.push({ ref: sourceRef, dependsOn: [...new Set(dependsOn)] });
+  }
+  dependencyRecords.sort((left, right) => left.ref.localeCompare(right.ref));
+
+  const bom = {
+    $schema: CYCLONEDX_SCHEMA_URL,
+    bomFormat: 'CycloneDX',
+    specVersion: CYCLONEDX_VERSION,
+    serialNumber: options.serialNumber || serialNumberFor(name, version),
+    version: 1,
+    metadata: {
+      timestamp: options.timestamp || new Date().toISOString(),
+      tools: [{ vendor: 'Harness Everything', name: 'generate-sbom.js', version }],
+      component: {
+        type: 'application',
+        'bom-ref': rootPurl,
+        name,
+        version,
+        purl: rootPurl
+      }
+    },
+    components,
+    dependencies: dependencyRecords
+  };
+  return bom;
+}
+
+function validateBom(bom, expectedVersion) {
+  if (!bom || bom.bomFormat !== 'CycloneDX') throw new Error('SBOM must use the CycloneDX format');
+  if (bom.$schema !== CYCLONEDX_SCHEMA_URL) throw new Error(`SBOM schema must be ${CYCLONEDX_SCHEMA_URL}`);
+  if (bom.specVersion !== CYCLONEDX_VERSION) throw new Error(`SBOM specVersion must be ${CYCLONEDX_VERSION}, got ${bom.specVersion}`);
+  if (!Number.isInteger(bom.version) || bom.version < 1) throw new Error('SBOM document version is missing');
+  if (!/^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(String(bom.serialNumber || ''))) {
+    throw new Error('SBOM serialNumber must be a UUID URN');
+  }
+  const component = bom.metadata && bom.metadata.component;
+  if (!component || component.name !== PACKAGE_NAME) throw new Error('SBOM metadata component must be harness-everything');
+  if (!component.version || (expectedVersion && component.version !== expectedVersion)) {
+    throw new Error(`SBOM metadata version drift: expected ${expectedVersion || 'a version'}, got ${component.version || 'missing'}`);
+  }
+  if (!Array.isArray(bom.components)) throw new Error('SBOM components array is missing');
+  for (const entry of bom.components) {
+    if (!entry.name || !entry.version || !entry.purl || !entry['bom-ref']) throw new Error('SBOM component is incomplete');
+  }
+  if (!Array.isArray(bom.dependencies)) throw new Error('SBOM dependencies array is missing');
+  return true;
+}
+
+function writeBom(output, root = ROOT, options = {}) {
+  const bom = buildBom(root, options);
+  validateBom(bom, options.version);
+  fs.writeFileSync(output, `${JSON.stringify(bom, null, 2)}\n`, 'utf8');
+  return bom;
+}
+
+function parseArgs(argv) {
+  const options = { output: DEFAULT_OUTPUT, validate: null, version: null };
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === '--output') options.output = path.resolve(argv[++index] || '');
+    else if (arg === '--validate') options.validate = path.resolve(argv[++index] || '');
+    else if (arg === '--version') options.version = argv[++index] || null;
+    else if (arg === '--help' || arg === '-h') options.help = true;
+    else throw new Error(`Unknown option: ${arg}`);
+  }
+  return options;
+}
+
+function main(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    console.log('Usage: node scripts/generate-sbom.js [--output <file>] [--version <x.y.z>]');
+    console.log('       node scripts/generate-sbom.js --validate <file> [--version <x.y.z>]');
+    return 0;
+  }
+  if (options.validate) {
+    const bom = readJson(options.validate);
+    validateBom(bom, options.version);
+    console.log(`Validated CycloneDX SBOM ${options.validate} (${bom.components.length} components).`);
+    return 0;
+  }
+  const bom = writeBom(options.output, ROOT, { version: options.version });
+  console.log(`Generated CycloneDX SBOM ${options.output} (${bom.components.length} components).`);
+  return 0;
+}
+
+if (require.main === module) {
+  try {
+    process.exitCode = main();
+  } catch (error) {
+    console.error(`[Error] ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = {
+  buildBom,
+  componentFor,
+  CYCLONEDX_SCHEMA_URL,
+  CYCLONEDX_VERSION,
+  directDependencyNames,
+  integrityHash,
+  main,
+  npmPurl,
+  validateBom,
+  writeBom
+};

package/scripts/lib/advisory-text.js

@@ -7,14 +7,14 @@ const MARKER = "Harness OS Guidance (Advisory)";
 
 const advisoryInstructions = [
   `\n# ${MARKER}`,
-  `Harness is an observer/router/reminder layer on this surface; do not treat its workflow guidance as a hard scheduler.`,
+  `Harness is an observer/router/reminder layer on this surface. Instruction/advisory delivery describes the mechanism, not semantic optionality; do not treat Harness as a hard scheduler.`,
   ``,
-  `## 🚦 ENTRY TRIAGE & WORKFLOW GUIDANCE`,
+  `## 🚦 ENTRY TRIAGE & SEMANTIC CONTRACT`,
   `For software/project work, load the \`harness-everything\` skill and establish routing context before broad mutation:`,
-  `1. Run \`npx github:dyphn1/Harness-everything next "<Brief summary of user's prompt>"\` when terminal execution is available.`,
-  `2. For EVERY suggested skill, read its complete \`SKILL.md\` entry and evaluate applicability from \`USE FOR\`, \`DO NOT USE FOR\`, and its basic flow.`,
-  `3. Treat the selected workflow topology and numeric limits as planning guidance, not a lock. Choose, combine, reorder, or skip steps when evidence supports it.`,
-  `4. Prefer objective verification before declaring done and worktree isolation for broad/Tier-3 mutation.`,
+  `1. MUST route before broad mutation; run \`npx github:dyphn1/Harness-everything next "<Brief summary of user's prompt>"\` when terminal execution is available and no equivalent routing state was injected.`,
+  `2. MUST read/evaluate EVERY suggested skill. If applicable, MUST follow its core contract; if not-applicable, keep a flow-grounded reason.`,
+  `3. Selected-topology required obligations are MUSTs. Implementation tactics MAY adapt; numeric iteration/revision/replan/worker values MAY guide planning but never hard-block.`,
+  `4. MUST verify before claiming completion. Tier-3/Fable broad mutation MUST resolve isolation: linked worktree or explicit degraded fallback.`,
   `5. Use the routing checkpoint only as internal source state for the first Harness Status; do not render a competing progress block.`,
   ``,
   `## 📣 USER-VISIBLE STATUS (MUST)`,
@@ -31,10 +31,11 @@ const advisoryInstructions = [
   `- **No universal skill pipeline**: do not force every task through TODO/TDD/Fable.`,
   `- **Rule of 3**: after 3 same-signature failures, stop micro-retrying and use a fresh diagnosis / zoom-out. This reflection boundary may block mutation until completed.`,
   `- **Permission boundaries are separate**: explicit host/user approval for destructive or external actions remains authoritative.`,
-  `- **Verification is evidence, not a cage**: missing evidence should trigger a reminder, not a persistent workflow lock.`,
-  `- **Environment discovery**: discover OS, shell, package manager/runtime, and host capability before relying on them.`,
-  `- **Memory / self-evolve**: persist only verified reusable lessons.`,
-  `- **Prefer editing**: prefer targeted edits and logically complete commits over broad rewrites.`,
+  `- **Contract strength**: MUST = required semantic obligation; SHOULD = default with evidence-based exception; MAY = optional optimization. Reminder-only mechanics never downgrade MUST.`,
+  `- **Verification is evidence, not a cage**: MUST verify before completion claims; host hooks may remind rather than persistently block.`,
+  `- **Environment discovery**: MUST establish relevant OS/shell/toolchain/host facts before relying on environment-sensitive behavior.`,
+  `- **Memory / self-evolve**: durable writes MUST be authorized by the active workflow/session contract and backed by verified reusable evidence.`,
+  `- **Editing / commits**: targeted edits SHOULD be preferred; before committing, MUST inspect the staged diff and SHOULD split unrelated concerns.`,
   ``
 ].join('\n');
 
@@ -144,15 +145,16 @@ function buildCodexGlobalContent() {
     `# ${MARKER}`,
     `This instruction surface cannot be assumed to provide hard lifecycle blocking.`,
     ``,
-    `- Discover the environment and host capabilities before relying on them.`,
-    `- For software/project work, run \`npx github:dyphn1/Harness-everything next "<summary>"\` before mutation and use the routing checkpoint as source state for the first Harness Status.`,
+    `- MUST establish relevant environment/host facts before relying on environment-sensitive behavior.`,
+    `- For software/project work, MUST establish routing before broad mutation; use \`npx github:dyphn1/Harness-everything next "<summary>"\` when terminal execution is available and routing state was not already injected.`,
     `- For non-trivial work, MUST render one Markdown \`### 🚦 Harness Status\` with bullet-aligned bold \`Current\`, \`Read / Evidence\`, \`Next\`, and optional \`Risk / Blocked\`; repeat it at major phase/direction boundaries and before final completion.`,
-    `- Read every suggested skill's complete \`SKILL.md\` entry before resolving applicability; do not omit it from metadata or confidence alone.`,
-    `- Use the selected workflow topology as planning guidance; the model may adapt or skip steps with an explicit evidence-based reason.`,
+    `- MUST read/evaluate every suggested skill; applicable skill core contracts MUST be followed, while not-applicable needs a flow-grounded reason.`,
+    `- Selected-topology required obligations are MUSTs; implementation tactics MAY adapt and numeric planning values MAY guide but never hard-block.`,
     `- Do not impose a universal TODO/TDD/Fable sequence; use the smallest useful topology plus applicable skills.`,
-    `- Prefer objective verification before declaring done; missing verification is a reminder, not a persistent lock.`,
-    `- After 3 same-signature failures, stop retrying and use a fresh diagnosis / zoom-out.`,
-    `- Prefer targeted edits and logically complete commits.`,
+    `- MUST verify before declaring done; a reminder-only host mechanism does not make verification optional.`,
+    `- Tier-3/Fable broad mutation MUST resolve isolation: verified linked worktree or explicit degraded fallback.`,
+    `- After 3 same-signature failures, MUST stop retrying and use a fresh diagnosis / zoom-out.`,
+    `- Targeted edits SHOULD be preferred; before committing, MUST inspect the staged diff and SHOULD split unrelated concerns.`,
     ``
   ].join('\n');
 }

package/to-tickets/SKILL.md

@@ -4,7 +4,7 @@ description: Break a to-spec feature-spec, a plan, or a conversation into tracer
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.12.0
+  version: 0.19.1
 ---
 
 # To Tickets
@@ -33,7 +33,7 @@ Cuts a plan or spec into tracer-bullet vertical slices, each declaring its block
 ## Process
 
 1. Resolve path: script check (Exit 0 = configured location) → workspace convention dirs → platform fallback (`.claude`/`.github`/`.cursor` + `/harness-everything/tickets/`).
-2. Gather context: prefer a referenced to-spec spec — design-audit verification MANDATORY first, else refuse; no spec is fine.
+2. Gather context: **SHOULD** use a referenced to-spec spec when available — design-audit verification is MANDATORY first, else refuse; no spec is fine.
 3. Explore codebase (optional): evidence-cited findings only; prefactor first.
 4. Draft vertical slices: complete path through every layer, demoable alone, one context window each; declare blocking edges.
 5. Quiz the user on granularity and edges until approved (MANDATORY gate).

package/using-git-worktrees/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: using-git-worktrees
-description: Use when starting feature work needing isolation or before implementation plans - recommends an isolated workspace via native tools or git worktree fallback
+description: Use when work needs isolation or before major implementation plans - resolves workspace isolation via native tools or git worktree fallback, with an explicit degraded fallback when isolation is unavailable
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.16.1
+  version: 0.19.1
 ---
 
 # Using Git Worktrees
@@ -13,9 +13,9 @@ Use native worktree support first; raw Git is the fallback.
 
 ## Contract
 
-- **Major workflow guidance** — Tier 3 / Fable-class engineering is safer in a linked worktree before broad source/artifact mutation. Reuse one or create one when practical.
-- **Ordinary mode** — isolation-needing feature work may honor an explicit user preference to stay in place.
-- Never nest a worktree inside an already isolated worktree.
+- **Tier 3 / Fable (MUST resolve)** — before broad source/artifact mutation, reuse/create a verified linked worktree. If isolation is unavailable or the user explicitly chooses to stay in place, MUST report an explicit degraded fallback/risk before continuing.
+- **Ordinary mode (SHOULD)** — use isolation when it materially reduces collision/risk; explicit user preference may keep work in place.
+- **MUST NOT** nest a worktree inside an already isolated worktree.
 
 ## Workflow
 
@@ -28,7 +28,7 @@ git rev-parse --show-superproject-working-tree
 ```
 Different git/common dirs and no superproject => already isolated; continue to Step 2. A submodule is a normal repo for this check.
 
-**Step 1 — Create/enter**: prefer native `EnterWorktree`, `/worktree`, or `--worktree`. Otherwise use `git worktree add "$path" -b "$BRANCH_NAME"`. Prefer an already-ignored or external/sibling path. If creation/entry fails, report it and continue only with explicit awareness of the isolation risk.
+**Step 1 — Create/enter**: use native `EnterWorktree`, `/worktree`, or `--worktree` first; otherwise use `git worktree add "$path" -b "$BRANCH_NAME"`. Use an already-ignored or external/sibling path when possible. If creation/entry fails, MUST surface the degraded isolation disposition before continuing.
 
 **Step 2 — Setup**: install project dependencies as needed.