forge-workflow 0.0.10 → 0.1.0-beta.3

package/scripts/spikes/skill-auto-invoke-parity.js

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const YAML = require('yaml');
+
+const CANONICAL_SKILL = {
+  name: 'guard-rails-audit',
+  description: 'Use when asked to inspect Forge L1 rail enforcement, audit events, or protected path policy.',
+  body: [
+    '# Guard Rails Audit',
+    '',
+    'Check Forge L1 rails, audit-event coverage, and protected path policy before recommending changes.',
+  ].join('\n'),
+};
+
+const MATCHING_PROMPT = 'Inspect Forge L1 rail enforcement and audit events for protected path policy.';
+const NON_MATCHING_PROMPT = 'Draft release notes for a minor README copy edit.';
+const FIXTURE_FILE = 'src/index.js';
+
+const SOURCES = [
+  {
+    label: 'S1',
+    harness: 'claude-code',
+    url: 'https://code.claude.com/docs/en/skills',
+    summary: 'Claude Code project skills live under .claude/skills/<skill>/SKILL.md and use description metadata for automatic invocation.',
+  },
+  {
+    label: 'S2',
+    harness: 'cursor',
+    url: 'https://docs.cursor.com/en/context',
+    summary: 'Cursor Project Rules live under .cursor/rules as .mdc files; Agent Requested rules are description-driven.',
+  },
+  {
+    label: 'S3',
+    harness: 'codex-cli',
+    url: 'https://github.com/openai/codex/blob/main/codex-rs/skills/src/assets/samples/skill-creator/SKILL.md',
+    summary: 'Codex skills use SKILL.md frontmatter name and description to determine when the skill gets used.',
+  },
+  {
+    label: 'S4',
+    harness: 'forge',
+    url: 'lib/codex-skills.js',
+    summary: 'Forge packages repository Codex skills from .codex/skills for installation into $CODEX_HOME/skills.',
+  },
+];
+
+const HARNESS_TARGETS = [
+  {
+    harness: 'claude-code',
+    target: '.claude/skills/guard-rails-audit/SKILL.md',
+    explicitInvocation: '/guard-rails-audit',
+    sourceLabel: 'S1',
+    source: 'Claude Code skill directory target',
+    buildFrontmatter: () => ({
+      name: CANONICAL_SKILL.name,
+      description: CANONICAL_SKILL.description,
+    }),
+  },
+  {
+    harness: 'cursor',
+    target: '.cursor/rules/guard-rails-audit.mdc',
+    explicitInvocation: '/guard-rails-audit',
+    sourceLabel: 'S2',
+    source: 'Cursor project rule with documented description/globs/alwaysApply metadata',
+    buildFrontmatter: () => ({
+      description: CANONICAL_SKILL.description,
+      globs: null,
+      alwaysApply: false,
+    }),
+  },
+  {
+    harness: 'codex-cli',
+    target: '.codex/skills/guard-rails-audit/SKILL.md',
+    explicitInvocation: '/guard-rails-audit',
+    sourceLabel: 'S4',
+    source: 'Forge repository Codex skills package surface; custom slash prompt files are intentionally not used',
+    buildFrontmatter: () => ({
+      name: CANONICAL_SKILL.name,
+      description: CANONICAL_SKILL.description,
+    }),
+  },
+];
+
+function buildMarkdown(frontmatter, body) {
+  return `---\n${YAML.stringify(frontmatter, {
+    lineWidth: 0,
+    defaultKeyType: 'PLAIN',
+    defaultStringType: 'PLAIN',
+  }).trimEnd()}\n---\n\n${body}\n`;
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!match) return {};
+  const parsed = YAML.parse(match[1]);
+  return parsed && typeof parsed === 'object' ? parsed : {};
+}
+
+function writeFile(root, relativePath, content) {
+  const absolutePath = path.join(root, relativePath);
+  fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+  fs.writeFileSync(absolutePath, content);
+}
+
+function isDirectoryEmpty(directory) {
+  return !fs.existsSync(directory) || fs.readdirSync(directory).length === 0;
+}
+
+function materializeFixture(root) {
+  if (!isDirectoryEmpty(root)) {
+    throw new Error(`fixture directory must be empty: ${root}`);
+  }
+
+  fs.mkdirSync(root, { recursive: true });
+  writeFile(root, FIXTURE_FILE, 'export function fixture() { return true; }\n');
+
+  for (const target of HARNESS_TARGETS) {
+    writeFile(
+      root,
+      target.target,
+      buildMarkdown(target.buildFrontmatter(), CANONICAL_SKILL.body),
+    );
+  }
+
+  return { root, skill: CANONICAL_SKILL, targets: HARNESS_TARGETS };
+}
+
+function tokens(value) {
+  return String(value)
+    .toLowerCase()
+    .match(/[a-z0-9]+/g)
+    ?.filter((token) => token.length >= 4) || [];
+}
+
+function descriptionMatches(description, prompt) {
+  const promptTokens = new Set(tokens(prompt));
+  const triggerTokens = tokens(description)
+    .filter((token) => !['when', 'asked', 'inspect'].includes(token));
+
+  return triggerTokens.some((token) => promptTokens.has(token));
+}
+
+function cursorGlobMatches(globs, filePath) {
+  void filePath;
+  if (!Array.isArray(globs) || globs.length === 0) return true;
+  return globs.includes('**/*') || globs.includes(filePath);
+}
+
+function validateHarness(root, target) {
+  const absolutePath = path.join(root, target.target);
+  const failures = [];
+
+  if (!fs.existsSync(absolutePath)) {
+    failures.push(`missing ${target.target}`);
+    return { ...target, passed: false, failures };
+  }
+
+  const frontmatter = parseFrontmatter(fs.readFileSync(absolutePath, 'utf8'));
+  const description = frontmatter.description;
+  const positiveMatch = descriptionMatches(description, MATCHING_PROMPT);
+  const negativeMatch = descriptionMatches(description, NON_MATCHING_PROMPT);
+
+  if (description !== CANONICAL_SKILL.description) {
+    failures.push('description does not match canonical skill description');
+  }
+  if (!positiveMatch) {
+    failures.push('matching prompt did not select the skill by description');
+  }
+  if (negativeMatch) {
+    failures.push('unrelated prompt selected the skill');
+  }
+  if (target.explicitInvocation !== `/${CANONICAL_SKILL.name}`) {
+    failures.push('explicit slash invocation does not match canonical skill name');
+  }
+
+  if (target.harness === 'claude-code') {
+    if (frontmatter.name !== CANONICAL_SKILL.name) failures.push('Claude skill name is missing or incorrect');
+  }
+
+  if (target.harness === 'cursor') {
+    if (frontmatter.alwaysApply !== false) failures.push('Cursor rule must keep alwaysApply: false for request-time selection');
+    if (!cursorGlobMatches(frontmatter.globs, FIXTURE_FILE)) failures.push(`Cursor globs do not include ${FIXTURE_FILE}`);
+  }
+
+  if (target.harness === 'codex-cli') {
+    if (!target.target.startsWith('.codex/skills/') || target.target.includes('/prompts/')) {
+      failures.push('Codex target must use .codex/skills, not undocumented prompt/slash files');
+    }
+  }
+
+  return {
+    ...target,
+    passed: failures.length === 0,
+    descriptionMatched: positiveMatch,
+    negativePromptIgnored: !negativeMatch,
+    frontmatter,
+    failures,
+  };
+}
+
+function runParity(options = {}) {
+  const root = options.fixtureDir || fs.mkdtempSync(path.join(os.tmpdir(), 'forge-w0-harness-parity-'));
+  const cleanup = options.fixtureDir ? false : options.cleanup !== false;
+
+  try {
+    materializeFixture(root);
+    const harnesses = HARNESS_TARGETS.map((target) => validateHarness(root, target));
+    const passed = harnesses.every((result) => result.passed);
+    const feasibleCount = harnesses.filter((result) => result.passed).length;
+    const knownIssues = passed ? [] : [{
+      issue: 'Cross-harness skill render parity did not pass for all three target harnesses.',
+      d38: 'D38 kills v3 if two of Claude/Cursor/Codex cannot render a single skill correctly by the W3 checkpoint.',
+      feasibleCount,
+    }];
+
+    return {
+      fixture: 'w0-skill-auto-invoke-parity',
+      fixtureRoot: root,
+      matchingPrompt: MATCHING_PROMPT,
+      nonMatchingPrompt: NON_MATCHING_PROMPT,
+      canonicalSkill: CANONICAL_SKILL,
+      harnesses,
+      sources: SOURCES,
+      proofBoundary: {
+        level: 'metadata-surface',
+        liveAgentInvocation: 'not-run',
+        codexRuntimeDiscovery: 'not-run',
+        reason: 'closed-source harness model invocation is outside this deterministic fixture; .codex/skills is the Forge repository packaging surface, not proof of direct Codex runtime discovery',
+      },
+      passed,
+      knownIssues,
+    };
+  } finally {
+    if (cleanup) fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function printText(result) {
+  console.log(`W0 skill auto-invoke parity: ${result.passed ? 'PASS' : 'FAIL'}`);
+  for (const harness of result.harnesses) {
+    const status = harness.passed ? 'PASS' : 'FAIL';
+    console.log(`${status} ${harness.harness} ${harness.target}`);
+    for (const failure of harness.failures) {
+      console.log(`  - ${failure}`);
+    }
+  }
+  if (result.knownIssues.length > 0) {
+    for (const issue of result.knownIssues) {
+      console.log(`Known issue: ${issue.issue} ${issue.d38}`);
+    }
+  }
+}
+
+function readStringFlag(args, name) {
+  const index = args.indexOf(name);
+  if (index === -1) return undefined;
+  const value = args[index + 1];
+  if (!value || value.startsWith('-')) return undefined;
+  return value;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const result = runParity({ fixtureDir: readStringFlag(args, '--fixture-dir') });
+
+  if (args.includes('--json')) {
+    console.log(JSON.stringify(result));
+  } else {
+    printText(result);
+  }
+
+  if (!result.passed) process.exitCode = 1;
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  CANONICAL_SKILL,
+  HARNESS_TARGETS,
+  MATCHING_PROMPT,
+  NON_MATCHING_PROMPT,
+  SOURCES,
+  descriptionMatches,
+  materializeFixture,
+  parseFrontmatter,
+  runParity,
+};

package/scripts/sync-agent-skills.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Pre-commit auto-sync for the committed `.agents/skills` mirror.
+ *
+ * `.agents/skills` is Codex's repo-local discovery path and the ONE skill mirror
+ * committed to the repo (so a teammate who clones WITHOUT running `forge setup`
+ * still gets Forge skills/stages auto-discovered). It must stay byte-identical to
+ * the canonical `skills/` source, which the structural drift gate enforces.
+ *
+ * This hook removes the regen friction: whenever `skills/**` is staged, it
+ * regenerates `.agents/skills` from `skills/` (reusing the same
+ * `populateCodexRepoSkills` / `populateAgentSkills` sync the drift gate checks
+ * against) and re-stages it, so the committed mirror never drifts from canonical.
+ *
+ * It is intentionally scoped to `skills/**` via lefthook's `glob`, so it only runs
+ * when the canonical source actually changes.
+ */
+
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { populateCodexRepoSkills, resolveCodexRepoSkillsDir } = require('../lib/codex-skills');
+
+function repoRoot() {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return path.resolve(__dirname, '..');
+  }
+}
+
+function main() {
+  const root = repoRoot();
+  let written = [];
+  try {
+    // clean: true so skills removed from canonical are dropped from the mirror too.
+    ({ written } = populateCodexRepoSkills({ sourceRoot: root, projectRoot: root, clean: true }));
+  } catch (error) {
+    console.error(`sync-agent-skills: failed to regenerate .agents/skills — ${error.message}`);
+    process.exit(1);
+  }
+
+  const mirror = resolveCodexRepoSkillsDir(root);
+  try {
+    // Stage the regenerated mirror (and any deletions within it).
+    execFileSync('git', ['add', '--all', '--', mirror], {
+      cwd: root,
+      stdio: ['ignore', 'ignore', 'inherit'],
+    });
+  } catch (error) {
+    console.error(`sync-agent-skills: failed to stage .agents/skills — ${error.message}`);
+    process.exit(1);
+  }
+
+  console.log(`sync-agent-skills: .agents/skills in sync with skills/ (${written.length} skills)`);
+}
+
+main();

package/scripts/sync-utils.sh

@@ -13,6 +13,9 @@ fi
 
 # Source shared sanitize library
 _SU_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [[ -f "$_SU_SCRIPT_DIR/bootstrap-windows-tools.sh" ]]; then
+  source "$_SU_SCRIPT_DIR/bootstrap-windows-tools.sh"
+fi
 source "$_SU_SCRIPT_DIR/lib/sanitize.sh"
 
 # ── Session Identity ───────────────────────────────────────────────────

package/scripts/test-ci-shard.js

@@ -177,17 +177,23 @@ function getShardPlan(args, { allUnitTests, durationMap }) {
   };
 }
 
