@remogram/core 0.1.0-beta.4 → 0.1.0-beta.5

package/auth-classes.js

@@ -18,6 +18,12 @@ export const API_PROVIDER_COMMAND_AUTH = {
   merge_plan: AUTH_CLASS.TOKEN_REQUIRED,
   sync_plan: AUTH_CLASS.GIT_ONLY,
   cr_open: AUTH_CLASS.TOKEN_REQUIRED,
+  status_set: AUTH_CLASS.TOKEN_REQUIRED,
+  whoami: AUTH_CLASS.TOKEN_REQUIRED,
+  branch_protection: AUTH_CLASS.TOKEN_REQUIRED,
+  cr_files: AUTH_CLASS.TOKEN_REQUIRED,
+  cr_comments: AUTH_CLASS.TOKEN_REQUIRED,
+  forge_changes: AUTH_CLASS.TOKEN_REQUIRED,
 };
 
 export function commandCapability(name, { implemented = true } = {}) {
@@ -28,9 +34,22 @@ export function commandCapability(name, { implemented = true } = {}) {
   return { name, implemented, auth_class };
 }
 
-export function apiProviderCommands({ writeCommandsImplemented = false } = {}) {
+export function apiProviderCommands({
+  writeCommandsImplemented = false,
+  statusSetImplemented = false,
+  branchProtectionImplemented = false,
+  crFilesImplemented = false,
+  crCommentsImplemented = false,
+  forgeChangesImplemented = false,
+} = {}) {
   return Object.keys(API_PROVIDER_COMMAND_AUTH).map((name) => {
-    const implemented = name === 'cr_open' ? writeCommandsImplemented : true;
+    let implemented = true;
+    if (name === 'cr_open') implemented = writeCommandsImplemented;
+    if (name === 'status_set') implemented = statusSetImplemented;
+    if (name === 'branch_protection') implemented = branchProtectionImplemented;
+    if (name === 'cr_files') implemented = crFilesImplemented;
+    if (name === 'cr_comments') implemented = crCommentsImplemented;
+    if (name === 'forge_changes') implemented = forgeChangesImplemented;
     return commandCapability(name, { implemented });
   });
 }

package/branch-protection.js

@@ -0,0 +1,155 @@
+import { sanitizeField } from './caps.js';
+
+export const MAX_BRANCH_PROTECTION_STATUS_CONTEXTS = 64;
+export const MAX_BRANCH_PROTECTION_RULES = 32;
+
+/** Gitea exposes required_approvals on branch protection; omit when unavailable. */
+export function unimplementedApprovalsRequiredSignal() {
+  return { implemented: false, count: null };
+}
+
+function sanitizeStringList(values, maxItems) {
+  if (!Array.isArray(values)) return [];
+  const out = [];
+  for (const value of values) {
+    if (out.length >= maxItems) break;
+    const sanitized = sanitizeField(value);
+    if (sanitized) out.push(sanitized);
+  }
+  return out;
+}
+
+function normalizeApprovalsRequired(signal) {
+  if (signal == null || typeof signal !== 'object') {
+    return unimplementedApprovalsRequiredSignal();
+  }
+  if (signal.implemented === false) {
+    return { implemented: false, count: null };
+  }
+  if (signal.implemented === true) {
+    if (signal.count == null) {
+      return { implemented: true, count: null };
+    }
+    const count = Number(signal.count);
+    if (!Number.isFinite(count) || count < 0) {
+      return { implemented: true, count: null };
+    }
+    return { implemented: true, count: Math.floor(count) };
+  }
+  return unimplementedApprovalsRequiredSignal();
+}
+
+export function buildBranchProtectionBody({
+  branch_ref,
+  required_status_contexts,
+  protected_branch_rules,
+  approvals_required,
+}) {
+  const rules = (Array.isArray(protected_branch_rules) ? protected_branch_rules : [])
+    .slice(0, MAX_BRANCH_PROTECTION_RULES)
+    .map((rule) => {
+      const name =
+        rule != null && typeof rule === 'object'
+          ? sanitizeField(rule.name)
+          : sanitizeField(rule);
+      return name ? { name } : null;
+    })
+    .filter(Boolean);
+
+  return {
+    branch_ref: sanitizeField(branch_ref),
+    required_status_contexts: sanitizeStringList(
+      required_status_contexts,
+      MAX_BRANCH_PROTECTION_STATUS_CONTEXTS,
+    ),
+    protected_branch_rules: rules,
+    approvals_required: normalizeApprovalsRequired(approvals_required),
+  };
+}
+
+export function buildBranchProtectionFromGitLabProtection(
+  branchRef,
+  { protectedBranch = null, approvalRules = [] } = {},
+) {
+  if (protectedBranch == null) {
+    return buildBranchProtectionBody({
+      branch_ref: branchRef,
+      required_status_contexts: [],
+      protected_branch_rules: [],
+      approvals_required: unimplementedApprovalsRequiredSignal(),
+    });
+  }
+  const ruleName = sanitizeField(protectedBranch.name ?? branchRef);
+  let approvals_required = unimplementedApprovalsRequiredSignal();
+  if (Array.isArray(approvalRules) && approvalRules.length > 0) {
+    const counts = approvalRules
+      .map((rule) => Number(rule.approvals_required))
+      .filter((count) => Number.isFinite(count) && count >= 0);
+    if (counts.length > 0) {
+      approvals_required = { implemented: true, count: Math.max(...counts) };
+    }
+  }
+  return buildBranchProtectionBody({
+    branch_ref: branchRef,
+    required_status_contexts: [],
+    protected_branch_rules: ruleName ? [{ name: ruleName }] : [],
+    approvals_required,
+  });
+}
+
+export function buildBranchProtectionFromGitHubProtection(branchRef, protectionPayload) {
+  if (protectionPayload == null) {
+    return buildBranchProtectionBody({
+      branch_ref: branchRef,
+      required_status_contexts: [],
+      protected_branch_rules: [],
+      approvals_required: unimplementedApprovalsRequiredSignal(),
+    });
+  }
+  const payload =
+    protectionPayload != null && typeof protectionPayload === 'object' ? protectionPayload : {};
+  const required_status_contexts = sanitizeStringList(
+    payload.required_status_checks?.contexts,
+    MAX_BRANCH_PROTECTION_STATUS_CONTEXTS,
+  );
+  let approvals_required = unimplementedApprovalsRequiredSignal();
+  const reviews = payload.required_pull_request_reviews;
+  if (reviews != null && typeof reviews === 'object' && 'required_approving_review_count' in reviews) {
+    const count = Number(reviews.required_approving_review_count);
+    if (Number.isFinite(count) && count >= 0) {
+      approvals_required = { implemented: true, count: Math.floor(count) };
+    }
+  }
+  const ruleName = sanitizeField(branchRef);
+  return buildBranchProtectionBody({
+    branch_ref: branchRef,
+    required_status_contexts,
+    protected_branch_rules: ruleName ? [{ name: ruleName }] : [],
+    approvals_required,
+  });
+}
+
+export function buildBranchProtectionFromGiteaProtection(branchRef, protectionPayload) {
+  const payload =
+    protectionPayload != null && typeof protectionPayload === 'object' ? protectionPayload : {};
+  const ruleName = sanitizeField(payload.branch_name ?? payload.rule_name ?? branchRef);
+  const required_status_contexts =
+    payload.enable_status_check === false
+      ? []
+      : sanitizeStringList(payload.status_check_contexts, MAX_BRANCH_PROTECTION_STATUS_CONTEXTS);
+
+  let approvals_required = unimplementedApprovalsRequiredSignal();
+  if ('required_approvals' in payload) {
+    const count = Number(payload.required_approvals);
+    if (Number.isFinite(count) && count >= 0) {
+      approvals_required = { implemented: true, count: Math.floor(count) };
+    }
+  }
+
+  return buildBranchProtectionBody({
+    branch_ref: branchRef,
+    required_status_contexts,
+    protected_branch_rules: ruleName ? [{ name: ruleName }] : [],
+    approvals_required,
+  });
+}

package/caps.js

@@ -64,6 +64,17 @@ export function idempotencyScanCapabilityFacts() {
   };
 }
 
+/** Idempotency scan facts for status set (commit-status list pagination). */
+export function statusSetIdempotencyScanCapabilityFacts() {
+  return {
+    idempotency_scan: {
+      max_pages: MAX_OPEN_PULL_IDEMPOTENCY_PAGES,
+      page_size: DEFAULT_CHECK_STATUS_PAGE_SIZE,
+      ingest_backoff: 'halve_until_fit',
+    },
+  };
+}
+
 /** Structured open-pull list pagination facts for provider capabilities (cr inventory). */
 export function openPullListCapabilityFacts({
   totalCountSource = null,
@@ -120,6 +131,8 @@ function redactSecretPatterns(text) {
     .replace(/Bearer\s+\S+/gi, 'Bearer [REDACTED]')
     .replace(/\bghp_[A-Za-z0-9]+\b/g, '[REDACTED]')
     .replace(/\bgho_[A-Za-z0-9]+\b/g, '[REDACTED]')
+    .replace(/\bghs_[A-Za-z0-9._-]{36,}/g, '[REDACTED]')
+    .replace(/\bghs_[A-Za-z0-9_-]+\b/g, '[REDACTED]')
     .replace(/\bglpat-[A-Za-z0-9_-]+\b/g, '[REDACTED]')
     .replace(/\b(GITHUB_TOKEN|GH_TOKEN|GITLAB_TOKEN|GITEA_TOKEN)\b/gi, '[REDACTED]');
 }

package/contracts/envelope.js

@@ -14,6 +14,12 @@ export const PACKET_TYPES = {
   PROVIDER_DOCTOR: 'provider_doctor',
   FORGE_ERROR: 'forge_error',
   CHANGE_REQUEST_OPENED: 'change_request_opened',
+  COMMIT_STATUS_SET: 'commit_status_set',
+  PROVIDER_IDENTITY: 'provider_identity',
+  BRANCH_PROTECTION: 'branch_protection',
+  CR_FILES: 'cr_files',
+  CR_COMMENTS: 'cr_comments',
+  FORGE_CHANGES: 'forge_changes',
 };
 
 export const FORBIDDEN_PACKET_KEYS = new Set([

package/contracts/observer-fact-inventory.js

@@ -18,6 +18,11 @@ export const OBSERVER_REMOGRAM_COMMANDS = Object.freeze([
   { command: 'sync plan', mcp_tool: 'sync_plan', read_only: true, observer_proto: false },
   { command: 'provider capabilities', mcp_tool: 'provider_capabilities', read_only: true, observer_proto: false },
   { command: 'doctor', mcp_tool: 'doctor', read_only: true, observer_proto: false },
+  { command: 'whoami', mcp_tool: 'whoami', read_only: true, observer_proto: false },
+  { command: 'branch protection', mcp_tool: 'branch_protection', read_only: true, observer_proto: false },
+  { command: 'cr files', mcp_tool: 'cr_files', read_only: true, observer_proto: false },
+  { command: 'cr comments', mcp_tool: 'cr_comments', read_only: true, observer_proto: false },
+  { command: 'forge changes', mcp_tool: 'forge_changes', read_only: true, observer_proto: false },
 ]);
 
 /** Fact inventory packet types for semantic-diff / branch-workcycle composition. */

package/contracts/semantic-diff-facts.js

@@ -20,10 +20,15 @@ export const V1_READ_PLAN_COMMANDS = Object.freeze([
   'sync plan',
   'provider capabilities',
   'doctor',
+  'whoami',
+  'branch protection',
+  'cr files',
+  'cr comments',
+  'forge changes',
 ]);
 
-/** v1 write surface (Gitea cr open only in first slice). */
-export const V1_WRITE_COMMANDS = Object.freeze(['cr open']);
+/** v1 write surface (Gitea cr open and status set in first slices). */
+export const V1_WRITE_COMMANDS = Object.freeze(['cr open', 'status set']);
 
 /**
  * Planned fact-inventory packet types (not emitted until wave 2+ commands ship).
@@ -58,12 +63,16 @@ export const TRUSTED_NORMALIZED_BODY_FIELDS = Object.freeze({
   truncated: true,
   list_truncated: true,
   checks_truncated: true,
+  paths_truncated: true,
+  comments_truncated: true,
+  events_truncated: true,
   slice_sort: true,
   entry_count: true,
   mergeability_confidence: true,
   write_support: true,
   diverged: true,
   auth_present: true,
+  can_write: true,
   reused_existing: true,
   idempotency_scan: true,
 });
@@ -81,6 +90,16 @@ export const FORGE_SOURCED_STRING_LEAVES = Object.freeze({
   sync_plan: ['remote', 'local_sha', 'remote_sha', 'blockers[].message'],
   ref_inventory: ['refs[].name', 'refs[].sha', 'default_ref'],
   change_request_opened: ['url', 'title', 'head', 'base'],
+  commit_status_set: ['sha', 'context', 'description', 'target_url'],
+  provider_identity: ['login'],
+  branch_protection: [
+    'branch_ref',
+    'required_status_contexts[]',
+    'protected_branch_rules[].name',
+  ],
+  cr_files: ['changed_paths[]'],
+  cr_comments: ['comments[].id', 'comments[].author', 'comments[].path', 'comments[].body'],
+  forge_changes: ['events[].title', 'events[].url', 'events[].head_sha'],
   cr_inventory_slice: [
     'entries[].url',
     'entries[].title',

package/cr-comments.js

@@ -0,0 +1,93 @@
+import { sanitizeField } from './caps.js';
+
+export const MAX_CR_COMMENTS = 256;
+
+export function normalizeCrComment(raw) {
+  if (raw == null || typeof raw !== 'object') return null;
+  const id = raw.id ?? raw.comment_id;
+  if (id == null) return null;
+
+  const author =
+    sanitizeField(
+      raw.author ??
+        raw.user?.login ??
+        raw.user?.username ??
+        raw.user?.name ??
+        '',
+    ) || null;
+  const path =
+    raw.path != null && String(raw.path).trim() !== '' ? sanitizeField(raw.path) : null;
+  const lineRaw = raw.line ?? raw.original_line ?? raw.new_line;
+  const line =
+    lineRaw != null && Number.isFinite(Number(lineRaw)) ? Math.floor(Number(lineRaw)) : null;
+  const body = sanitizeField(raw.body ?? raw.note ?? '') ?? '';
+  const resolved = Boolean(raw.resolved ?? raw.is_resolved ?? false);
+
+  return {
+    id: sanitizeField(String(id)),
+    author,
+    path,
+    line,
+    body,
+    resolved,
+  };
+}
+
+export function buildCrCommentsBody({ pr_number, comments, comments_truncated, comment_count }) {
+  const list = Array.isArray(comments) ? comments : [];
+  const count = Number.isFinite(Number(comment_count))
+    ? Math.floor(Number(comment_count))
+    : list.length;
+  return {
+    pr_number: Math.floor(Number(pr_number)),
+    comments: list,
+    comments_truncated: Boolean(comments_truncated),
+    comment_count: count,
+  };
+}
+
+function buildCrCommentsFromNormalizedList(prNumber, all) {
+  const comment_count = all.length;
+  const capped = all.length > MAX_CR_COMMENTS;
+  const comments = all.slice(0, MAX_CR_COMMENTS);
+  return buildCrCommentsBody({
+    pr_number: prNumber,
+    comments,
+    comments_truncated: capped,
+    comment_count,
+  });
+}
+
+export function buildCrCommentsFromGiteaComments(prNumber, commentsArray) {
+  const all = [];
+  if (Array.isArray(commentsArray)) {
+    for (const item of commentsArray) {
+      const normalized = normalizeCrComment(item);
+      if (normalized) all.push(normalized);
+    }
+  }
+  return buildCrCommentsFromNormalizedList(prNumber, all);
+}
+
+export function buildCrCommentsFromGitLabDiscussions(prNumber, discussionsArray) {
+  const all = [];
+  if (Array.isArray(discussionsArray)) {
+    for (const discussion of discussionsArray) {
+      const notes = Array.isArray(discussion?.notes) ? discussion.notes : [];
+      for (const note of notes) {
+        if (note?.system === true) continue;
+        const position = note.position && typeof note.position === 'object' ? note.position : null;
+        const normalized = normalizeCrComment({
+          id: note.id,
+          author: note.author?.username ?? note.author?.name ?? '',
+          path: position?.new_path ?? position?.old_path ?? null,
+          line: position?.new_line ?? position?.old_line ?? null,
+          body: note.body ?? '',
+          resolved: note.resolved ?? false,
+        });
+        if (normalized) all.push(normalized);
+      }
+    }
+  }
+  return buildCrCommentsFromNormalizedList(prNumber, all);
+}

package/cr-files.js

@@ -0,0 +1,62 @@
+import { sanitizeField } from './caps.js';
+
+export const MAX_CR_FILES_PATHS = 256;
+
+function sanitizePathList(filesArray) {
+  if (!Array.isArray(filesArray)) return [];
+  const paths = [];
+  for (const file of filesArray) {
+    if (file == null || typeof file !== 'object') continue;
+    const sanitized = sanitizeField(file.filename);
+    if (sanitized) paths.push(sanitized);
+  }
+  return paths;
+}
+
+export function buildCrFilesBody({ pr_number, changed_paths, paths_truncated, path_count }) {
+  const paths = Array.isArray(changed_paths) ? changed_paths : [];
+  const count = Number.isFinite(Number(path_count)) ? Math.floor(Number(path_count)) : paths.length;
+  return {
+    pr_number: Math.floor(Number(pr_number)),
+    changed_paths: paths,
+    paths_truncated: Boolean(paths_truncated),
+    path_count: count,
+  };
+}
+
+export function buildCrFilesFromGiteaFiles(prNumber, filesArray) {
+  const allPaths = sanitizePathList(filesArray);
+  const path_count = allPaths.length;
+  const capped = allPaths.length > MAX_CR_FILES_PATHS;
+  const changed_paths = allPaths.slice(0, MAX_CR_FILES_PATHS);
+  return buildCrFilesBody({
+    pr_number: prNumber,
+    changed_paths,
+    paths_truncated: capped,
+    path_count,
+  });
+}
+
+export function buildCrFilesFromGitLabChanges(prNumber, changesArray) {
+  const paths = [];
+  const seen = new Set();
+  if (Array.isArray(changesArray)) {
+    for (const change of changesArray) {
+      if (change == null || typeof change !== 'object') continue;
+      const path = sanitizeField(change.new_path ?? change.old_path ?? '');
+      if (path && !seen.has(path)) {
+        seen.add(path);
+        paths.push(path);
+      }
+    }
+  }
+  const path_count = paths.length;
+  const capped = paths.length > MAX_CR_FILES_PATHS;
+  const changed_paths = paths.slice(0, MAX_CR_FILES_PATHS);
+  return buildCrFilesBody({
+    pr_number: prNumber,
+    changed_paths,
+    paths_truncated: capped,
+    path_count,
+  });
+}

package/forge-changes.js

@@ -0,0 +1,181 @@
+import { sanitizeField, sanitizeUrl } from './caps.js';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+
+export const MAX_FORGE_CHANGES_EVENTS = 256;
+
+export const FORGE_CHANGE_EVENT_KINDS = Object.freeze({
+  PR_OPENED: 'pr_opened',
+  PR_CLOSED: 'pr_closed',
+  PR_MERGED: 'pr_merged',
+  HEAD_SHA_MOVED: 'head_sha_moved',
+  CHECKS_CONCLUSION_OBSERVED: 'checks_conclusion_observed',
+});
+
+export function parseSinceObservedAt(raw) {
+  if (raw == null || String(raw).trim() === '') {
+    throw Object.assign(new Error('--since required'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--since required for forge changes'),
+    });
+  }
+  const ms = Date.parse(String(raw));
+  if (!Number.isFinite(ms)) {
+    throw Object.assign(new Error('Invalid --since'), {
+      forgeError: forgeError(
+        ERROR_CODES.INVALID_ARGS,
+        '--since must be a parseable ISO-8601 timestamp',
+      ),
+    });
+  }
+  return new Date(ms).toISOString();
+}
+
+function timestampMs(value) {
+  const ms = Date.parse(value ?? '');
+  return Number.isFinite(ms) ? ms : null;
+}
+
+function isAtOrAfter(value, sinceIso) {
+  const ms = timestampMs(value);
+  const sinceMs = timestampMs(sinceIso);
+  if (ms == null || sinceMs == null) return false;
+  return ms >= sinceMs;
+}
+
+function isBefore(value, sinceIso) {
+  const ms = timestampMs(value);
+  const sinceMs = timestampMs(sinceIso);
+  if (ms == null || sinceMs == null) return false;
+  return ms < sinceMs;
+}
+
+function normalizePrState(state) {
+  const normalized = String(state ?? '').toLowerCase();
+  if (normalized === 'open') return 'open';
+  if (normalized === 'closed') return 'closed';
+  return 'unknown';
+}
+
+function normalizeIsoTimestamp(value) {
+  const ms = timestampMs(value);
+  return ms == null ? null : new Date(ms).toISOString();
+}
+
+function baseEventFields(pull) {
+  return {
+    pr_number: Math.floor(Number(pull.number)),
+    title: sanitizeField(pull.title ?? '') || null,
+    url: sanitizeUrl(pull.html_url ?? pull.url) || null,
+  };
+}
+
+export function buildChecksConclusionObservedEvent(prNumber, checksBody) {
+  return {
+    kind: FORGE_CHANGE_EVENT_KINDS.CHECKS_CONCLUSION_OBSERVED,
+    pr_number: Math.floor(Number(prNumber)),
+    head_sha: sanitizeField(checksBody?.head_sha ?? '') || null,
+    check_conclusion: sanitizeField(checksBody?.check_conclusion ?? '') || 'unknown',
+    checks_truncated: Boolean(checksBody?.checks_truncated ?? false),
+  };
+}
+
+export function buildForgeChangesBody({
+  since,
+  events,
+  events_truncated,
+  event_count,
+  since_kind = 'observed_at',
+}) {
+  const list = Array.isArray(events) ? events : [];
+  const count = Number.isFinite(Number(event_count))
+    ? Math.floor(Number(event_count))
+    : list.length;
+  return {
+    since,
+    since_kind,
+    events: list,
+    events_truncated: Boolean(events_truncated),
+    event_count: count,
+  };
+}
+
+function capForgeChangeEvents(allEvents, sinceIso, { listTruncated = false } = {}) {
+  const event_count = allEvents.length;
+  const capped = allEvents.length > MAX_FORGE_CHANGES_EVENTS;
+  return buildForgeChangesBody({
+    since: sinceIso,
+    events: allEvents.slice(0, MAX_FORGE_CHANGES_EVENTS),
+    events_truncated: capped || listTruncated,
+    event_count,
+  });
+}
+
+export function appendForgeChangeEvents(body, additionalEvents, { listTruncated = false } = {}) {
+  const merged = [...(body.events ?? []), ...(Array.isArray(additionalEvents) ? additionalEvents : [])];
+  return capForgeChangeEvents(merged, body.since, {
+    listTruncated: listTruncated || body.events_truncated,
+  });
+}
+
+export function buildForgeChangesFromGiteaPulls(sinceIso, pullsArray, opts = {}) {
+  const since = parseSinceObservedAt(sinceIso);
+  const events = [];
+  if (Array.isArray(pullsArray)) {
+    for (const pull of pullsArray) {
+      if (pull == null || pull.number == null) continue;
+      const state = normalizePrState(pull.state);
+      const base = baseEventFields(pull);
+      const createdAt = pull.created_at;
+      const updatedAt = pull.updated_at;
+      const closedAt = pull.closed_at;
+      const mergedAt = pull.merged_at;
+      const mergedInWindow = isAtOrAfter(mergedAt, since);
+
+      if (isAtOrAfter(createdAt, since)) {
+        events.push({
+          kind: FORGE_CHANGE_EVENT_KINDS.PR_OPENED,
+          ...base,
+          state,
+          opened_at: normalizeIsoTimestamp(createdAt),
+        });
+      }
+
+      if (mergedInWindow) {
+        events.push({
+          kind: FORGE_CHANGE_EVENT_KINDS.PR_MERGED,
+          ...base,
+          state: 'closed',
+          merged_at: normalizeIsoTimestamp(mergedAt),
+        });
+      }
+
+      const closedNotMerged =
+        state === 'closed' && (mergedAt == null || String(mergedAt).trim() === '');
+      const closedInWindow =
+        isAtOrAfter(closedAt, since) ||
+        (closedAt == null && closedNotMerged && isAtOrAfter(updatedAt, since));
+      if (!mergedInWindow && closedNotMerged && closedInWindow) {
+        events.push({
+          kind: FORGE_CHANGE_EVENT_KINDS.PR_CLOSED,
+          ...base,
+          state: 'closed',
+          closed_at: normalizeIsoTimestamp(closedAt ?? updatedAt),
+        });
+      }
+
+      if (
+        state === 'open' &&
+        isAtOrAfter(updatedAt, since) &&
+        isBefore(createdAt, since)
+      ) {
+        events.push({
+          kind: FORGE_CHANGE_EVENT_KINDS.HEAD_SHA_MOVED,
+          ...base,
+          state: 'open',
+          head_sha: sanitizeField(pull.head?.sha ?? '') || null,
+          updated_at: normalizeIsoTimestamp(updatedAt),
+        });
+      }
+    }
+  }
+  return capForgeChangeEvents(events, since, { listTruncated: Boolean(opts.listTruncated) });
+}

package/index.js

@@ -36,6 +36,7 @@ export {
   forgeIngestCapabilityFacts,
   checkPaginationCapabilityFacts,
   idempotencyScanCapabilityFacts,
+  statusSetIdempotencyScanCapabilityFacts,
   openPullListCapabilityFacts,
 } from './caps.js';
 export {
@@ -73,11 +74,63 @@ export {
   appendSortQuery,
 } from './open-pull-list.js';
 export { buildChangeRequestOpenedBody } from './cr-open.js';
+export {
+  STATUS_SET_STATES,
+  assertCommitSha,
+  normalizeStatusSetState,
+  parseStatusSetArgs,
+  buildCommitStatusSetBody,
+} from './status-set.js';
+export {
+  buildProviderIdentityBody,
+  buildProviderIdentityFromGiteaUser,
+  parseGitHubOAuthScopes,
+  githubCanWriteFromScopes,
+  buildProviderIdentityFromGitHubUser,
+  normalizeGitLabCanWrite,
+  parseGitLabPatSelfSignals,
+  buildProviderIdentityFromGitLabUser,
+  normalizeGiteaCanWrite,
+  unimplementedTokenScopeSignal,
+  unimplementedTokenExpirySignal,
+} from './whoami.js';
+export {
+  buildBranchProtectionBody,
+  buildBranchProtectionFromGiteaProtection,
+  buildBranchProtectionFromGitHubProtection,
+  buildBranchProtectionFromGitLabProtection,
+  unimplementedApprovalsRequiredSignal,
+  MAX_BRANCH_PROTECTION_STATUS_CONTEXTS,
+  MAX_BRANCH_PROTECTION_RULES,
+} from './branch-protection.js';
+export {
+  buildCrFilesBody,
+  buildCrFilesFromGiteaFiles,
+  buildCrFilesFromGitLabChanges,
+  MAX_CR_FILES_PATHS,
+} from './cr-files.js';
+export {
+  buildCrCommentsBody,
+  buildCrCommentsFromGiteaComments,
+  buildCrCommentsFromGitLabDiscussions,
+  normalizeCrComment,
+  MAX_CR_COMMENTS,
+} from './cr-comments.js';
+export {
+  parseSinceObservedAt,
+  buildForgeChangesBody,
+  buildForgeChangesFromGiteaPulls,
+  buildChecksConclusionObservedEvent,
+  appendForgeChangeEvents,
+  MAX_FORGE_CHANGES_EVENTS,
+  FORGE_CHANGE_EVENT_KINDS,
+} from './forge-changes.js';
 export {
   WRITE_COMMAND_IDS,
   CONFIGURED_WRITE_COMMANDS,
   writeCommandSchema,
   assertWriteCommandConfigured,
+  writeNotConfiguredMessage,
   isWriteCommandConfigured,
 } from './write-config.js';
 export { mergeBlockersFromFacts, isOpenPrState } from './merge-blockers.js';

package/merge-plan.js

@@ -12,6 +12,9 @@ export function resolveMergePlanPathScope(ctx, view, opts = {}) {
   if (!allowedPaths) {
     return { allowed_paths: null, changed_paths: null };
   }
+  if (Array.isArray(opts.changed_paths)) {
+    return { allowed_paths: allowedPaths, changed_paths: opts.changed_paths };
+  }
   if (!view.base_sha || !view.head_sha) {
     return { allowed_paths: allowedPaths, changed_paths: null };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remogram/core",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.5",
   "description": "Remogram forge envelope, config, caps, and HTTP utilities",
   "type": "module",
   "license": "MIT",

package/status-set.js

@@ -0,0 +1,87 @@
+import { sanitizeField, sanitizeUrl } from './caps.js';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+
+/** Supported commit status states (Gitea/GitHub parity). */
+export const STATUS_SET_STATES = Object.freeze(['pending', 'success', 'failure', 'error']);
+
+const STATUS_SET_STATE_SET = new Set(STATUS_SET_STATES);
+
+const FULL_SHA_RE = /^[0-9a-fA-F]{40}$/;
+
+export function assertCommitSha(sha, label = 'sha') {
+  const value = String(sha ?? '').trim();
+  if (!FULL_SHA_RE.test(value)) {
+    throw Object.assign(new Error(`Invalid ${label}`), {
+      forgeError: forgeError(
+        ERROR_CODES.INVALID_ARGS,
+        `${label} must be a 40-character hexadecimal commit SHA`,
+      ),
+    });
+  }
+  return value.toLowerCase();
+}
+
+export function normalizeStatusSetState(state) {
+  const normalized = String(state ?? '').toLowerCase();
+  if (STATUS_SET_STATE_SET.has(normalized)) return normalized;
+  if (normalized === 'pass') return 'success';
+  if (normalized === 'fail') return 'failure';
+  throw Object.assign(new Error('Invalid status state'), {
+    forgeError: forgeError(
+      ERROR_CODES.INVALID_ARGS,
+      `state must be one of: ${STATUS_SET_STATES.join(', ')}`,
+    ),
+  });
+}
+
+export function parseStatusSetArgs({ sha, context, state, target_url, description }) {
+  const parsedSha = assertCommitSha(sha, '--sha');
+  if (context == null || String(context).trim() === '') {
+    throw Object.assign(new Error('--context required'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--context required for status set'),
+    });
+  }
+  if (state == null || String(state).trim() === '') {
+    throw Object.assign(new Error('--state required'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--state required for status set'),
+    });
+  }
+  const parsed = {
+    sha: parsedSha,
+    context: sanitizeField(String(context)),
+    state: normalizeStatusSetState(state),
+  };
+  if (target_url != null && String(target_url).trim() !== '') {
+    parsed.target_url = sanitizeUrl(String(target_url));
+  }
+  if (description != null && String(description).trim() !== '') {
+    parsed.description = sanitizeField(String(description));
+  }
+  return parsed;
+}
+
+/** Normalize forge commit status POST/GET response into commit_status_set body fields. */
+export function buildCommitStatusSetBody(
+  response,
+  args,
+  { reusedExisting = false } = {},
+) {
+  const state = normalizeStatusSetState(response?.status ?? response?.state ?? args.state);
+  const body = {
+    sha: args.sha,
+    context: sanitizeField(args.context),
+    state,
+  };
+  const description = response?.description ?? args.description;
+  if (description != null && String(description).trim() !== '') {
+    body.description = sanitizeField(String(description));
+  }
+  const targetUrl = response?.target_url ?? args.target_url;
+  if (targetUrl != null && String(targetUrl).trim() !== '') {
+    body.target_url = sanitizeUrl(String(targetUrl));
+  }
+  if (reusedExisting) {
+    body.reused_existing = true;
+  }
+  return body;
+}

package/stub-provider.js

@@ -29,5 +29,12 @@ export function createStubProvider(id) {
     prChecks: unsupported,
     mergePlan: unsupported,
     syncPlan: unsupported,
+    whoami: unsupported,
+    branchProtection: unsupported,
+    crFiles: unsupported,
+    crComments: unsupported,
+    forgeChanges: unsupported,
+    crOpen: unsupported,
+    statusSet: unsupported,
   };
 }

package/whoami.js

@@ -0,0 +1,114 @@
+import { sanitizeField } from './caps.js';
+
+/** Gitea does not expose OAuth scope or token expiry on GET /user. */
+export function unimplementedTokenScopeSignal() {
+  return { implemented: false, scopes: null };
+}
+
+export function unimplementedTokenExpirySignal() {
+  return { implemented: false, expires_at: null };
+}
+
+/** Restricted Gitea users are read-only; others may write per forge policy. */
+export function normalizeGiteaCanWrite(user) {
+  if (user == null || typeof user !== 'object') return false;
+  if (user.restricted === true) return false;
+  return true;
+}
+
+export function buildProviderIdentityBody({
+  login,
+  can_write,
+  token_scope_signal,
+  token_expiry_signal,
+}) {
+  return {
+    login: sanitizeField(login),
+    can_write: Boolean(can_write),
+    token_scope_signal,
+    token_expiry_signal,
+  };
+}
+
+export function buildProviderIdentityFromGiteaUser(user) {
+  return buildProviderIdentityBody({
+    login: user?.login ?? '',
+    can_write: normalizeGiteaCanWrite(user),
+    token_scope_signal: unimplementedTokenScopeSignal(),
+    token_expiry_signal: unimplementedTokenExpirySignal(),
+  });
+}
+
+export function parseGitHubOAuthScopes(headerValue) {
+  if (headerValue == null || String(headerValue).trim() === '') {
+    return unimplementedTokenScopeSignal();
+  }
+  const scopes = String(headerValue)
+    .split(',')
+    .map((scope) => sanitizeField(scope.trim()))
+    .filter(Boolean);
+  if (scopes.length === 0) {
+    return unimplementedTokenScopeSignal();
+  }
+  return { implemented: true, scopes };
+}
+
+export function githubCanWriteFromScopes(tokenScopeSignal) {
+  if (!tokenScopeSignal?.implemented || !Array.isArray(tokenScopeSignal.scopes)) {
+    return false;
+  }
+  return tokenScopeSignal.scopes.some(
+    (scope) => scope === 'repo' || scope === 'public_repo' || scope.startsWith('repo:'),
+  );
+}
+
+export function buildProviderIdentityFromGitHubUser(user, oauthScopesHeader) {
+  const token_scope_signal = parseGitHubOAuthScopes(oauthScopesHeader);
+  return buildProviderIdentityBody({
+    login: user?.login ?? '',
+    can_write: githubCanWriteFromScopes(token_scope_signal),
+    token_scope_signal,
+    token_expiry_signal: unimplementedTokenExpirySignal(),
+  });
+}
+
+export function normalizeGitLabCanWrite(user) {
+  if (user == null || typeof user !== 'object') return false;
+  if (user.state != null && user.state !== 'active') return false;
+  if (user.can_create_project === false) return false;
+  return true;
+}
+
+export function parseGitLabPatSelfSignals(patSelf) {
+  if (patSelf == null || typeof patSelf !== 'object') {
+    return {
+      token_scope_signal: unimplementedTokenScopeSignal(),
+      token_expiry_signal: unimplementedTokenExpirySignal(),
+    };
+  }
+  let token_scope_signal = unimplementedTokenScopeSignal();
+  if (Array.isArray(patSelf.scopes)) {
+    const scopes = patSelf.scopes.map((scope) => sanitizeField(String(scope))).filter(Boolean);
+    if (scopes.length > 0) {
+      token_scope_signal = { implemented: true, scopes };
+    }
+  }
+  const token_expiry_signal =
+    'expires_at' in patSelf
+      ? {
+          implemented: true,
+          expires_at: patSelf.expires_at == null ? null : sanitizeField(String(patSelf.expires_at)),
+        }
+      : unimplementedTokenExpirySignal();
+  return { token_scope_signal, token_expiry_signal };
+}
+
+export function buildProviderIdentityFromGitLabUser(user, patSelf) {
+  const { token_scope_signal, token_expiry_signal } = parseGitLabPatSelfSignals(patSelf);
+  return buildProviderIdentityBody({
+    login: user?.username ?? user?.login ?? '',
+    can_write: normalizeGitLabCanWrite(user),
+    token_scope_signal,
+    token_expiry_signal,
+  });
+}

package/write-config.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { ERROR_CODES, forgeError } from './contracts/errors.js';
 
 /** Canonical v1 consumer write command ids (schema + gate single source). */
-export const WRITE_COMMAND_IDS = Object.freeze(['cr_open']);
+export const WRITE_COMMAND_IDS = Object.freeze(['cr_open', 'status_set']);
 
 export const writeCommandSchema = z.enum(WRITE_COMMAND_IDS);
 
@@ -15,6 +15,15 @@ export function isWriteCommandConfigured(config, commandName) {
   return Array.isArray(allowed) && allowed.includes(commandName);
 }
 
+/** Consumer-facing message when a write command is not opted in via write_commands. */
+export function writeNotConfiguredMessage(commandName) {
+  return (
+    `Command "${commandName}" is not in write_commands; add it to .remogram.json `
+    + 'for Remogram CLI/MCP writes, or use your forge/CI tooling outside Remogram '
+    + '(read commands still work)'
+  );
+}
+
 export function assertWriteCommandConfigured(config, commandName) {
   if (!writeCommandSchema.safeParse(commandName).success) {
     throw Object.assign(new Error(`Unknown write command: ${commandName}`), {
@@ -28,7 +37,7 @@ export function assertWriteCommandConfigured(config, commandName) {
   throw Object.assign(new Error(`Write command not configured: ${commandName}`), {
     forgeError: forgeError(
       ERROR_CODES.WRITE_NOT_CONFIGURED,
-      `Add "${commandName}" to write_commands in .remogram.json to enable this command`,
+      writeNotConfiguredMessage(commandName),
     ),
   });
 }