forgedock 1.2.0 → 1.4.0

package/packages/protocol/src/card.js

@@ -0,0 +1,114 @@
+/**
+ * FORGE Annotation Protocol v1.0 — CARD codec.
+ *
+ * Implements the Base64url machine-surface encoding used by the CARD reserved
+ * type (§4.2, forge#1727): `<!-- FORGE:CARD: v1 sha:<sha8hex> b64:<base64url> -->`.
+ *
+ * Design decision (2026-07-08): the Base64url alphabet [A-Za-z0-9_-] cannot
+ * contain '>', '<', or '!' — so `-->`, `--!>`, and `<!--` are structurally
+ * unrepresentable in the encoded payload, by construction. This sidesteps the
+ * escaping-related round-trip bugs that affected the plain field-value/inline
+ * form of other reserved types (forge#1637, forge#1638, forge#1662) — CARD
+ * payloads never need escaping in the first place.
+ *
+ * This module is the single production code path for CARD encode/decode: it
+ * is used by `cli.js` (the `emit --b64` / `parse --field` subcommands),
+ * `validate.js` (CARD integrity checking), and the conformance test suite.
+ *
+ * @license MIT
+ */
+
+import { createHash } from 'node:crypto';
+
+/**
+ * Produce canonical JSON: sorted keys (recursively), single line, UTF-8.
+ * This is the payload that gets Base64url-encoded in the CARD format.
+ *
+ * @param {*} obj
+ * @returns {string}
+ */
+export function canonicalJson(obj) {
+  return JSON.stringify(sortKeysDeep(obj));
+}
+
+function sortKeysDeep(val) {
+  if (Array.isArray(val)) return val.map(sortKeysDeep);
+  if (val !== null && typeof val === 'object') {
+    return Object.fromEntries(
+      Object.keys(val)
+        .sort()
+        .map(k => [k, sortKeysDeep(val[k])]),
+    );
+  }
+  return val;
+}
+
+/**
+ * Encode a UTF-8 string as Base64url (URL-safe alphabet, no padding).
+ *
+ * @param {string} str — UTF-8 string to encode
+ * @returns {string} Base64url-encoded string without padding
+ */
+export function toBase64url(str) {
+  return Buffer.from(str, 'utf8')
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=/g, '');
+}
+
+/**
+ * Encode a JS value into the CARD wire components: the sha8 integrity prefix
+ * (first 8 hex chars of SHA-256 over the canonical JSON payload) and the
+ * Base64url-encoded canonical payload.
+ *
+ * Composes the full inline value with `\`v1 sha:${sha8} b64:${b64url}\`` to
+ * build the complete `<!-- FORGE:CARD: v1 sha:<sha8> b64:<base64url> -->` tag.
+ *
+ * @param {*} payload — the JS value to encode (typically a plain object)
+ * @returns {{ sha8: string, b64url: string, inlineValue: string }}
+ */
+export function encodeCard(payload) {
+  const canonical = canonicalJson(payload);
+  const b64url = toBase64url(canonical);
+  const sha8 = createHash('sha256').update(canonical, 'utf8').digest('hex').slice(0, 8);
+  return { sha8, b64url, inlineValue: `v1 sha:${sha8} b64:${b64url}` };
+}
+
+/**
+ * Decode a CARD inline value of the form "v1 sha:<sha8hex> b64:<base64url>"
+ * and return the parsed JSON value, or null if the format is unrecognized,
+ * the Base64url payload fails to decode, the sha8 integrity prefix does not
+ * match, or the decoded payload is not valid JSON.
+ *
+ * @param {string} inlineValue — the parsed inlineValue from a CARD annotation
+ * @returns {*|null}
+ */
+export function decodeCardInlineValue(inlineValue) {
+  if (typeof inlineValue !== 'string') return null;
+
+  const m = inlineValue.match(/^v1\s+sha:([0-9a-f]{8})\s+b64:([A-Za-z0-9_-]+)$/);
+  if (!m) return null;
+  const [, sha8, b64url] = m;
+
+  // Restore standard Base64 padding and swap the URL-safe alphabet back.
+  const b64std = b64url.replace(/-/g, '+').replace(/_/g, '/');
+  const padded = b64std + '='.repeat((4 - (b64std.length % 4)) % 4);
+
+  let canonical;
+  try {
+    canonical = Buffer.from(padded, 'base64').toString('utf8');
+  } catch {
+    return null;
+  }
+
+  // Integrity check: first 8 hex chars of SHA-256 must match the prefix.
+  const expectedSha8 = createHash('sha256').update(canonical, 'utf8').digest('hex').slice(0, 8);
+  if (expectedSha8 !== sha8) return null;
+
+  try {
+    return JSON.parse(canonical);
+  } catch {
+    return null;
+  }
+}

