forge-workflow 0.1.0-beta.4 → 0.1.0-beta.6

package/lib/kernel/taxonomy-validator.js

@@ -29,7 +29,10 @@ const STATUS_TRANSITIONS = Object.freeze({
 	backlog: Object.freeze(['open', 'cancelled']),
 });
 
-const CLAIM_STATES = Object.freeze(['active', 'released', 'expired']);
+// `reclaimable` is the historical row left behind when an expired active lease is
+// superseded. It is distinct from `expired`: both are non-authoritative history,
+// but reclaimable records that the slot was deliberately freed for another owner.
+const CLAIM_STATES = Object.freeze(['active', 'released', 'expired', 'reclaimable']);
 
 const DEFAULT_PRIORITY_RANK = 2;
 const MAX_DISPLAY_PRIORITY_RANK = 4;

package/lib/kernel/windows-private-acl.js

@@ -0,0 +1,239 @@
+'use strict';
+
+/* global ActiveXObject, Enumerator, VBArray, WScript */
+
+// This file is executed by Windows Script Host and loaded by Bun/Node tests.
+// Keep its syntax compatible with the system JScript engine.
+var ADS_PATH_FILE = 1;
+var ADS_SD_FORMAT_IID = 1;
+var ADS_SD_FORMAT_RAW = 2;
+var ADS_SECURITY_INFO_OWNER = 1;
+var ADS_SECURITY_INFO_DACL = 4;
+var PROTECTED_DACL_SECURITY_INFORMATION = 0x80000000;
+var SE_DACL_PRESENT = 0x0004;
+var SE_DACL_PROTECTED = 0x1000;
+var SE_SELF_RELATIVE = 0x8000;
+var FILE_ALL_ACCESS = 0x001f01ff;
+var ACCESS_ALLOWED_ACE_TYPE = 0;
+var OBJECT_INHERIT_ACE = 1;
+var CONTAINER_INHERIT_ACE = 2;
+var MAX_TARGETS = 128;
+
+function invariant(condition, message) {
+	if (!condition) throw new Error(message);
+}
+
+function atStage(code, action) {
+	try {
+		return action();
+	} catch (error) {
+		error.forgeExitCode = code;
+		throw error;
+	}
+}
+
+function bytesFromSafeArray(value) {
+	var values = new VBArray(value).toArray();
+	var bytes = [];
+	for (var i = 0; i < values.length; i++) bytes.push(values[i] & 0xff);
+	return bytes;
+}
+
+function u16(bytes, offset) {
+	invariant(offset >= 0 && offset + 2 <= bytes.length, 'truncated uint16');
+	return bytes[offset] | (bytes[offset + 1] << 8);
+}
+
+function u32(bytes, offset) {
+	invariant(offset >= 0 && offset + 4 <= bytes.length, 'truncated uint32');
+	return (bytes[offset] | (bytes[offset + 1] << 8) | (bytes[offset + 2] << 16) | (bytes[offset + 3] << 24)) >>> 0;
+}
+
+function sidAt(bytes, offset) {
+	invariant(offset > 0 && offset + 8 <= bytes.length, 'missing SID');
+	var revision = bytes[offset];
+	var count = bytes[offset + 1];
+	var end = offset + 8 + (count * 4);
+	invariant(revision === 1 && end <= bytes.length, 'malformed SID');
+	var authority = 0;
+	for (var i = 0; i < 6; i++) authority = (authority * 256) + bytes[offset + 2 + i];
+	invariant(authority <= 9007199254740991, 'unsupported SID authority');
+	var parts = ['S', String(revision), String(authority)];
+	for (var j = 0; j < count; j++) parts.push(String(u32(bytes, offset + 8 + (j * 4))));
+	return { end: end, value: parts.join('-') };
+}
+
+function inspectDescriptor(bytes, expectedOwnerSid, expectedAceFlags) {
+	invariant(bytes && typeof bytes.length === 'number' && bytes.length >= 20, 'malformed security descriptor');
+	invariant(/^S-1-[0-9]+(?:-[0-9]+)+$/.test(expectedOwnerSid), 'invalid expected SID');
+	invariant(bytes[0] === 1, 'unsupported security descriptor revision');
+	var control = u16(bytes, 2);
+	invariant((control & SE_SELF_RELATIVE) !== 0, 'security descriptor is not self-relative');
+	invariant((control & SE_DACL_PRESENT) !== 0, 'DACL is absent');
+	invariant((control & SE_DACL_PROTECTED) !== 0, 'DACL is not protected');
+	var owner = sidAt(bytes, u32(bytes, 4));
+	invariant(owner.value === expectedOwnerSid, 'owner changed');
+	var daclOffset = u32(bytes, 16);
+	invariant(daclOffset > 0 && daclOffset + 8 <= bytes.length, 'DACL is malformed');
+	var aclRevision = bytes[daclOffset];
+	var aclSize = u16(bytes, daclOffset + 2);
+	var aceCount = u16(bytes, daclOffset + 4);
+	invariant(aclRevision === 2, 'unsupported ACL revision');
+	invariant(aclSize >= 8 && daclOffset + aclSize <= bytes.length, 'ACL size is malformed');
+	invariant(aceCount === 1, 'DACL must contain one ACE');
+	var aceOffset = daclOffset + 8;
+	invariant(aceOffset + 8 <= daclOffset + aclSize, 'ACE is truncated');
+	var aceType = bytes[aceOffset];
+	var aceFlags = bytes[aceOffset + 1];
+	var aceSize = u16(bytes, aceOffset + 2);
+	invariant(aceType === ACCESS_ALLOWED_ACE_TYPE, 'ACE must allow access');
+	invariant(aceFlags === expectedAceFlags, 'ACE flags are not exact');
+	invariant(aceSize >= 16 && aceOffset + aceSize === daclOffset + aclSize, 'ACE size is not exact');
+	invariant(u32(bytes, aceOffset + 4) === FILE_ALL_ACCESS, 'ACE is not full control');
+	var trustee = sidAt(bytes, aceOffset + 8);
+	invariant(trustee.value === expectedOwnerSid, 'ACE trustee is not the owner');
+	invariant(trustee.end === aceOffset + aceSize, 'ACE contains trailing data');
+	return { aceFlags: aceFlags, ownerSid: owner.value };
+}
+
+function inspectIidDescriptor(descriptor, expectedOwner, expectedAceFlags, enumeratorFactory) {
+	invariant(descriptor && descriptor.Owner, 'IID owner is absent');
+	if (expectedOwner !== null) invariant(String(descriptor.Owner) === expectedOwner, 'IID owner changed');
+	invariant((descriptor.Control & SE_DACL_PRESENT) !== 0, 'IID DACL is absent');
+	invariant((descriptor.Control & SE_DACL_PROTECTED) !== 0, 'IID DACL is not protected');
+	var dacl = descriptor.DiscretionaryAcl;
+	invariant(dacl && dacl.AceCount === 1, 'IID DACL must contain one ACE');
+	var entries = enumeratorFactory ? enumeratorFactory(dacl) : new Enumerator(dacl);
+	invariant(!entries.atEnd(), 'IID ACE is absent');
+	var ace = entries.item();
+	invariant(ace.AceType === ACCESS_ALLOWED_ACE_TYPE, 'IID ACE must allow access');
+	invariant((ace.AccessMask >>> 0) === FILE_ALL_ACCESS, 'IID ACE is not full control');
+	invariant(ace.AceFlags === expectedAceFlags, 'IID ACE flags are not exact');
+	entries.moveNext();
+	invariant(entries.atEnd(), 'IID DACL contains extra ACEs');
+}
+
+function rawDescriptor(utility, targetPath) {
+	utility.SecurityMask = ADS_SECURITY_INFO_OWNER | ADS_SECURITY_INFO_DACL;
+	return bytesFromSafeArray(utility.GetSecurityDescriptor(targetPath, ADS_PATH_FILE, ADS_SD_FORMAT_RAW));
+}
+
+function iidDescriptor(utility, targetPath) {
+	utility.SecurityMask = ADS_SECURITY_INFO_OWNER | ADS_SECURITY_INFO_DACL;
+	return utility.GetSecurityDescriptor(targetPath, ADS_PATH_FILE, ADS_SD_FORMAT_IID);
+}
+
+function ownerSid(bytes) {
+	invariant(bytes && typeof bytes.length === 'number' && bytes.length >= 20, 'malformed security descriptor');
+	invariant(bytes[0] === 1, 'unsupported security descriptor revision');
+	invariant((u16(bytes, 2) & SE_SELF_RELATIVE) !== 0, 'security descriptor is not self-relative');
+	return sidAt(bytes, u32(bytes, 4)).value;
+}
+
+function readTargets(environment, fso) {
+	var countText = String(environment('FORGE_PRIVATE_ACL_COUNT'));
+	invariant(/^[1-9][0-9]*$/.test(countText), 'invalid target count');
+	var count = Number(countText);
+	invariant(count <= MAX_TARGETS, 'too many ACL targets');
+	var targets = [];
+	for (var i = 0; i < count; i++) {
+		var targetPath = String(environment('FORGE_PRIVATE_ACL_TARGET_' + i));
+		invariant(targetPath.length > 0 && targetPath.indexOf('\0') === -1, 'invalid ACL target');
+		var isDirectory = fso.FolderExists(targetPath);
+		var isFile = fso.FileExists(targetPath);
+		invariant(isDirectory !== isFile, 'ACL target does not exist');
+		targets.push({ isDirectory: isDirectory, path: targetPath });
+	}
+	return targets;
+}
+
+function applyOwnerOnlyDacl(utility, target, currentSid, createObject, descriptor) {
+	var dacl = createObject('AccessControlList');
+	dacl.AclRevision = 2;
+	var ace = createObject('AccessControlEntry');
+	ace.Trustee = currentSid;
+	ace.AccessMask = FILE_ALL_ACCESS;
+	ace.AceType = ACCESS_ALLOWED_ACE_TYPE;
+	ace.AceFlags = target.isDirectory ? (OBJECT_INHERIT_ACE | CONTAINER_INHERIT_ACE) : 0;
+	dacl.AddAce(ace);
+	descriptor.Owner = currentSid;
+	descriptor.DiscretionaryAcl = dacl;
+	descriptor.Control = descriptor.Control | SE_DACL_PRESENT | SE_DACL_PROTECTED;
+	utility.SecurityMask = ADS_SECURITY_INFO_OWNER | ADS_SECURITY_INFO_DACL | PROTECTED_DACL_SECURITY_INFORMATION;
+	utility.SetSecurityDescriptor(target.path, ADS_PATH_FILE, descriptor, ADS_SD_FORMAT_IID);
+}
+
+function runWithDependencies(dependencies) {
+	var environment = dependencies.environment;
+	var fso = dependencies.fso;
+	var utility = dependencies.utility;
+	var createObject = dependencies.createObject;
+	var enumeratorFactory = dependencies.enumeratorFactory;
+	var currentSid = String(environment('FORGE_PRIVATE_ACL_SID'));
+	invariant(/^S-1-[0-9]+(?:-[0-9]+)+$/.test(currentSid), 'invalid current SID');
+	var targets = readTargets(environment, fso);
+	var owners = [];
+	var iidOwners = [];
+	var i;
+
+	// Prove every target and descriptor are readable before the first mutation.
+	for (i = 0; i < targets.length; i++) {
+		var beforeRaw = atStage(20, function () { return rawDescriptor(utility, targets[i].path); });
+		var beforeIid = atStage(21, function () { return iidDescriptor(utility, targets[i].path); });
+		owners.push(atStage(22, function () { return ownerSid(beforeRaw); }));
+		iidOwners.push(atStage(23, function () {
+			invariant(beforeIid && beforeIid.Owner, 'precheck IID owner is absent');
+			return String(beforeIid.Owner);
+		}));
+	}
+
+	for (i = 0; i < targets.length; i++) {
+		// Recheck immediately before changing the owner and DACL together.
+		var currentIid = atStage(30, function () {
+			var isDirectory = fso.FolderExists(targets[i].path);
+			var isFile = fso.FileExists(targets[i].path);
+			invariant(isDirectory === targets[i].isDirectory && isFile !== isDirectory, 'target type changed before mutation');
+			invariant(ownerSid(rawDescriptor(utility, targets[i].path)) === owners[i], 'owner changed before mutation');
+			var descriptor = iidDescriptor(utility, targets[i].path);
+			invariant(descriptor && descriptor.Owner, 'IID owner is absent before mutation');
+			invariant(String(descriptor.Owner) === iidOwners[i], 'IID owner changed before mutation');
+			return descriptor;
+		});
+		atStage(31, function () { applyOwnerOnlyDacl(utility, targets[i], currentSid, createObject, currentIid); });
+		var expectedFlags = targets[i].isDirectory ? (OBJECT_INHERIT_ACE | CONTAINER_INHERIT_ACE) : 0;
+		atStage(32, function () {
+			inspectDescriptor(rawDescriptor(utility, targets[i].path), currentSid, expectedFlags);
+		});
+		atStage(33, function () {
+			inspectIidDescriptor(iidDescriptor(utility, targets[i].path), null, expectedFlags, enumeratorFactory);
+		});
+	}
+	return true;
+}
+
+function main() {
+	try {
+		var shell = new ActiveXObject('WScript.Shell');
+		runWithDependencies({
+			createObject: function (name) { return new ActiveXObject(name); },
+			environment: shell.Environment('PROCESS'),
+			fso: new ActiveXObject('Scripting.FileSystemObject'),
+			utility: new ActiveXObject('ADsSecurityUtility')
+		});
+		WScript.Quit(0);
+	} catch (_error) {
+		var exitCode = _error && typeof _error.forgeExitCode === 'number' ? _error.forgeExitCode : 1;
+		WScript.Quit(exitCode);
+	}
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+	module.exports = {
+		FILE_ALL_ACCESS: FILE_ALL_ACCESS,
+		inspectDescriptor: inspectDescriptor,
+		inspectIidDescriptor: inspectIidDescriptor,
+		runWithDependencies: runWithDependencies
+	};
+} else {
+	main();
+}