-function runTests(label, files) {
-  fs.mkdirSync(reportDir, { recursive: true });
-  const junitPath = path.join(reportDir, `${label}.xml`);
-  const bunCommand = process.env.BUN_EXE || 'bun';
-  const result = spawnSync(bunCommand, [
+function buildBunTestArgs({ junitPath, files }) {
+  return [
     'test',
+    '--timeout',
+    '15000',
     '--reporter=junit',
     '--reporter-outfile',
     junitPath,
     ...files,
-  ], {
+  ];
+}
+
+function runTests(label, files) {
+  fs.mkdirSync(reportDir, { recursive: true });
+  const junitPath = path.join(reportDir, `${label}.xml`);
+  const bunCommand = process.env.BUN_EXE || 'bun';
+  const result = spawnSync(bunCommand, buildBunTestArgs({ junitPath, files }), {
     cwd: rootDir,
     stdio: 'inherit',
     shell: process.platform === 'win32',
@@ -226,6 +232,7 @@ if (require.main === module) {
 module.exports = {
   DEFAULT_SMOKE_FILES,
   PROFILE_MAX_AGE_MS,
+  buildBunTestArgs,
   createDurationMap,
   ensureFilesExist,
   getShardPlan,

package/scripts/test.js

@@ -23,15 +23,9 @@ const PACKAGE_LEVEL_PATHS = new Set([
 ]);
 
 const KNOWN_TARGETABLE_PREFIXES = [
-  '.claude/commands/',
   '.cursor/',
-  '.cline/',
-  '.roo/',
-  '.kilocode/',
-  '.opencode/',
-  '.codex/skills/',
+  '.codex/',
   '.forge/',
-  '.github/prompts/',
   '.github/agentic-workflows/',
   '.github/workflows/',
   'test/',
@@ -45,6 +39,65 @@ const ALWAYS_RUN_RISK_TEST_TARGETS = [
 
 const isWindows = process.platform === 'win32';
 
+// Wall-clock ceiling for a single spawned test lane. Bun's per-test `--timeout`
+// races a JS timer and CANNOT preempt a synchronous blocking spawn (e.g. an
+// `execFileSync` of git/bash that hangs during git mid-push state). Without this
+// ceiling such a hang blocks `forge push` indefinitely (observed ~50 min on
+// Windows, issue 8aef79e8). This kills the lane process so the push fails fast
+// instead of hanging forever.
+//
+// The default is a practical 5 minutes for a single TARGETED lane: those run a
+// small, mapped subset that completes in seconds, so 5 min is comfortably a
+// fail-fast ceiling (not the old 15-min wait that made `forge push` feel
+// wedged). Raise it with FORGE_TEST_TIMEOUT_MS for slow machines.
+const DEFAULT_TEST_COMMAND_TIMEOUT_MS = 5 * 60 * 1000;
+
+// Wall-clock budget for the FULL-SUITE fallback lane (`scripts/test-full-suite.js`),
+// which runs on package-level, unmapped, or zero-resolved changes. Unlike a
+// targeted lane, a healthy full suite legitimately takes 5-10 min, so the 5-min
+// fail-fast ceiling would kill a good-but-slow full run. Kept at 10 min to stay
+// aligned with the local-validation budget (VALIDATION_COMMAND_TIMEOUT_MS = 600000
+// in lib/commands/validate.js and its "long enough subprocess timeout for the
+// full local suite" regression test). FORGE_TEST_TIMEOUT_MS still overrides.
+const DEFAULT_FULL_SUITE_TIMEOUT_MS = 10 * 60 * 1000;
+
+// Conventional shell exit code for a command terminated by a timeout.
+const TIMEOUT_EXIT_CODE = 124;
+
+/**
+ * Reads and validates the FORGE_TEST_TIMEOUT_MS override, if any.
+ *
+ * @param {NodeJS.ProcessEnv} env Environment to read the override from.
+ * @returns {number|null} The positive integer override, or null when unset/invalid.
+ */
+function readTimeoutOverride(env) {
+  const parsed = Number.parseInt(env.FORGE_TEST_TIMEOUT_MS, 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+
+/**
+ * Resolves the wall-clock timeout for a targeted/e2e/edge-case lane, honoring
+ * FORGE_TEST_TIMEOUT_MS.
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env] Environment to read the override from.
+ * @returns {number} Timeout in milliseconds (defaults to DEFAULT_TEST_COMMAND_TIMEOUT_MS).
+ */
+function resolveCommandTimeoutMs(env = process.env) {
+  return readTimeoutOverride(env) ?? DEFAULT_TEST_COMMAND_TIMEOUT_MS;
+}
+
+/**
+ * Resolves the wall-clock budget for the full-suite fallback lane. An explicit
+ * FORGE_TEST_TIMEOUT_MS override wins; otherwise it uses the larger,
+ * validation-aligned budget so a healthy-but-slow full run is not failed fast.
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env] Environment to read the override from.
+ * @returns {number} Timeout in milliseconds (defaults to DEFAULT_FULL_SUITE_TIMEOUT_MS).
+ */
+function resolveFullSuiteTimeoutMs(env = process.env) {
+  return readTimeoutOverride(env) ?? DEFAULT_FULL_SUITE_TIMEOUT_MS;
+}
+
 /**
  * @typedef {Object} TestExecutionPlan
  * @property {string[]} changedFiles
@@ -101,7 +154,19 @@ function isKnownTargetablePath(file) {
     return true;
   }
 
-  if (file.startsWith('docs/plans/')) {
+  if (file === 'README.md'
+    || file === 'bin/forge.js'
+    || file === 'QUICKSTART.md'
+    || file === 'CHANGELOG.md'
+    || file === 'AGENTS.md'
+    || file === 'DEVELOPMENT.md'
+    || file === 'docs/INDEX.md'
+    || file === 'docs/PROJECT_DESIGN.md'
+    || file.startsWith('docs/forge/')
+    || file.startsWith('docs/guides/')
+    || file.startsWith('docs/plans/')
+    || file.startsWith('docs/reference/')
+    || file.startsWith('docs/work/')) {
     return true;
   }
 
@@ -257,6 +322,15 @@ function runCommand(command, args, options = {}, spawnSync = defaultSpawnSync) {
   });
 
   if (result.error) {
+    if (result.error.code === 'ETIMEDOUT') {
+      console.error('');
+      console.error('Test lane exceeded its wall-clock ceiling and was terminated.');
+      console.error('A single test likely hung (e.g. a spawned git/bash call that never returns).');
+      console.error('Adjust the ceiling with FORGE_TEST_TIMEOUT_MS. Failing the run instead of');
+      console.error('blocking the push. See issue 8aef79e8.');
+      console.error('');
+      return TIMEOUT_EXIT_CODE;
+    }
     throw result.error;
   }
 
@@ -276,30 +350,35 @@ function runTestExecutionPlan(plan, deps = {}) {
   const env = deps.env || stripGitHookEnv(process.env);
   const bunCommand = deps.bunCommand || env.BUN_EXE || process.env.BUN_EXE || 'bun';
   const label = deps.label || 'tests';
+  const timeout = resolveCommandTimeoutMs(env);
+  const laneOptions = { env, killSignal: 'SIGKILL', timeout };
+  // The full-suite fallback gets a larger, validation-aligned budget so a
+  // healthy-but-slow full run is not failed fast by the targeted-lane ceiling.
+  const fullSuiteOptions = { env, killSignal: 'SIGKILL', timeout: resolveFullSuiteTimeoutMs(env) };
 
   console.log(`Running ${label} (${pkgManager})...`);
 
   try {
     if (plan.runFullSuite) {
       console.log(`  Mode: full suite (${plan.reason})`);
-      const status = runCommand('node', ['scripts/test-full-suite.js'], { env }, spawnSync);
+      const status = runCommand('node', ['scripts/test-full-suite.js'], fullSuiteOptions, spawnSync);
       if (status !== 0) return status;
     } else if (plan.testTargets.length > 0) {
       console.log(`  Mode: targeted (${plan.testTargets.length} test file${plan.testTargets.length === 1 ? '' : 's'})`);
       const command = pkgManager === 'bun' ? bunCommand : pkgManager;
-      const status = runCommand(command, ['run', 'test', ...plan.testTargets], { env }, spawnSync);
+      const status = runCommand(command, ['run', 'test', ...plan.testTargets], laneOptions, spawnSync);
       if (status !== 0) return status;
     }
 
     if (plan.runE2E) {
       console.log('  Extra: running affected e2e tests');
-      const status = runCommand(bunCommand, ['test', 'test/e2e/'], { env }, spawnSync);
+      const status = runCommand(bunCommand, ['test', '--timeout', '15000', 'test/e2e/'], laneOptions, spawnSync);
       if (status !== 0) return status;
     }
 
     if (!plan.runFullSuite && plan.runTestEnv) {
       console.log('  Extra: running affected edge-case tests');
-      const status = runCommand(bunCommand, ['test', 'test-env/'], { env }, spawnSync);
+      const status = runCommand(bunCommand, ['test', '--timeout', '15000', 'test-env/'], laneOptions, spawnSync);
       if (status !== 0) return status;
     }
 
@@ -348,9 +427,13 @@ if (require.main === module) {
 
 module.exports = {
   ALWAYS_RUN_RISK_TEST_TARGETS,
+  DEFAULT_FULL_SUITE_TIMEOUT_MS,
+  DEFAULT_TEST_COMMAND_TIMEOUT_MS,
   buildTestExecutionPlan,
   classifyPushTests,
   detectPackageManager,
+  resolveCommandTimeoutMs,
+  resolveFullSuiteTimeoutMs,
   runLocalValidationTests,
   runPrePushTests,
   runTestExecutionPlan,

package/skills/claim-safety/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: claim-safety
+description: >
+  Claim a Forge issue and then PROVE you hold the live lease before you touch it, using `forge
+  issue owns <id>` (exit 0 iff you hold the single unexpired lease). Use this whenever winning
+  the claim matters: right after `forge claim`, before you `dev`/edit/`close`/`release` a
+  claimed issue, when two agents or a subagent fan-out contend for the same work, or before
+  any irreversible step. A claim's `ok:true` does NOT prove you won — duplicate replays return
+  it and expired leases get reclaimed; only `owns` proves it, so re-verify before
+  close/release. Trigger on "claim this issue safely", "did I actually win the lease",
+  "verify/prove ownership", "claim conflict", "two agents grabbed the same issue", "check I
+  still own it before closing", or before ANY mutation of a claimed issue. NOT for plain
+  single-issue create/update/close/comment with no ownership question (that is issue-basics),
+  and NOT for read-only selecting or ranking the next ready issue without claiming (that is
+  triage-ready).
+allowed-tools: Read, Bash(forge:*)
+---
+
+# Claim safety — claim, then prove you own the lease
+
+Claiming is not owning. The Forge kernel keys a claim's idempotency on
+`claim.create:<issue_id>:<actor>`, so a **same-key duplicate replay returns
+`ok:true`** echoing the *current* call's `claim_id`. A genuine cross-actor
+conflict returns `ok:false` (the partial-UNIQUE active-lease index guarantees one
+lease) — but `ok:true` **alone does not prove sole ownership**. A live lease can
+also be **reclaimed on expiry** (an expired lease is superseded by the next
+claimant). Therefore every worker MUST verify ownership before mutating a claimed
+issue, and RE-verify before `close`/`release`.
+
+This is a reusable, standalone procedure: any skill or agent that mutates a
+claimed issue embeds it (it is NOT folded into one orchestrator).
+
+## The verification primitive
+
+```bash
+forge issue owns <id>          # exit 0 iff YOU hold the live lease; non-zero otherwise
+forge issue owns <id> --json   # { ok:true, data:{ owned, claimed_by, expired, actor, expires_at } }
+```
+
+`owns` resolves your actor the same way the kernel does — `FORGE_ACTOR` →
+`FORGE_SESSION_ID` → default `forge` — then reports `owned:true` iff you hold the
+**single active claim** AND that lease **has not expired**. It exits `0` when you
+own it and non-zero (conflict, code 4) when you do not, with a clear "you do not
+own the lease for `<id>` (held by `<actor>`)" message. It is a strict READ — it
+never mutates kernel state. (`data.claimed_by` is lease-derived; there is no
+`claims` command.)
+
+## Procedure
+
+1. **Select** work — `forge issue ready --json` (see the `triage-ready` skill).
+   Never claim epics/decisions or defer-windowed items.
+2. **Claim** — `FORGE_ACTOR=<your-actor> forge claim <id>`. Always run under a
+   distinct actor so a losing claim reaches the conflict guard instead of
+   collapsing to a shared-actor duplicate.
+3. **Prove ownership BEFORE working** — `forge issue owns <id>`.
+   - **exit 0 (OWNED)** → the lease is yours; proceed to work.
+   - **non-zero (NOT OWNED)** → you lost the race, or your claim collapsed to a
+     foreign/duplicate-collapsed claim. Do NOT work the issue. **Reselect** via
+     `forge issue ready --json` and start over at step 1.
+4. **Work** the issue (`dev`/edit/etc.).
+5. **RE-verify before `close`/`release`** — a live lease can be reclaimed on
+   expiry while you worked. Run `forge issue owns <id>` again:
+   - **OWNED** → `forge release check --target <release-ref> --json` (release-readiness; omit `--target` to use the project default), then
+     `forge close <id> --reason "…"` or `forge release <id>`.
+   - **NOT OWNED** → the lease was reclaimed (likely expired). Do NOT close/
+     release someone else's lease; reselect and, if the work is still needed,
+     re-claim and reconcile.
+
+## Contract (what each result means)
+
+| `forge claim` result | Meaning | Action |
+|----------------------|---------|--------|
+| `ok:false` (conflict, code 4) | A live lease is held by another actor | Reselect (`ready`) |
+| `ok:true` | Provisionally yours — **not proof** (duplicate replays also return ok:true) | **Run `forge issue owns <id>`** |
+
+| `forge issue owns` | Meaning | Action |
+|--------------------|---------|--------|
+| exit 0, `owned:true` | You hold the live, unexpired lease | Work / close / release |
+| non-zero, `owned:false` | Someone else holds it, or your lease expired | Reselect; never mutate |
+
+## Fork points
+
+- **Actor source** — how `<your-actor>` is derived (`FORGE_ACTOR` explicit id →
+  `FORGE_SESSION_ID` → default `forge`). Use a distinct per-agent actor so
+  contending claims reach the conflict guard rather than collapsing to a duplicate.
+- **Expiry / lease TTL** — whether claims carry an `expires_at` and how long;
+  `owns` treats an expired lease as NOT owned (it can be reclaimed).
+- **Re-verify cadence** — verify after claim and again before `close`/`release`;
+  a longer task may re-verify more often (e.g. before each irreversible step).
+- **Reselection policy** — on NOT-OWNED, how the next item is chosen (ranking /
+  filters live in the `triage-ready` skill).
+- **Fail-closed posture** — with no usable clock/state, treat ownership as NOT
+  proven (mirror the readiness model's "no usable clock ⇒ not workable").
+
+## Reliability notes
+
+- A genuine cross-actor conflict returns `ok:false` — there is no phantom
+  `ok:true`-on-conflict. The real hazards are (a) a duplicate replay's `ok:true`
+  and (b) expiry-driven reclaim. `owns` closes both.
+- Full multi-agent safety depends on the actor-identity kernel fix (distinct
+  actors per agent, kernel `d71a824b`): without distinct actors, two agents
+  share one idempotency key and `owns` cannot tell them apart.