package/packages/protocol/src/cli.js

@@ -42,10 +42,10 @@
 
 import { readFileSync, readdirSync } from 'node:fs';
 import { resolve, extname } from 'node:path';
-import { createHash } from 'node:crypto';
 import { parse } from './parse.js';
 import { validate } from './validate.js';
 import { emit } from './emit.js';
+import { encodeCard, decodeCardInlineValue } from './card.js';
 
 // ---------------------------------------------------------------------------
 // Argv routing
@@ -114,16 +114,15 @@ function cmdEmit(argv) {
     // Payload: canonical JSON (sorted keys, single line, UTF-8).
     // The Base64url alphabet [A-Za-z0-9_-] cannot contain '>', '<', or '!' —
     // so -->, --!>, and <!-- are structurally unrepresentable by construction.
+    // Codec lives in ./card.js (shared with validate.js and the test suite).
     const payload = Object.keys(fields).length > 0 ? { ...fields } : {};
     if (type) payload.type = type.toUpperCase();
-    const canonical = canonicalJson(payload);
-    const b64url = toBase64url(canonical);
-    const sha8 = createHash('sha256').update(canonical, 'utf8').digest('hex').slice(0, 8);
+    const { inlineValue } = encodeCard(payload);
     // The colon-separator form "<!-- FORGE:CARD: v1 sha:X b64:Y -->" matches
     // OPENING_TAG_RE so parse() can extract the inline value "v1 sha:X b64:Y".
     // This keeps the canonical FORGE inline-value syntax (§3.4) while adding
     // the sha8 integrity prefix and Base64url payload from the design decision.
-    process.stdout.write(`<!-- FORGE:CARD: v1 sha:${sha8} b64:${b64url} -->\n`);
+    process.stdout.write(`<!-- FORGE:CARD: ${inlineValue} -->\n`);
     return;
   }
 
@@ -351,75 +350,3 @@ function die(msg) {
   process.stderr.write(`forge-protocol-cli: ${msg}\n`);
   process.exit(1);
 }