package/lib/lefthook-wiring.js

@@ -55,6 +55,20 @@ pre-push:
       run: npm test --if-present
 `;
 
+// The same config MINUS the TDD pre-commit job, written when the project already has its own
+// pre-commit TDD/coupling gate (kernel 5b425a85 / 2699b234). Stacking a second gate on the same
+// commit is the reported bug, so Forge defers on pre-commit but still wires pre-push.
+const FORGE_USER_LEFTHOOK_YML_NO_TDD = `# Forge git hooks — installed by \`forge setup\` / \`forge init\`.
+# Your project already has its own pre-commit TDD/coupling gate, so Forge did NOT add a second
+# one here. To use Forge's gate instead, remove yours and run: forge gate enable rail.tdd_intent
+# Edit freely to add your own checks — Forge only replaces a fully-commented stub.
+
+pre-push:
+  commands:
+    tests:
+      run: npm test --if-present
+`;
+
 /**
  * A fresh `lefthook install` (run by lefthook's own npm postinstall) drops a stock
  * EXAMPLE lefthook.yml with every hook commented out. That disposable stub used to
@@ -221,10 +235,13 @@ npm test --if-present || exit 1
  * `skipped`) rather than destroyed.
  *
  * @param {string} projectRoot - Absolute path to the project root.
+ * @param {{ skipHooks?: string[] }} [options] - Hook names to leave alone entirely. `forge setup`
+ *   passes `['pre-commit']` when the project already has its own pre-commit TDD/coupling gate,
+ *   so Forge defers instead of stacking a second one (kernel 5b425a85 / 2699b234).
  * @returns {{ installed: boolean, method?: string, hooksDir?: string,
  *   written?: string[], skipped?: string[], reason?: string }}
  */
-function installNativeGitHooks(projectRoot) {
+function installNativeGitHooks(projectRoot, options = {}) {
   const hooksDir = resolveGitHooksDir(projectRoot);
   if (!hooksDir) {
     return { installed: false, reason: 'not-a-git-repo' };
@@ -235,9 +252,11 @@ function installNativeGitHooks(projectRoot) {
     return { installed: false, reason: `hooks-dir-unwritable: ${error.message}` };
   }
 
+  const skipHooks = new Set(Array.isArray(options.skipHooks) ? options.skipHooks : []);
   const written = [];
   const skipped = [];
   for (const [name, body] of Object.entries(NATIVE_HOOK_BODIES)) {
+    if (skipHooks.has(name)) continue;
     const outcome = writeNativeHook(path.join(hooksDir, name), body);
     (outcome === 'written' ? written : skipped).push(name);
   }
@@ -406,6 +425,7 @@ function verifyHooksActive(projectRoot) {
 module.exports = {
   FORGE_NATIVE_HOOK_SENTINEL,
   FORGE_USER_LEFTHOOK_YML,
+  FORGE_USER_LEFTHOOK_YML_NO_TDD,
   forgeShouldWriteLefthookConfig,
   resolveGitHooksDir,
   installNativeGitHooks,

package/lib/memory/hygiene.js

@@ -0,0 +1,191 @@
+'use strict';
+
+const { createHash } = require('node:crypto');
+
+const MEMORY_REVIEW_ENTRY_LIMIT = 200;
+const DEFAULT_FINDING_LIMIT = 50;
+const STALE_AFTER_DAYS = 90;
+const STALE_AFTER_MS = STALE_AFTER_DAYS * 24 * 60 * 60 * 1000;
+const VOLATILE_FIELDS = new Set([
+  'id', 'key', 'memory_id', 'created_at', 'updated_at', 'timestamp', 'revision',
+  'createdAt', 'updatedAt',
+]);
+const NEGATION_PREFIXES = Object.freeze(['do not ', "don't ", 'never ']);
+
+function compareCodeUnits(left, right) {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+function normalizeText(value) {
+  return String(value)
+    .normalize('NFKC')
+    .toLowerCase()
+    .replace(/[’']/g, "'")
+    .replace(/[^\p{L}\p{N}'\s]/gu, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function canonicalize(value) {
+  if (typeof value === 'string') return normalizeText(value);
+  if (Array.isArray(value)) {
+    return value.map(canonicalize).sort((left, right) =>
+      compareCodeUnits(JSON.stringify(left), JSON.stringify(right)));
+  }
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value)
+    .filter(key => !VOLATILE_FIELDS.has(key))
+    .sort(compareCodeUnits)
+    .map(key => [key, canonicalize(value[key])]));
+}
+
+function payloadFor(entry) {
+  if (entry && Object.hasOwn(entry, 'note')) return entry.note;
+  if (entry && Object.hasOwn(entry, 'value')) return entry.value;
+  return entry;
+}
+
+function fingerprint(value) {
+  return createHash('sha256').update(JSON.stringify(canonicalize(value))).digest('hex');
+}
+
+function reviewId(kind, parts) {
+  const digest = createHash('sha256')
+    .update(`${kind}\0${[...parts].sort(compareCodeUnits).join('\0')}`)
+    .digest('hex')
+    .slice(0, 16);
+  return `memory-${kind}-${digest}`;
+}
+
+function claimFor(entry) {
+  const payload = payloadFor(entry);
+  if (typeof payload !== 'string') return null;
+  let text = normalizeText(payload);
+  let negative = false;
+  const prefix = NEGATION_PREFIXES.find(candidate => text.startsWith(candidate));
+  if (prefix) {
+    negative = true;
+    text = text.slice(prefix.length).trim();
+  }
+  return text ? { basis: text, negative } : null;
+}
+
+function readOwnDataProperty(value, fieldName, subject) {
+  let descriptor;
+  try {
+    descriptor = Object.getOwnPropertyDescriptor(value, fieldName);
+  } catch {
+    throw new TypeError(`${subject} ${fieldName} must be an own data property`);
+  }
+  if (!descriptor || !Object.hasOwn(descriptor, 'value')) {
+    throw new TypeError(`${subject} ${fieldName} must be an own data property`);
+  }
+  return descriptor.value;
+}
+
+function stalenessForMemory(memory, usageProjection, options = {}) {
+  if (!memory || typeof memory !== 'object') {
+    throw new TypeError('memory must be an object');
+  }
+  const assertCanonicalIso = (value, fieldName) => {
+    if (typeof value !== 'string' || Number.isNaN(Date.parse(value))
+      || new Date(value).toISOString() !== value) {
+      throw new TypeError(`${fieldName} must be a canonical ISO timestamp`);
+    }
+  };
+  const createdAt = readOwnDataProperty(memory, 'created_at', 'memory');
+  assertCanonicalIso(createdAt, 'memory created_at');
+  let useCount = 0;
+  let baselineAt = createdAt;
+  if (usageProjection !== null && usageProjection !== undefined) {
+    if (!usageProjection || typeof usageProjection !== 'object') {
+      throw new TypeError('durable usage projection must be an object');
+    }
+    const lastUsedAt = readOwnDataProperty(usageProjection, 'last_used_at', 'durable usage projection');
+    const projectedUseCount = readOwnDataProperty(usageProjection, 'use_count', 'durable usage projection');
+    assertCanonicalIso(lastUsedAt, 'durable last_used_at');
+    if (!Number.isSafeInteger(projectedUseCount) || projectedUseCount < 0) {
+      throw new TypeError('durable usage projection use_count must be a nonnegative safe integer');
+    }
+    baselineAt = lastUsedAt;
+    useCount = projectedUseCount;
+  }
+  if (!options || typeof options !== 'object') {
+    throw new TypeError('staleness review options must be an object');
+  }
+  const now = readOwnDataProperty(options, 'now', 'staleness review options');
+  assertCanonicalIso(now, 'staleness review now');
+  const ageMs = Date.parse(now) - Date.parse(baselineAt);
+  const stale = ageMs > STALE_AFTER_MS;
+  return {
+    baseline_at: baselineAt,
+    use_count: useCount,
+    stale,
+    demote: stale,
+    age_days: Math.max(0, Math.floor(ageMs / (24 * 60 * 60 * 1000))),
+  };
+}
+
+function reviewMemories(entries, options = {}) {
+  const source = Array.isArray(entries) ? entries : [];
+  const entryLimit = Math.max(1, Math.min(options.entryLimit || MEMORY_REVIEW_ENTRY_LIMIT, MEMORY_REVIEW_ENTRY_LIMIT));
+  const findingLimit = Math.max(1, Math.min(options.findingLimit || DEFAULT_FINDING_LIMIT, DEFAULT_FINDING_LIMIT));
+  const selected = source.slice(0, entryLimit);
+  const findings = [];
+
+  const duplicateGroups = new Map();
+  for (const entry of selected) {
+    const payload = payloadFor(entry);
+    const canonical = JSON.stringify(canonicalize(payload));
+    const group = duplicateGroups.get(canonical) || [];
+    group.push(fingerprint(payload));
+    duplicateGroups.set(canonical, group);
+  }
+  for (const [canonical, members] of duplicateGroups) {
+    if (members.length < 2) continue;
+    findings.push({
+      review_id: reviewId('duplicate', [canonical]),
+      kind: 'duplicate',
+      count: members.length,
+      members: [...new Set(members)].sort(compareCodeUnits),
+    });
+  }
+
+  const claims = new Map();
+  for (const entry of selected) {
+    const claim = claimFor(entry);
+    if (!claim) continue;
+    const sides = claims.get(claim.basis) || { positive: [], negative: [] };
+    sides[claim.negative ? 'negative' : 'positive'].push(fingerprint(payloadFor(entry)));
+    claims.set(claim.basis, sides);
+  }
+  for (const [basis, sides] of claims) {
+    if (!sides.positive.length || !sides.negative.length) continue;
+    findings.push({
+      review_id: reviewId('contradiction', [basis]),
+      kind: 'contradiction',
+      claim: basis,
+      members: [...new Set([...sides.positive, ...sides.negative])].sort(compareCodeUnits),
+    });
+  }
+
+  findings.sort((left, right) => compareCodeUnits(left.review_id, right.review_id));
+  const total = Number.isInteger(options.total) && options.total >= source.length
+    ? options.total
+    : source.length;
+  return {
+    total,
+    scanned: selected.length,
+    truncated: total > selected.length || findings.length > findingLimit,
+    findings: findings.slice(0, findingLimit),
+  };
+}
+
+module.exports = {
+  MEMORY_REVIEW_ENTRY_LIMIT,
+  STALE_AFTER_DAYS,
+  reviewMemories,
+  stalenessForMemory,
+};