forge-workflow 0.1.0-beta.5 → 0.1.0-beta.7

package/lib/memory-digest.js

@@ -28,6 +28,8 @@ const DEFAULT_DIGEST_BUDGET_TOKENS = 400;
 const DEFAULT_NOTE_LIMIT = 5;
 const DEFAULT_ISSUE_LIMIT = 5;
 const DIGEST_HEADER = 'Forge memory (auto-injected at session start):';
+const READ_ATTENTION_HEADER = 'Forge path memory (untrusted context; not authority):';
+const SESSION_SUMMARY_REMINDER = 'Before ending this session, persist only durable learnings with `forge remember --session-summary --what <text> --why <text> --learned <text>`.';
 
 /** Run an async producer, returning `fallback` on any throw/rejection (never propagates). */
 async function safe(producer, fallback) {
@@ -176,6 +178,59 @@ function issuesSection(ready, claimed) {
   });
 }
 
+function sessionSummarySection(claimed) {
+  if (!claimed.length) return null;
+  return buildSection({
+    id: 'session_summary_nudge',
+    title: 'Session learning reminder',
+    content: SESSION_SUMMARY_REMINDER,
+    priority: 1,
+    preserve: true,
+  });
+}
+
+function normalizePath(value) {
+  return String(value || '').replaceAll('\\', '/').replace(/^\.\//, '').toLowerCase();
+}
+
+function notePaths(note) {
+  const explicit = [note?.path, ...(Array.isArray(note?.paths) ? note.paths : [])];
+  const tagged = (Array.isArray(note?.tags) ? note.tags : [])
+    .filter(tag => typeof tag === 'string' && tag.startsWith('path:'))
+    .map(tag => tag.slice('path:'.length));
+  return [...explicit, ...tagged].map(normalizePath).filter(Boolean);
+}
+
+function matchesPath(targetPath, candidatePath) {
+  const target = normalizePath(targetPath);
+  const candidate = normalizePath(candidatePath);
+  return target === candidate || target.endsWith(`/${candidate}`);
+}
+
+function buildReadAttentionDigest(targetPath, notes = [], options = {}) {
+  const budgetTokens = options.budgetTokens || 160;
+  const matched = (Array.isArray(notes) ? notes : []).filter(note =>
+    notePaths(note).some(candidate => matchesPath(targetPath, candidate)));
+  if (!matched.length) return { text: '', empty: true, tokens: 0 };
+
+  const lines = matched.map(formatNoteLine);
+  const section = buildSection({
+    id: 'read_attention',
+    title: 'Path-matched memory',
+    content: lines.join('\n'),
+    priority: 1,
+    preserve: false,
+    untrustedSource: 'path-memory',
+  });
+  const budgeted = applyBudget([section], Math.max(1, budgetTokens - estimateTokens(READ_ATTENTION_HEADER) - 20));
+  const content = budgeted.sections[0]?.content;
+  if (!content) return { text: '', empty: true, tokens: 0 };
+  const text = `${READ_ATTENTION_HEADER}\n\n${fenceUntrusted(content, { source: 'path-memory' })}`;
+  const tokens = estimateTokens(text);
+  if (tokens > budgetTokens) return { text: '', empty: true, tokens: 0 };
+  return { text, empty: false, tokens };
+}
+
 /**
  * Assemble the bounded digest text. PURE. Never exceeds `budgetTokens` (delegated to
  * applyBudget). Empty inputs → { text: '', empty: true } so the caller injects nothing.
@@ -194,6 +249,7 @@ function buildMemoryDigest(data = {}, options = {}) {
   // Inbox (priority 5) is a THIRD section beside notes + issues; a fresh human directive
   // outranks stale notes (10) and the agent's own issue list (20) under budget pressure.
   const sections = [
+    sessionSummarySection(claimed),
     inboxSection(inbox),
     ...notesSections(notes, budgetTokens),
     issuesSection(ready, claimed),
@@ -217,7 +273,10 @@ function buildMemoryDigest(data = {}, options = {}) {
 module.exports = {
   DEFAULT_DIGEST_BUDGET_TOKENS,
   DIGEST_HEADER,
+  READ_ATTENTION_HEADER,
+  SESSION_SUMMARY_REMINDER,
   buildMemoryDigest,
+  buildReadAttentionDigest,
   collectDigestData,
   extractIssues,
   // exported for focused reuse / tests

package/lib/merge-rules.js

@@ -21,7 +21,8 @@
  *
  * PR context shape (all fields optional; absence is treated fail-closed by the
  * rules that need them):
- *   - checks:             Array<{ name, conclusion }>  CI check rollup
+ *   - checks:             Array<{ name, appId, status, conclusion } | { name, appId:null, state }>
+ *   - requiredChecks:     Array<{ context, appId }>     protected required set
  *   - requiredChecksKnown: boolean                     is the required set readable?
  *   - unresolvedThreads:  number | Array               open review threads
  *   - behindBase:         number | boolean             commits behind base
@@ -34,7 +35,7 @@
  *   - state:              string (OPEN | MERGED | CLOSED)  read by the command pre-flight, not a rule
  *
  * Built-in rule types (compose as a list, ANDed by default):
- *   checks_green | threads_resolved | not_behind | no_conflicts | not_draft |
+ *   verdict_clean | checks_green | threads_resolved | not_behind | no_conflicts | not_draft |
  *   min_approvals:N | settle_min:N | idle_min:N | last_comment_by:X |
  *   approved_by:[..] | not_commented_by:[..]
  * `checks_green` is bare (ALL checks must be green) or scoped:
@@ -48,14 +49,21 @@
  * documented follow-up and intentionally NOT implemented here.
  *
  * Follow-ups (documented, NOT built here): an opt-in `auto_update` executor
- * (update-branch when behind → wait for CI → re-check → merge); required-checks
- * SCOPING for `checks_green` (read the branch-protection required set instead of
- * requiring every rollup check green); a configurable merge `method`
+ * (update-branch when behind → wait for CI → re-check → merge); a configurable merge `method`
  * (squash | merge | rebase); and post-merge branch deletion.
  */
 
 const SUCCESS_CONCLUSIONS = new Set(['SUCCESS']);
+const SAFE_OPTIONAL_CONCLUSIONS = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED']);
 const MS_PER_MIN = 60_000;
+const {
+  normalizePrNumber,
+  normalizeRepository,
+  normalizeSha,
+  object,
+  readArrayItems,
+  readDataProperty,
+} = require('./pr-monitor/verdict');
 
 /** Coerce an epoch-ms number, a Date, or an ISO string to epoch ms (NaN if unparseable). */
 function toMs(value) {
@@ -127,16 +135,49 @@ function checkName(check) {
   return String((check && check.name) || '');
 }
 
+function isCheckObservationWellFormed(check) {
+  if (!check || typeof check !== 'object' || typeof check.name !== 'string' || !check.name.trim()
+    || !Object.prototype.hasOwnProperty.call(check, 'appId')) return false;
+  const hasState = Object.prototype.hasOwnProperty.call(check, 'state');
+  const hasStatus = Object.prototype.hasOwnProperty.call(check, 'status');
+  const hasConclusion = Object.prototype.hasOwnProperty.call(check, 'conclusion');
+  if (hasState) {
+    return !hasStatus && !hasConclusion && check.appId === null
+      && typeof check.state === 'string' && Boolean(check.state.trim());
+  }
+  return hasStatus && hasConclusion && Number.isInteger(check.appId) && check.appId > 0
+    && typeof check.status === 'string' && Boolean(check.status.trim())
+    && (check.conclusion === null || typeof check.conclusion === 'string');
+}
+
+function normalizeRequiredCheck(check) {
+  if (!check || typeof check !== 'object' || typeof check.context !== 'string' || !check.context.trim()
+    || !Object.prototype.hasOwnProperty.call(check, 'appId')
+    || (check.appId !== null && (!Number.isInteger(check.appId) || check.appId <= 0))) return null;
+  return { context: check.context, appId: check.appId };
+}
+
+function matchesRequiredCheck(check, required) {
+  return checkName(check) === required.context
+    && (required.appId === null || check.appId === required.appId);
+}
+
+function isSafeOptionalCheck(check) {
+  if (Object.prototype.hasOwnProperty.call(check, 'state')) return isCheckGreen(check);
+  return String(check.status).toUpperCase() === 'COMPLETED'
+    && SAFE_OPTIONAL_CONCLUSIONS.has(String(check.conclusion || '').toUpperCase());
+}
+
 /**
- * `checks_green` — every CI check must be green per `isCheckGreen`. Optionally scoped:
- *   - bare string / no arg → ALL checks must be green (strict default).
- *   - { ignore: ["A","B"] } → the named checks are EXEMPT; every OTHER check
- *     must be green. `ignore: []` is identical to the bare form.
+ * `checks_green` — protected checks must be strict SUCCESS; optional check runs
+ * may also be terminal NEUTRAL or SKIPPED. Optionally scoped:
+ *   - bare string / no arg → protected checks strict, optional checks safely terminal.
+ *   - { ignore: ["A","B"] } → the named optional checks are EXEMPT;
+ *     `ignore: []` is identical to the bare form.
  *   - { only: ["A"] }       → ONLY the named checks must be green (present AND
- *     green per `isCheckGreen`); all others are ignored.
+ *     green per `isCheckGreen`); all optional others are ignored.
  * `ignore` + `only` together is malformed → fail-closed. Exact name match.
- * (`required_only` — scope to the branch-protection required set — is a
- * documented follow-up, not built here.)
+ * The protected required set is always enforced before optional scoping.
  */
 function checksGreen(ctx, arg) {
   let ignore = [];
@@ -168,14 +209,42 @@ function checksGreen(ctx, arg) {
   if (!Array.isArray(ctx.checks)) {
     return fail('check results are missing from the PR context (fail-closed).');
   }
+  if (!Array.isArray(ctx.requiredChecks)) {
+    return fail('required-check set is missing or malformed (fail-closed).');
+  }
+  if (ctx.checks.some((check) => !isCheckObservationWellFormed(check))) {
+    return fail('check results contain malformed observations (fail-closed).');
+  }
+
+  const required = ctx.requiredChecks.map(normalizeRequiredCheck);
+  if (required.some((check) => !check)) {
+    return fail('required-check set contains malformed entries (fail-closed).');
+  }
+  const requiredApps = new Map();
+  for (const check of required) {
+    if (!requiredApps.has(check.context)) requiredApps.set(check.context, new Set());
+    requiredApps.get(check.context).add(check.appId === null ? '*' : String(check.appId));
+  }
+  if ([...requiredApps.values()].some((apps) => apps.size > 1)) {
+    return fail('required-check set contains conflicting application identities (fail-closed).');
+  }
+
+  const requiredProblems = required.map((requiredCheck) => {
+    const matches = ctx.checks.filter((check) => matchesRequiredCheck(check, requiredCheck));
+    if (matches.length === 0) return `${requiredCheck.context} (missing)`;
+    if (matches.some((check) => !isCheckGreen(check))) return `${requiredCheck.context} (not successful)`;
+    return null;
+  }).filter(Boolean);
+  if (requiredProblems.length > 0) {
+    return fail(`protected required check(s) not green: ${requiredProblems.join(', ')}.`);
+  }
 
   if (only) {
     // Only the named checks matter — each must be PRESENT and green.
-    const byName = new Map(ctx.checks.map((c) => [checkName(c), c]));
     const problems = only.map((name) => {
-      const check = byName.get(name);
-      if (!check) return `${name} (missing)`;
-      if (!isCheckGreen(check)) return `${name} (${check.conclusion || 'not green'})`;
+      const matches = ctx.checks.filter((check) => checkName(check) === name);
+      if (matches.length === 0) return `${name} (missing)`;
+      if (matches.some((check) => !isCheckGreen(check))) return `${name} (not green)`;
       return null;
     }).filter(Boolean);
     if (problems.length > 0) return fail(`required check(s) not green: ${problems.join(', ')}.`);
@@ -184,7 +253,9 @@ function checksGreen(ctx, arg) {
 
   // Default / ignore: every check EXCEPT the exempt ones must be green.
   const exempt = new Set(ignore);
-  const notGreen = ctx.checks.filter((c) => !exempt.has(checkName(c)) && !isCheckGreen(c));
+  const notGreen = ctx.checks.filter((check) => !exempt.has(checkName(check))
+    && !required.some((requiredCheck) => matchesRequiredCheck(check, requiredCheck))
+    && !isSafeOptionalCheck(check));
   if (notGreen.length > 0) {
     const names = notGreen.map((c) => (c && c.name) || '?').join(', ');
     return fail(`${notGreen.length} check(s) not green: ${names}.`);
@@ -227,6 +298,52 @@ function notDraft(ctx) {
   return fail('draft status is unknown (fail-closed).');
 }
 
+/** Require the pure reducer's positive verdict to match the caller's immutable head lease. */
+function verdictClean(ctx) {
+  const verdict = object(readDataProperty(ctx, 'verdict').value);
+  if (!verdict) {
+    return fail('current-head verdict is missing or malformed (fail-closed).');
+  }
+  const repository = normalizeRepository(readDataProperty(ctx, 'repository').value);
+  const expectedRepository = normalizeRepository(readDataProperty(ctx, 'expectedRepository').value);
+  const prNumber = normalizePrNumber(readDataProperty(ctx, 'prNumber').value);
+  const expectedPrNumber = normalizePrNumber(readDataProperty(ctx, 'expectedPrNumber').value);
+  const head = normalizeSha(readDataProperty(ctx, 'headSha').value);
+  const expected = normalizeSha(readDataProperty(ctx, 'expectedHeadSha').value);
+  const base = normalizeSha(readDataProperty(ctx, 'baseSha').value);
+  const expectedBase = normalizeSha(readDataProperty(ctx, 'expectedBaseSha').value);
+  const verdictRepository = normalizeRepository(readDataProperty(verdict, 'repository').value);
+  const verdictPrNumber = normalizePrNumber(readDataProperty(verdict, 'prNumber').value);
+  const verdictHead = normalizeSha(readDataProperty(verdict, 'headSha').value);
+  const verdictBase = normalizeSha(readDataProperty(verdict, 'baseSha').value);
+  const verdictState = readDataProperty(verdict, 'state').value;
+  const verdictReasons = readArrayItems(readDataProperty(verdict, 'reasons').value);
+  if (!head || !expected || !base || !expectedBase || !verdictHead || !verdictBase) {
+    return fail('exact head lease, verdict head, or verdict base is missing or malformed (fail-closed).');
+  }
+  if (!repository || !expectedRepository || !prNumber || !expectedPrNumber
+    || !verdictRepository || !verdictPrNumber) {
+    return fail('repository or PR authority is missing or malformed (fail-closed).');
+  }
+  if (repository !== expectedRepository || verdictRepository !== repository
+    || prNumber !== expectedPrNumber || verdictPrNumber !== prNumber) {
+    return fail('current-head verdict does not match the exact repository and PR authority.');
+  }
+  if (head !== expected || verdictHead !== head) {
+    return fail('current-head verdict does not match the exact caller head lease.');
+  }
+  if (base !== expectedBase || verdictBase !== base) {
+    return fail('current-head verdict does not match the exact caller base lease.');
+  }
+  if (verdictState !== 'MERGE_READY') {
+    return fail(`current-head verdict is ${String(verdictState || 'INCOMPLETE')}, not MERGE_READY.`);
+  }
+  if (!verdictReasons || verdictReasons.length > 0) {
+    return fail('MERGE_READY verdict carries incomplete or contradictory reasons (fail-closed).');
+  }
+  return pass();
+}
+
 function minApprovals(ctx, arg) {
   const need = Number.parseInt(arg, 10);
   if (!Number.isFinite(need)) return fail('min_approvals requires a numeric argument, e.g. "min_approvals:2".');
@@ -310,6 +427,7 @@ function notWrapper(ctx, arg) {
 }
 
 const PREDICATES = {
+  verdict_clean: (ctx) => verdictClean(ctx),
   checks_green: (ctx, arg) => checksGreen(ctx, arg),
   threads_resolved: (ctx) => threadsResolved(ctx),
   not_behind: (ctx) => notBehind(ctx),