-
-/**
- * Produce canonical JSON: sorted keys, single line, UTF-8.
- * This is the payload that gets Base64url-encoded in the CARD format.
- */
-function canonicalJson(obj) {
-  return JSON.stringify(sortKeysDeep(obj));
-}
-
-function sortKeysDeep(val) {
-  if (Array.isArray(val)) return val.map(sortKeysDeep);
-  if (val !== null && typeof val === 'object') {
-    return Object.fromEntries(
-      Object.keys(val)
-        .sort()
-        .map(k => [k, sortKeysDeep(val[k])]),
-    );
-  }
-  return val;
-}
-
-/**
- * Encode a UTF-8 string as Base64url (URL-safe alphabet, no padding).
- * The Base64url alphabet [A-Za-z0-9_-] cannot contain '>', '<', or '!' —
- * so -->, --!>, and <!-- are structurally unrepresentable by construction
- * (design decision 2026-07-08: encoding beats escaping).
- *
- * @param {string} str — UTF-8 string to encode
- * @returns {string} Base64url-encoded string without padding
- */
-function toBase64url(str) {
-  return Buffer.from(str, 'utf8')
-    .toString('base64')
-    .replace(/\+/g, '-')
-    .replace(/\//g, '_')
-    .replace(/=/g, '');
-}
-
-/**
- * Decode a CARD inline value of the form "v1 sha:<sha8hex> b64:<base64url>"
- * and return the parsed JSON object, or null if the format is unrecognized.
- * Verifies the sha8 integrity prefix; returns null on corruption or tampering.
- *
- * @param {string} inlineValue — the parsed inlineValue from a CARD annotation
- * @returns {object|null}
- */
-function decodeCardInlineValue(inlineValue) {
-  const m = inlineValue.match(/^v1\s+sha:([0-9a-f]{8})\s+b64:([A-Za-z0-9_-]+)$/);
-  if (!m) return null;
-  const [, sha8, b64url] = m;
-
-  // Restore standard Base64 padding and swap the URL-safe alphabet back.
-  const b64std = b64url.replace(/-/g, '+').replace(/_/g, '/');
-  const padded = b64std + '='.repeat((4 - (b64std.length % 4)) % 4);
-
-  let canonical;
-  try {
-    canonical = Buffer.from(padded, 'base64').toString('utf8');
-  } catch {
-    return null;
-  }
-
-  // Integrity check: first 8 hex chars of SHA-256 must match the prefix.
-  const expectedSha8 = createHash('sha256').update(canonical, 'utf8').digest('hex').slice(0, 8);
-  if (expectedSha8 !== sha8) return null;
-
-  try {
-    return JSON.parse(canonical);
-  } catch {
-    return null;
-  }
-}

package/packages/protocol/src/emit.js

@@ -12,6 +12,7 @@
  */
 
 import { RESERVED_TYPES, RESERVED_TYPE_NAMES } from './types.js';
+import { escapeHtmlCommentDelimiters } from './html-comment-escape.js';
 
 // A folded field/inline value that is itself (whole, trimmed) shaped like a FORGE
 // opening tag or a generic sentinel line has no legitimate reason to look that way —
@@ -40,7 +41,9 @@ const NEWLINE_RE = /\r\n|\r|\n/g;
  *      subsequent lines including the completion sentinel, and treats a literal
  *      `-->` as ending the enclosing comment early, leaking the remainder as
  *      visible rendered text. Both directions of the delimiter pair must be
- *      escaped. (forge#1594, forge#1638)
+ *      escaped. (forge#1594, forge#1638) Delegated to the shared
+ *      `escapeHtmlCommentDelimiters()` helper (forge#2225) so this scheme has a
+ *      single implementation shared with `bin/engine/state.mjs`.
  *
  * As defense in depth, if a value still folds down to a line that is itself a
  * bare FORGE tag/sentinel shape, emit() rejects it outright rather than silently
@@ -56,16 +59,7 @@ function sanitizeFieldValue(rawValue) {
       `emit(): field value resolves to a bare FORGE tag/sentinel line, which is not permitted: ${JSON.stringify(rawValue)}`,
     );
   }
-  // Escape the HTML comment opener ("<!--") so a value cannot start a new
-  // unterminated HTML comment in GitHub's renderer, which would visually swallow
-  // subsequent lines — the same rendering-leak the closer escaping below prevents
-  // from the opposite direction. (forge#1638)
-  const withOpenerEscaped = folded.replace(/<!--/g, '&lt;!--');
-  // Escape both HTML comment-close forms ("-->" and "--!>") — only replacing the
-  // literal character sequence (not just documenting the risk) prevents the
-  // enclosing comment from terminating early. (forge#1594; noted but never fixed
-  // for the FORGE:STATE codec in bin/engine/state.mjs — see issue investigation)
-  return withOpenerEscaped.replace(/--(!)?>/g, (_, bang) => `--${bang || ''}&gt;`);
+  return escapeHtmlCommentDelimiters(folded);
 }
 
 /**

package/packages/protocol/src/html-comment-escape.js

@@ -0,0 +1,68 @@
+/**
+ * Shared HTML-comment-delimiter escape/unescape pair for the FORGE annotation
+ * wire format.
+ *
+ * This scheme is used by two independent callers that must agree byte-for-byte:
+ *   - `packages/protocol/src/emit.js` / `parse.js` (per-field-value escaping)
+ *   - `bin/engine/state.mjs` (whole-JSON-payload escaping for the FORGE:STATE
+ *     compact-index block)
+ *
+ * Extracting it here removes the drift vector between those two call sites —
+ * they previously hand-duplicated this exact regex chain, kept in sync only by
+ * cross-referencing code comments, and had already drifted once (forge#1638's
+ * fix was applied to `emit.js` before `state.mjs` caught up in forge#2119).
+ *
+ * @license MIT
+ */
+
+/**
+ * Escape the three HTML comment delimiter forms so a payload/value can never
+ * open or close an HTML comment in GitHub's renderer:
+ *   - `<!--`         the comment opener — an unescaped opener would start a new
+ *     (nested-looking) comment, visually swallowing subsequent content.
+ *   - `-->` and `--!>`  the two comment-close forms browsers/HTML parsers
+ *     honour. An unescaped closer could end the enclosing comment early,
+ *     leaking the remainder as visible rendered text (CodeQL js/bad-tag-filter).
+ *
+ * The `&` escape MUST run first, before either delimiter-escape pass. Without
+ * it, a value that already contains literal entity-like text (e.g. `<!--&gt;`
+ * or `&lt;!--`) collides with the encoded form of an unrelated real delimiter —
+ * the encoder would not be injective, and the collision is unrecoverable on
+ * decode (forge#2137). Escaping `&` first guarantees every `&lt;!--`/`--&gt;`/
+ * `--!&gt;` sequence in the output was produced by *this* pass, never by
+ * pre-existing entity text (which is now doubly-escaped, e.g.
+ * `&` -> `&amp;`, left untouched by the delimiter passes that only match the
+ * literal `<!--`/`--`+`>` character sequences).
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+export function escapeHtmlCommentDelimiters(value) {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/<!--/g, '&lt;!--')
+    .replace(/--(!)?>/g, (_, bang) => `--${bang || ''}&gt;`);
+}
+
+/**
+ * Inverse of {@link escapeHtmlCommentDelimiters}. Restores `--&gt;`, `--!&gt;`,
+ * `&lt;!--`, then `&amp;` — in that order.
+ *
+ * Unescape order matters: the closer forms are restored first (most-specific
+ * `--!&gt;` before `--&gt;`) so a dangling `!` is never left behind, then the
+ * opener is restored. The `&amp;` -> `&` unescape MUST run LAST (mirroring the
+ * encode side running it FIRST) so it never touches the `&` that is part of a
+ * just-restored `<!--`/`-->`/`--!>` sequence (forge#2137; forge#1662 — parse()
+ * previously failed to apply the exact inverse of emit()'s escape, corrupting
+ * round-trips).
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+export function unescapeHtmlCommentDelimiters(raw) {
+  return raw
+    .replace(/--!&gt;/g, '--!>')
+    .replace(/--&gt;/g, '-->')
+    .replace(/&lt;!--/g, '<!--')
+    .replace(/&amp;/g, '&');
+}

package/packages/protocol/src/index.js

@@ -1,7 +1,7 @@
 /**
  * @forgedock/protocol — FORGE Annotation Protocol v1.0 reference implementation.
  *
- * Provides parse, validate, and emit for all 13 reserved annotation types
+ * Provides parse, validate, and emit for all reserved annotation types
  * defined in the FORGE Annotation Protocol specification (CC-BY-4.0).
  *
  * @example
@@ -29,6 +29,8 @@ export { parse } from './parse.js';
 export { validate } from './validate.js';
 export { emit, emitPartial, isKnownType } from './emit.js';
 export { RESERVED_TYPES, RESERVED_TYPE_NAMES, Category, SentinelState } from './types.js';
+export { canonicalJson, toBase64url, encodeCard, decodeCardInlineValue } from './card.js';
+export { PHASE_IDS, PHASE_MARKERS } from './phases.js';
 
 /**
  * @typedef {Object} ParsedAnnotation

package/packages/protocol/src/parse.js

@@ -17,6 +17,7 @@
  */
 
 import { RESERVED_TYPES, RESERVED_TYPE_NAMES, SentinelState } from './types.js';
+import { unescapeHtmlCommentDelimiters } from './html-comment-escape.js';
 
 // Matches: <!-- FORGE:TYPE --> or <!-- FORGE:TYPE: value -->
 // Anchored to require the tag to be the ENTIRE (trimmed) line — a FORGE-tag-shaped
@@ -101,26 +102,33 @@ function escapeRegExp(str) {
 /**
  * Reverse the HTML entity escapes applied by emit()'s sanitizeFieldValue().
  *
- * emit() escapes three HTML comment delimiter sequences to protect GitHub's
- * renderer from comment injection:
+ * emit() escapes "&" first, then three HTML comment delimiter sequences, to
+ * protect GitHub's renderer from comment injection AND to keep the encoding
+ * injective (reversible for every input, not just delimiter-free ones):
+ *   0. `&`     → `&amp;`      (forge#2137 — must run first on encode)
  *   1. `<!--`  → `&lt;!--`   (forge#1638)
  *   2. `--!>`  → `--!&gt;`   (forge#1594)
  *   3. `-->`   → `--&gt;`    (forge#1594)
  *
- * parse() must apply the inverse so that round-tripping through emit → parse
- * is lossless. Unescape order: `--!&gt;` before `--&gt;` (most-specific first)
- * to avoid the `!` being left dangling by an overly-greedy `--&gt;` pass.
- * The `&lt;!--` unescape is independent and can run in any relative order.
- * (forge#1662)
+ * parse() must apply the exact inverse, in reverse order, so that
+ * round-tripping through emit → parse is lossless. Unescape order:
+ * `--!&gt;` before `--&gt;` (most-specific first) to avoid the `!` being left
+ * dangling by an overly-greedy `--&gt;` pass; `&lt;!--` can run in any order
+ * relative to those two. The `&amp;` → `&` unescape MUST run LAST — doing it
+ * first (or interleaved) would corrupt the `&` that is part of a freshly
+ * restored `<!--`/`-->`/`--!>` sequence. Running "&" first on encode and last
+ * on decode is what makes the scheme injective: any pre-existing entity-like
+ * text in the original value (e.g. `&lt;!--` or `<!--&gt;`) is doubly-escaped
+ * at encode time and can never collide with the single-escaped form produced
+ * by a real delimiter (forge#2137; forge#1662). Delegated to the shared
+ * `unescapeHtmlCommentDelimiters()` helper (forge#2225) so this scheme has a
+ * single implementation shared with `bin/engine/state.mjs`.
  *
  * @param {string} raw
  * @returns {string}
  */
 function unescapeFieldValue(raw) {
-  return raw
-    .replace(/--!&gt;/g, '--!>')
-    .replace(/--&gt;/g, '-->')
-    .replace(/&lt;!--/g, '<!--');
+  return unescapeHtmlCommentDelimiters(raw);
 }
 
 /**

package/packages/protocol/src/phases.js

@@ -0,0 +1,105 @@
+/**
+ * Canonical FORGE pipeline phase table — single source of truth for phase ids
+ * (in dispatch order) and the exact marker/label strings that indicate each
+ * phase has committed.
+ *
+ * Consumers: `bin/engine/phases.mjs` (the authoritative engine gate) and
+ * `bin/hooks/interactive-engine.mjs` (the interactive-session SubagentStop
+ * hook) both import this module instead of hand-declaring their own copies
+ * of the marker strings. Before this module existed, the two files carried
+ * independent literal copies of the same strings and drifted out of sync at
+ * least twice (forge#1669 established the strict `:COMPLETE` gate for
+ * `context`/`architect`; forge#2375/PR#2395 then had to hand-patch the hook's
+ * copy back into agreement with the engine's). See forge#2378.
+ *
+ * `completionMarker` values are sourced from `RESERVED_TYPES[*].completionSentinel`
+ * wherever that reserved annotation type exists (INVESTIGATOR, CONTEXT,
+ * ARCHITECT, BUILDER) — so the reserved-annotation registry in `types.js` and
+ * this phase registry cannot drift apart for those four phases; there is
+ * exactly one literal declaration of each of those marker strings in the
+ * entire codebase, in `types.js`.
+ *
+ * `review` and `close` have no corresponding `RESERVED_TYPES` entry with a
+ * matching sentinel today (`REVIEWER` has no `completionSentinel` defined in
+ * spec §4.1; `close` is gated on a GitHub *label*, not a comment annotation),
+ * so those two are declared directly in this file — still single-sourced
+ * across the two consumers, just not additionally derived from `types.js`.
+ *
+ * @license MIT
+ */
+
+import { RESERVED_TYPES } from './types.js';
+
+/** Phase ids, in canonical dispatch order (mirrors `commands/work-on.md`'s
+ * "Universal Phase Dispatcher" table and `bin/engine/phases.mjs`'s `PHASES`
+ * array).
+ *
+ * `decompose` and `remediate` (forge#2379) are branch phases, not part of the
+ * six-phase linear happy path — `decompose` is reached only when `investigate`
+ * signals `DECOMPOSE:YES`, and `remediate` only when `review` escalates to
+ * `needs-human`. They are still declared here, in the exact same array
+ * position `bin/engine/phases.mjs`'s `PHASES` array declares them, because
+ * `scripts/check-phase-registry-drift.mjs` requires the two lists to match
+ * index-for-index — see that file's own doc comment. */
+export const PHASE_IDS = ['investigate', 'decompose', 'context', 'architect', 'build', 'review', 'remediate', 'close'];
+
+/**
+ * @typedef {Object} PhaseMarkerEntry
+ * @property {string} [completionMarker] - marker/sentinel string (or label, for `close`)
+ *   whose presence means this phase has committed.
+ * @property {string} [invalidMarker] - (investigate only) marks the issue INVALID.
+ * @property {string} [decomposedMarker] - (investigate only) marks the issue DECOMPOSED.
+ * @property {string} [partialMarker] - sentinel for an interrupted/partial annotation.
+ * @property {string} [presenceMarker] - bare annotation-opener substring, used only by
+ *   phases whose completion is non-critical (see `context` below) — presence alone
+ *   (without `:COMPLETE`) is enough to report a soft/visible skip rather than a hard fail.
+ * @property {string} [completionLabel] - a GitHub issue *label* (not a comment marker)
+ *   whose presence means this phase has committed. Only `close` uses this form.
+ */
+
+/** @type {Object.<string, PhaseMarkerEntry>} */
+export const PHASE_MARKERS = {
+  investigate: {
+    completionMarker: RESERVED_TYPES.INVESTIGATOR.completionSentinel, // 'INVESTIGATION:COMPLETE'
+    invalidMarker: 'INVESTIGATION:INVALID',
+    decomposedMarker: 'DECOMPOSE:YES',
+  },
+  // forge#2379: `decompose` actually runs work-on/decompose (sub-issue
+  // fan-out) once `investigate` hands off on `DECOMPOSE:YES` — see
+  // bin/engine/phases.mjs's `decompose` phase entry for the handoff mechanics.
+  decompose: {
+    completionMarker: RESERVED_TYPES.DECOMPOSED.completionSentinel, // 'FORGE:DECOMPOSED:COMPLETE'
+  },
+  context: {
+    completionMarker: RESERVED_TYPES.CONTEXT.completionSentinel, // 'FORGE:CONTEXT:COMPLETE'
+    partialMarker: RESERVED_TYPES.CONTEXT.partialSentinel, // 'FORGE:CONTEXT:PARTIAL'
+    // Bare presence marker: context is documented as non-critical (spec §7) — a
+    // missing completion marker is a visible skip, not a hard fail. Only
+    // bin/engine/phases.mjs's `context.detectOutcome` uses this bare form;
+    // `context.reconcile` (and everything in interactive-engine.mjs) uses the
+    // strict `completionMarker` above. Do not collapse these two fields.
+    presenceMarker: `FORGE:${RESERVED_TYPES.CONTEXT.type}`, // 'FORGE:CONTEXT'
+  },
+  architect: {
+    completionMarker: RESERVED_TYPES.ARCHITECT.completionSentinel, // 'FORGE:ARCHITECT:COMPLETE'
+    partialMarker: RESERVED_TYPES.ARCHITECT.partialSentinel, // 'FORGE:ARCHITECT:PARTIAL'
+  },
+  build: {
+    completionMarker: RESERVED_TYPES.BUILDER.completionSentinel, // 'FORGE:BUILDER:COMPLETE'
+  },
+  review: {
+    // No RESERVED_TYPES entry defines this sentinel (REVIEWER has no
+    // completionSentinel in spec §4.1) — declared directly here.
+    completionMarker: 'FORGE:REVIEWER:MERGED',
+  },
+  // forge#2379: `remediate` re-drives a needs-human PR (commands/work-on/remediate.md).
+  // Posted to BOTH the PR and the linked issue (Phase M8) — bin/engine/phases.mjs's
+  // `remediate` phase reads it off the issue, consistent with every other phase here.
+  remediate: {
+    completionMarker: RESERVED_TYPES.REMEDIATION.completionSentinel, // 'FORGE:REMEDIATION:COMPLETE'
+  },
+  close: {
+    // A GitHub label, not a comment marker — see `completionLabel` above.
+    completionLabel: 'workflow:merged',
+  },
+};

package/packages/protocol/src/types.js

@@ -18,7 +18,7 @@ export const SentinelState = {
 };
 
 /**
- * All 16 reserved annotation types from spec §4.
+ * All reserved annotation types from spec §4.
  * Spec ref: §4.1 lifecycle, §4.2 cross-artifact, §4.3 control/error markers.
  * Added CLAIM and CLAIM_RELEASED in forge#1736 — claims board for claim-level parallelism.
  * Added AUTOPILOT_CYCLE in forge#1753 — durable cycle state for /autopilot.
@@ -86,6 +86,23 @@ export const RESERVED_TYPES = {
     requiredFields: ['Verdict'],
     verdictValues: ['APPROVED', 'CHANGES_REQUESTED', 'COMMENTED'],
   },
+  /**
+   * REMEDIATION — paper trail for a needs-human PR re-driven by
+   * commands/work-on/remediate.md. Posted to BOTH the PR and the linked
+   * issue (Phase M8) once the re-gate outcome (AUTO-LANDED /
+   * HELD-AWAITING-MERGE / RE-ESCALATED / UNFIXABLE) is known. Added in
+   * forge#2379 to single-source the completion sentinel that
+   * bin/engine/phases.mjs's `remediate` phase gates on. <!-- Added: forge#2379 -->
+   */
+  REMEDIATION: {
+    type: 'REMEDIATION',
+    category: Category.LIFECYCLE,
+    completionSentinel: 'FORGE:REMEDIATION:COMPLETE',
+    partialSentinel: null,
+    inlineValue: false,
+    requiredFields: [],
+    reGateOutcomeValues: ['AUTO-LANDED', 'HELD-AWAITING-MERGE', 'RE-ESCALATED', 'UNFIXABLE'],
+  },
   TRAJECTORY: {
     type: 'TRAJECTORY',
     category: Category.LIFECYCLE,

package/packages/protocol/src/validate.js

@@ -8,12 +8,14 @@
  *   - Required field presence (§4.1 per-type field tables)
  *   - Required field enum values (Verdict, Confidence, Severity, Task Type)
  *   - Inline-value non-empty (§3.4)
+ *   - CARD inline-value decodability + sha8 integrity (§4.2 — see card.js)
  *   - Partial sentinel marking (§3.3) — generates a warning, not an error
  *
  * @license MIT
  */
 
 import { RESERVED_TYPES, SentinelState } from './types.js';
+import { decodeCardInlineValue } from './card.js';
 
 /**
  * Validate a parsed annotation against the spec.
@@ -46,6 +48,15 @@ export function validate(annotation) {
   if (typeDef.inlineValue) {
     if (inlineValue === null || inlineValue === '') {
       errors.push(`Inline-value annotation "${type}" must carry a non-empty value (§3.4)`);
+    } else if (type === 'CARD') {
+      // CARD-specific (§4.2): the inline value must decode via the Base64url
+      // codec and pass its sha8 integrity check. A malformed encoding or a
+      // tampered/corrupted payload must not be treated as a valid annotation.
+      if (decodeCardInlineValue(inlineValue) === null) {
+        errors.push(
+          `Inline-value "CARD" annotation failed to decode or failed its sha8 integrity check (§4.2)`,
+        );
+      }
     }
     return { valid: errors.length === 0, errors, warnings };
   }