@windyroad/itil 3.4.0-preview.1367 → 3.4.0-preview.1369

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "3.4.0-preview.1367",
+  "version": "3.4.0-preview.1369",
   "description": "ITIL-aligned IT service management for Claude Code and Codex",
   "bin": {
     "windyroad-itil": "./bin/install.mjs"

package/skills/outcome-led-planning/references/github-coordination.md

@@ -156,7 +156,7 @@ Use this contribution lifecycle:
 
 A starting battle plan exposes likely work, dependencies and parallel opportunities without precreating, assigning or reserving every future task. The increment owner keeps acceptance, sequence and integration clear and resolves overlap/dependencies. Explicit assignments and handoffs remain valid. Two agents sharing an account are distinct contributors. Checklists suffice for routine steps; do not create a task for every command. Task creation within assessed scope requires no fresh human approval.
 
-**Each agent holds only one contribution task at a time**, including a blocked assignment. Finish, explicitly hand over or release the current assignment before claiming another. Do not reserve queued tasks. Outcome or increment coordination ownership does not reserve contribution tasks. Agents sharing an account remain distinct through their recorded agent/session identities.
+**One contribution claim is a ceiling, not a retention requirement.** A blocked assignment still counts until its release is verified. For an unfinished task, when no useful authorized in-task step remains, hand over the remaining gap, remove your assignment and read back its removal; do not retain it merely because its dependency is unresolved. Preserve genuine assigned watcher duties; routine discussion reads alone do not justify retaining an exhausted reservation. Finish, explicitly hand over or release the current assignment before claiming another. Do not reserve queued tasks. Outcome or increment coordination ownership does not reserve contribution tasks. Agents sharing an account remain distinct through their recorded agent/session identities.
 
 Before declaring a contribution ready to start, complete this claim receipt: **no other contribution assignment held; parent increment; current assessed plan revision; non-overlapping scope; dependencies (or explicitly none); actual account; distinct agent/session; saved claim and reciprocal-link readback; competing-claim recheck.** Record all fields on the task, even when some are already known in conversation. Assignment does not increase authority. When explaining a proposed claim, make these required fields and the before/after overlap checks explicit.
 
@@ -188,15 +188,31 @@ actual acknowledgement.
 
 At each work checkpoint, reconcile tracking in this order:
 
-1. **Establish scope.** Reuse the established backend. Establish Project selection
-   separately from the backend, using configuration, project requirements or
-   explicit direction: selected/required, none, or unresolved. Do not infer none
-   or an unset configuration from omitted information. An established choice to
-   use no Project needs no setup. While selection remains unresolved, inspect available
-   records and keep Project work conditional; do not assert a pending or
-   unsynchronized mirror. An unavailable API or bootstrap default proves neither
-   selection nor a missing view, field or membership; inspect saved setup before
-   naming gaps.
+When the affected records include an outcome, current Now, provisional Next and
+a task, and `gh` works, MUST first use the [read-only hierarchy inspector](github-project-checkpoint.md#inspect-the-hierarchy).
+Construct its request from those actual records and consume its findings before
+claiming completeness; identical draft/remote text is not that comparison.
+Do not manufacture a Next issue for this route. Its configuration report is one
+source for the selection decision below, not proof of capability or acceptance.
+
+1. **Establish selection before checking Project capability.** Reuse the
+   established backend. From configuration, project requirements or explicit
+   direction, choose the applicable branch:
+   - **Selected/required:** verify the repository, Project and account, then
+     inspect its saved setup and applicable operations. For join/resume of an
+     active open task with working `gh`, MUST use the [executable Project checkpoint](github-project-checkpoint.md).
+     Read its inspection and handle current discussion before applying it;
+     do not manually publish synchronization-success text on that route.
+     If an applicable operation is unavailable, retain its exact pending state
+     under the recovery rules below. An unavailable API or bootstrap default
+     does not prove a missing view, field or membership.
+   - **Established none:** continue issue-side reconciliation without Project
+     setup, fields or synchronization.
+   - **Unresolved:** inspect available configuration, requirements, direction and
+     issue records. Record the selection gap and keep Project work conditional;
+     there is no established mirror operation to report pending or unsynchronized.
+     Omitted information and API availability establish neither selection nor
+     an explicit choice to use no Project.
 2. **Inspect each affected record.** Read each outcome, increment and task
    against the minimum-information table above. Preserve its own owner/account,
    applicable agent/session, revision and acceptance; mark missing required

package/skills/outcome-led-planning/references/github-project-checkpoint.md

@@ -0,0 +1,137 @@
+# Inspect and reconcile GitHub records
+
+Resolve `scripts/github-project-checkpoint.mjs` relative to this installed
+planning skill, including when called from `contribute`. Use the existing
+authenticated `gh` account and saved project configuration. The default is
+`.agents/planning.json`; an existing project-declared configuration path may be
+supplied last. These operations require no new grants, account changes or tokens.
+Local tracking keeps its existing path.
+
+## Inspect the hierarchy
+
+When reconciling an outcome, current Now, an affected provisional Next and a
+task together with working `gh`, planning and `contribute` MUST first use the
+read-only hierarchy inspector. Supply those actual distinct issue numbers;
+do not invent a Next issue to satisfy the command. Other record sets retain
+their existing coordination path.
+
+```json
+{
+  "outcome": 1,
+  "increment": {"issue": 2},
+  "next": {"issue": 3},
+  "task": {"issue": 4}
+}
+```
+
+Run `node <installed-planning-skill>/scripts/github-project-checkpoint.mjs inspect-hierarchy request.json`.
+This reads the four actual issues and their returned comments. It writes
+nothing and makes no Project or native-link request. Read the raw records and
+consume `findings` before claiming that the records are correct:
+
+- `projectSelection` reports configuration facts. `not-recorded` means selection
+  is unresolved from that configuration, not an explicit choice to use no
+  Project. `recorded` does not prove capability; consider actual project
+  requirements and explicit direction too. Preserve invalid configuration.
+- Each record's `inspection` reports literal owner, revision, acceptance and
+  Parent candidates with raw line evidence. `candidate` is text, not verified
+  ownership or passed acceptance. `explicitly-unresolved` preserves a recorded
+  unknown. Empty/missing literals, unsupported syntax and multiple candidates
+  remain unestablished by this inspector; they do not prove semantic information
+  is absent or that the issue is invalid. Inspect the actual prose/history
+  rather than forcing a new format or choosing a historical value.
+- `textLinks` compares the three requested textual relationships. A mention is
+  observed text, not proof of a current native relationship. Inspect both sides
+  and repair known reciprocal gaps under the existing coordination rules.
+- `capabilities` are `not-probed`; do not turn that into an outage or native-link
+  absence. `inspection-unavailable` means the read/report operation failed,
+  not that a Project mirror is pending.
+
+A successful command produces a diagnostic report, never a correctness or
+synchronization verdict. Identical drafts and saved bodies do not establish
+completeness. Before claiming completeness, account for every finding through
+actual semantic review, authorized repair with saved readback where needed, or
+honest unresolved recording in the existing plan or record. Follow the selection
+finding's conditional next action, which targets the existing outcome issue
+for saving and reading back a still-unresolved gap. Reuse an already saved gap
+without an unchanged write. Configuration alone may leave the choice unresolved
+while requirements or explicit direction establish it. Unsupported
+syntax does not force normalization or another artifact.
+Apply the existing per-record rules to known gaps, marking missing
+required information unresolved rather than inventing it; preserve completed
+acceptance and attribution. Read back authorized changes and compare reciprocal
+links before reporting reconciliation. Unsupported syntax needs actual review,
+not automatic normalization. Semantic acceptance remains with the caller and
+required independent review.
+
+## Synchronize selected Project fields
+
+For a join/resume checkpoint on an active open task with a selected GitHub Project and working `gh`,
+planning and `contribute` MUST use the bundled
+`scripts/github-project-checkpoint.mjs` operation. Do not manually publish a
+Project synchronization-success claim on this route. The operation reads the
+records/discussion, updates the two items, verifies their saved fields and only
+then generates the task's synchronization result. It does not allocate owners,
+approve a plan, acknowledge another person or complete the increment.
+
+This mutation route applies to its open outcome, increment and active task.
+GitHub Issues-only tracking uses no Project field mutations.
+
+## Inspect, decide, apply
+
+Create a request from the actual records and Project fields. IDs below are
+placeholders. Preserve each record's own verified agent/session; do not copy the
+task contributor onto the increment. The status option must be the existing
+In progress equivalent, never Done.
+
+```json
+{
+  "outcome": 1,
+  "increment": {"issue": 2, "itemId": "INCREMENT_ITEM_ID", "agent": "verified increment owner/session"},
+  "task": {"issue": 4, "itemId": "TASK_ITEM_ID", "agent": "verified task owner/session"},
+  "statusFieldId": "STATUS_FIELD_ID",
+  "agentFieldId": "AGENT_FIELD_ID",
+  "statusOptionId": "IN_PROGRESS_OPTION_ID",
+  "nextAction": "the actual next step in this task"
+}
+```
+
+1. Run `node <installed-planning-skill>/scripts/github-project-checkpoint.mjs inspect request.json`.
+   The default configuration is `.agents/planning.json` in the project. An
+   existing project-declared configuration path may be supplied as the final
+   argument. Save the returned JSON in a permitted working location.
+2. Read that inspection, including the increment discussion, current revision,
+   dependencies and claims. Acknowledge relevant handoffs through the authorized
+   channel and resolve overlap or material changes under the existing rules.
+   The operation reading a comment does not mean its recipient acknowledged it.
+   If that work changes these records, inspect again before applying.
+3. Run `node <installed-planning-skill>/scripts/github-project-checkpoint.mjs apply request.json inspection.json`.
+   Supply the same explicit configuration path last when one was used above.
+   The operation rechecks inspected context, updates only task/increment
+   Status/Agent, reads back the actual fields, then publishes generated task
+   progress and reads it back. It preserves Horizon and the rest of the brief.
+   The current brief needs a literal `Next action:` line; if absent, maintain
+   that field truthfully before inspecting again. Do not erase existing content.
+
+Use direct commands with literal paths supported by the runtime permissions.
+Do not infer unavailable authority from one rejected compound command when an
+already-authorized direct invocation remains available.
+
+## Read the result
+
+- `synchronized`: the requested fields and generated task update were read back.
+  This establishes this checkpoint only, not task or increment completion.
+- `changed-context`: inspect the returned facts and resolve the change. A body
+  changed before publication stays untouched, even if fields already changed.
+- `pending`: keep the precise affected operation and next action visible. A
+  partial or ambiguous field result cannot generate synchronization success.
+  The operation reads saved state before resolving uncertain writes and never
+  automatically repeats a mutation. If the pending note itself could not be
+  saved, its output does not prove the issue was updated.
+
+Do not treat an exit code, assignment or local note as a saved-field result.
+Keep useful authorized issue work moving while Project work is pending. If
+`gh` or this operation is unavailable, use other already-authorized capabilities
+under the coordination protocol, preserving the same truthful claim dependency.
+Do not request broader access while an existing authorized route works, or
+claim the executable operation enforced an untested browser/manual path.

package/skills/outcome-led-planning/scripts/github-project-checkpoint.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { isDeepStrictEqual } from 'node:util';
+
+const itemQuery = `query($ids:[ID!]!,$agentFieldId:ID!){nodes(ids:$ids){... on ProjectV2Item{
+  id project{id url} content{... on Issue{number url parent{number url}}}
+  fieldValues(first:100){nodes{... on ProjectV2ItemFieldSingleSelectValue{
+    optionId name field{... on ProjectV2SingleSelectField{id}}
+  } ... on ProjectV2ItemFieldTextValue{text field{... on ProjectV2Field{id}}}}
+  pageInfo{hasNextPage}}
+}} agentField:node(id:$agentFieldId){... on ProjectV2Field{dataType}}}`;
+const start = '<!-- outcome-led-planning:project-checkpoint:start -->';
+const end = '<!-- outcome-led-planning:project-checkpoint:end -->';
+const load = path => JSON.parse(readFileSync(path, 'utf8'));
+const requireValue = (ok, message) => { if (!ok) throw new Error(message); };
+
+function call(args, input) {
+  const result = spawnSync('gh', args, { input, encoding: 'utf8', timeout: 60000 });
+  return { ...result, failure: result.error?.message || (result.status !== 0 ? result.stderr.trim() || `gh exited ${result.status}` : '') };
+}
+function json(args, input) {
+  const result = call(args, input);
+  if (result.failure) throw new Error(result.failure);
+  const value = JSON.parse(result.stdout);
+  if (value.errors?.length) throw new Error(value.errors.map(error => error.message).join('; '));
+  return value;
+}
+function repositoryFor(config) {
+  requireValue(config?.version === 1 && config.backend === 'github', 'This operation requires the saved GitHub backend.');
+  const repository = config.github?.repository;
+  requireValue(typeof repository === 'string' && /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\/[\w.-]+$/.test(repository) && !['.', '..'].includes(repository.split('/')[1]), 'Invalid configured GitHub repository.');
+  return repository;
+}
+function scope(request, config) {
+  const repository = repositoryFor(config);
+  const url = new URL(config.github?.projectUrl);
+  const match = url.pathname.match(/^\/(?:users|orgs)\/([\w.-]+)\/projects\/([1-9]\d*)(?:\/views\/[1-9]\d*)?\/?$/);
+  requireValue(url.protocol === 'https:' && url.hostname === 'github.com' && match && !url.username && !url.password, 'A selected GitHub Project URL is required.');
+  requireValue([request.outcome, request.increment?.issue, request.task?.issue].every(n => Number.isSafeInteger(n) && n > 0), 'Outcome, increment and task issue numbers are required.');
+  requireValue(new Set([request.outcome, request.increment.issue, request.task.issue]).size === 3, 'The three issue roles must be distinct.');
+  for (const value of [request.increment.itemId, request.task.itemId, request.statusFieldId, request.agentFieldId, request.statusOptionId]) {
+    requireValue(typeof value === 'string' && value.length > 0 && !/[\r\n\0]/.test(value), 'Existing item, field and option IDs are required.');
+  }
+  requireValue(request.increment.itemId !== request.task.itemId && request.statusFieldId !== request.agentFieldId, 'Item and field roles must be distinct.');
+  return { repository, owner: match[1], number: match[2], projectUrl: `https://github.com${url.pathname.split('/views/')[0].replace(/\/$/, '')}` };
+}
+function issue(number, bound) {
+  return json(['issue', 'view', String(number), '--repo', bound.repository, '--json', 'number,url,body,state,assignees,labels,comments']);
+}
+function briefField(body, pattern, cue) {
+  // shortcut: observed literal brief fields only; extend when an actual brief needs another syntax.
+  const lines = body.split(/\r?\n/).map((text, index) => ({ line: index + 1, text }));
+  const matches = lines.flatMap(line => {
+    const match = line.text.match(pattern);
+    return match ? [{ ...line, value: match[1].trim() }] : [];
+  });
+  const literalEvidence = matches.map(({ line, text }) => ({ line, text }));
+  if (matches.length > 1) return { state: 'multiple-candidates', evidence: literalEvidence };
+  if (matches.length === 1) {
+    const { value } = matches[0];
+    return { state: !value ? 'empty' : /^(?:unresolved|unknown|tbd|unclaimed)(?:\b|$)/i.test(value) ? 'explicitly-unresolved' : 'candidate', value, evidence: literalEvidence };
+  }
+  const evidence = lines.filter(line => cue.test(line.text));
+  return { state: evidence.length ? 'unsupported-format' : 'literal-field-missing', evidence };
+}
+function textReference(body, number, repository) {
+  const escaped = repository.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const reference = new RegExp(`(?:(?<![\\w./#:-])#${number}\\b|https://github\\.com/${escaped}/issues/${number}(?![\\w/]))`, 'i');
+  const evidence = body.split(/\r?\n/).flatMap((text, index) => reference.test(text) ? [{ line: index + 1, text }] : []);
+  return { observed: evidence.length > 0, evidence };
+}
+function inspectHierarchy(request, config) {
+  const repository = repositoryFor(config);
+  const roles = { outcome: request?.outcome, increment: request?.increment?.issue, next: request?.next?.issue, task: request?.task?.issue };
+  requireValue(Object.values(roles).every(n => Number.isSafeInteger(n) && n > 0) && new Set(Object.values(roles)).size === 4, 'Four distinct outcome, increment, next and task issue numbers are required.');
+  const projectSelection = { state: 'not-recorded', source: 'configuration' };
+  if (Object.hasOwn(config.github, 'projectUrl')) {
+    try {
+      const url = new URL(config.github.projectUrl);
+      requireValue(url.protocol === 'https:' && url.hostname === 'github.com' && !url.username && !url.password && !url.search && !url.hash && /^\/(?:users|orgs)\/[\w.-]+\/projects\/[1-9]\d*(?:\/views\/[1-9]\d*)?\/?$/.test(url.pathname), 'Invalid recorded Project URL.');
+      Object.assign(projectSelection, { state: 'recorded', url: `https://github.com${url.pathname.split('/views/')[0].replace(/\/$/, '')}` });
+    } catch { projectSelection.state = 'invalid'; }
+  }
+  const records = {};
+  const findings = projectSelection.state === 'recorded' ? [] : [{ issue: roles.outcome, field: 'projectSelection', state: projectSelection.state, nextAction: `Establish selection from applicable project requirements and explicit direction. If it remains unresolved, save that selection gap and conditional Project work on outcome #${roles.outcome} and read back its saved body before claiming reconciliation complete. Reuse an already saved gap without an unchanged write.` }];
+  for (const [role, number] of Object.entries(roles)) {
+    const record = issue(number, { repository });
+    requireValue(record.number === number && record.url?.toLowerCase() === `https://github.com/${repository}/issues/${number}`.toLowerCase() && typeof record.body === 'string', 'Returned issue does not match its requested repository/number or brief.');
+    const inspection = {
+      owner: briefField(record.body, /^\s*(?:(?:Outcome|Increment|Task) )?Owner:\s*(.*)$/i, /\bowner\b/i),
+      revision: briefField(record.body, /^\s*Revision:\s*(.*)$/i, /\brevision\b/i),
+      acceptance: briefField(record.body, /^\s*(?:Tentative )?Acceptance(?: criteria| evidence)?:\s*(.*)$/i, /\bacceptance\b/i),
+      parent: briefField(record.body, /^\s*Parent(?: outcome| increment)?:\s*(.*)$/i, /\bparent\b/i)
+    };
+    records[role] = { ...record, inspection };
+    for (const field of ['owner', 'revision', 'acceptance']) {
+      if (!['candidate', 'explicitly-unresolved'].includes(inspection[field].state)) findings.push({ issue: number, field, state: inspection[field].state });
+    }
+  }
+  const textLinks = [[records.outcome, records.increment], [records.outcome, records.next], [records.increment, records.task]].map(([parent, child]) => {
+    const parentMentionsChild = textReference(parent.body, child.number, repository);
+    const field = child.inspection.parent;
+    const referencesExpected = 'value' in field ? textReference(field.value, parent.number, repository).observed : null;
+    if (!parentMentionsChild.observed) findings.push({ issue: parent.number, field: 'child-text-reference', state: 'not-established', child: child.number });
+    if (referencesExpected !== true) findings.push({ issue: child.number, field: 'parent-text-reference', state: 'not-established', parent: parent.number });
+    return { parent: parent.number, child: child.number, parentMentionsChild, childParent: { ...field, referencesExpected } };
+  });
+  return { repository, projectSelection, capabilities: { project: 'not-probed', nativeLinks: 'not-probed' }, records, textLinks, findings };
+}
+function items(request, bound, projectId) {
+  const response = json(['api', 'graphql', '--input', '-'], JSON.stringify({ query: itemQuery, variables: { ids: [request.increment.itemId, request.task.itemId], agentFieldId: request.agentFieldId } }));
+  requireValue(response.data.agentField?.dataType === 'TEXT', 'The Agent field must be a text field.');
+  return response.data.nodes.map((item, index) => {
+    const record = index === 0 ? request.increment : request.task;
+    const parent = index === 0 ? request.outcome : request.increment.issue;
+    const expected = `https://github.com/${bound.repository}/issues/${record.issue}`;
+    requireValue(item && item.id === record.itemId && item.project.id === projectId && item.project.url === bound.projectUrl, 'Project item does not belong to the selected Project.');
+    requireValue(item.content?.url.toLowerCase() === expected.toLowerCase() && item.content.parent?.number === parent && item.content.parent.url.toLowerCase() === `https://github.com/${bound.repository}/issues/${parent}`.toLowerCase(), 'Current native issue parent or repository does not match the requested hierarchy.');
+    requireValue(!item.fieldValues.pageInfo.hasNextPage, 'Project field response is incomplete; inspect the remaining fields before applying.');
+    return { id: item.id, issue: record.issue, fields: Object.fromEntries(item.fieldValues.nodes.filter(value => value.field?.id).map(value => [value.field.id, 'text' in value ? { text: value.text } : { optionId: value.optionId, name: value.name }]).sort(([a], [b]) => a.localeCompare(b))) };
+  });
+}
+function inspect(request, config) {
+  const bound = scope(request, config);
+  const actor = json(['api', 'user']).login;
+  const project = json(['project', 'view', bound.number, '--owner', bound.owner, '--format', 'json']);
+  requireValue(project.url === bound.projectUrl && !project.closed, 'Selected Project is unavailable or closed.');
+  const allFields = json(['project', 'field-list', bound.number, '--owner', bound.owner, '--format', 'json']).fields;
+  const status = allFields.find(field => field.id === request.statusFieldId);
+  const agent = allFields.find(field => field.id === request.agentFieldId);
+  const option = status?.options?.find(value => value.id === request.statusOptionId);
+  requireValue(status?.name === 'Status' && status.type === 'ProjectV2SingleSelectField' && agent?.name === 'Agent' && agent.type === 'ProjectV2Field' && option, 'Requested fields must be the selected Project Status and Agent fields.');
+  requireValue(option.name.replace(/[-_\s]/g, '').toLowerCase() === 'inprogress', 'A resume checkpoint requires the existing In progress status option.');
+  const records = { outcome: issue(request.outcome, bound), increment: issue(request.increment.issue, bound), task: issue(request.task.issue, bound) };
+  requireValue(Object.values(records).every(record => record.state === 'OPEN'), 'This resume operation requires open outcome, increment and task records.');
+  return { context: { actor, repository: bound.repository, project: { id: project.id, url: project.url }, fields: { status: { id: status.id, option }, agent: { id: agent.id } }, issues: records, items: items(request, bound, project.id) } };
+}
+function bodyFor(body, request, status, observed, reason) {
+  // shortcut: only the observed literal Next action line; extend when an adopter needs another brief format.
+  requireValue(/^Next action:[^\r\n]*/m.test(body), 'Task brief needs its current literal Next action line; no body changes were made.');
+  const first = body.indexOf(start);
+  const last = body.indexOf(end);
+  requireValue((first === -1 && last === -1) || (first >= 0 && last > first && body.indexOf(start, first + 1) === -1 && body.indexOf(end, last + 1) === -1), 'Existing checkpoint block is malformed; preserve the body and repair that block first.');
+  let preserved = first < 0 ? body : body.slice(0, first) + body.slice(last + end.length);
+  const next = status === 'synchronized' ? request.nextAction : `Resolve the pending Project checkpoint: ${reason}`;
+  preserved = preserved.replace(/^Next action:[^\r\n]*/m, () => `Next action: ${next}`);
+  const rows = status === 'synchronized' ? observed.map(item => `- Issue #${item.issue}: Status ${JSON.stringify(item.fields[request.statusFieldId].name)}; Agent ${JSON.stringify(item.fields[request.agentFieldId].text)}.`).join('\n') : `Pending: ${reason}`;
+  return `${preserved.trimEnd()}\n\n${start}\n## Current Project checkpoint\n\nResult: ${status}\n${rows}\n${end}\n`;
+}
+function apply(request, inspection, config) {
+  for (const value of [request.increment?.agent, request.task?.agent, request.nextAction]) requireValue(typeof value === 'string' && value.trim() && !/[\r\n\0]/.test(value), 'Verified agent/session values and one next action are required.');
+  const current = inspect(request, config);
+  if (!isDeepStrictEqual(current.context, inspection.context)) return { status: 'changed-context', record: request.task.issue, nextAction: 'Read the returned current context and resolve its changes before applying.', ...current };
+  const bound = scope(request, config);
+  const projectId = current.context.project.id;
+  const originalBody = current.context.issues.task.body;
+  bodyFor(originalBody, request, 'pending', [], 'validation');
+  let observed = current.context.items;
+  let failure = '';
+  let operation = '';
+  try {
+    for (const record of [request.increment, request.task]) {
+      for (const [field, flag, value] of [[request.agentFieldId, '--text', record.agent], [request.statusFieldId, '--single-select-option-id', request.statusOptionId]]) {
+        operation = `Issue #${record.issue}, item ${record.itemId}, ${field === request.agentFieldId ? 'Agent' : 'Status'} field ${field}`;
+        const result = call(['project', 'item-edit', '--id', record.itemId, '--field-id', field, '--project-id', projectId, flag, value, '--format', 'json']);
+        if (result.failure) {
+          observed = items(request, bound, projectId);
+          const saved = observed.find(item => item.id === record.itemId).fields[field];
+          if ((flag === '--text' ? saved?.text : saved?.optionId) !== value) throw new Error(result.failure);
+        }
+      }
+    }
+    operation = `Saved Status/Agent readback for issues #${request.increment.issue} and #${request.task.issue}`;
+    observed = items(request, bound, projectId);
+    for (const record of [request.increment, request.task]) {
+      const saved = observed.find(item => item.id === record.itemId).fields;
+      requireValue(saved[request.agentFieldId]?.text === record.agent && saved[request.statusFieldId]?.optionId === request.statusOptionId, `Saved Project fields for issue #${record.issue} do not match the requested state.`);
+    }
+  } catch (error) { failure = `${operation}: ${error.message}`; }
+  const freshBody = json(['issue', 'view', String(request.task.issue), '--repo', bound.repository, '--json', 'body']).body;
+  if (freshBody !== originalBody) return { status: 'changed-context', record: request.task.issue, lastObservedFields: observed, nextAction: 'Preserve the changed task body; inspect it before publishing any checkpoint result.' };
+  const status = failure ? 'pending' : 'synchronized';
+  const body = bodyFor(freshBody, request, status, observed, failure);
+  const written = call(['issue', 'edit', String(request.task.issue), '--repo', bound.repository, '--body-file', '-'], body);
+  const saved = json(['issue', 'view', String(request.task.issue), '--repo', bound.repository, '--json', 'body']).body;
+  if (saved !== body) return { status: 'pending', record: request.task.issue, reason: written.failure || 'Saved issue body does not match the checkpoint update.', lastObservedFields: observed, nextAction: 'Read the saved issue body before deciding on another write.' };
+  return { status, record: request.task.issue, lastObservedFields: observed, ...(failure ? { reason: failure, nextAction: 'Resolve the pending operation before claiming synchronization.' } : {}) };
+}
+
+if (process.argv[2] === '--help') {
+  console.log('Hierarchy: node github-project-checkpoint.mjs inspect-hierarchy REQUEST.json [CONFIG.json]\nInspect: node github-project-checkpoint.mjs inspect REQUEST.json [CONFIG.json]\nApply: node github-project-checkpoint.mjs apply REQUEST.json INSPECTION.json [CONFIG.json]');
+} else {
+  try {
+    const [mode, requestPath, third, fourth] = process.argv.slice(2);
+    requireValue(['inspect', 'apply', 'inspect-hierarchy'].includes(mode), 'Expected inspect-hierarchy, inspect or apply; use --help for usage.');
+    const request = load(requestPath);
+    const config = load((mode === 'apply' ? fourth : third) || '.agents/planning.json');
+    const result = mode === 'inspect-hierarchy' ? inspectHierarchy(request, config) : mode === 'inspect' ? inspect(request, config) : apply(request, load(third), config);
+    console.log(JSON.stringify(result));
+    if (result.status && result.status !== 'synchronized') process.exitCode = 1;
+  } catch (error) {
+    console.log(JSON.stringify(process.argv[2] === 'inspect-hierarchy'
+      ? { status: 'inspection-unavailable', reason: error.message, nextAction: 'Read the affected configuration or record before claiming a completed inspection.' }
+      : { status: 'pending', reason: error.message, nextAction: 'Inspect the affected record and resolve this operation before claiming synchronization.' }));
+    process.exitCode = 1;
+  }
+}

package/skills-codex/outcome-led-planning/references/github-coordination.md

@@ -156,7 +156,7 @@ Use this contribution lifecycle:
 
 A starting battle plan exposes likely work, dependencies and parallel opportunities without precreating, assigning or reserving every future task. The increment owner keeps acceptance, sequence and integration clear and resolves overlap/dependencies. Explicit assignments and handoffs remain valid. Two agents sharing an account are distinct contributors. Checklists suffice for routine steps; do not create a task for every command. Task creation within assessed scope requires no fresh human approval.
 
-**Each agent holds only one contribution task at a time**, including a blocked assignment. Finish, explicitly hand over or release the current assignment before claiming another. Do not reserve queued tasks. Outcome or increment coordination ownership does not reserve contribution tasks. Agents sharing an account remain distinct through their recorded agent/session identities.
+**One contribution claim is a ceiling, not a retention requirement.** A blocked assignment still counts until its release is verified. For an unfinished task, when no useful authorized in-task step remains, hand over the remaining gap, remove your assignment and read back its removal; do not retain it merely because its dependency is unresolved. Preserve genuine assigned watcher duties; routine discussion reads alone do not justify retaining an exhausted reservation. Finish, explicitly hand over or release the current assignment before claiming another. Do not reserve queued tasks. Outcome or increment coordination ownership does not reserve contribution tasks. Agents sharing an account remain distinct through their recorded agent/session identities.
 
 Before declaring a contribution ready to start, complete this claim receipt: **no other contribution assignment held; parent increment; current assessed plan revision; non-overlapping scope; dependencies (or explicitly none); actual account; distinct agent/session; saved claim and reciprocal-link readback; competing-claim recheck.** Record all fields on the task, even when some are already known in conversation. Assignment does not increase authority. When explaining a proposed claim, make these required fields and the before/after overlap checks explicit.
 
@@ -188,15 +188,31 @@ actual acknowledgement.
 
 At each work checkpoint, reconcile tracking in this order:
 
-1. **Establish scope.** Reuse the established backend. Establish Project selection
-   separately from the backend, using configuration, project requirements or
-   explicit direction: selected/required, none, or unresolved. Do not infer none
-   or an unset configuration from omitted information. An established choice to
-   use no Project needs no setup. While selection remains unresolved, inspect available
-   records and keep Project work conditional; do not assert a pending or
-   unsynchronized mirror. An unavailable API or bootstrap default proves neither
-   selection nor a missing view, field or membership; inspect saved setup before
-   naming gaps.
+When the affected records include an outcome, current Now, provisional Next and
+a task, and `gh` works, MUST first use the [read-only hierarchy inspector](github-project-checkpoint.md#inspect-the-hierarchy).
+Construct its request from those actual records and consume its findings before
+claiming completeness; identical draft/remote text is not that comparison.
+Do not manufacture a Next issue for this route. Its configuration report is one
+source for the selection decision below, not proof of capability or acceptance.
+
+1. **Establish selection before checking Project capability.** Reuse the
+   established backend. From configuration, project requirements or explicit
+   direction, choose the applicable branch:
+   - **Selected/required:** verify the repository, Project and account, then
+     inspect its saved setup and applicable operations. For join/resume of an
+     active open task with working `gh`, MUST use the [executable Project checkpoint](github-project-checkpoint.md).
+     Read its inspection and handle current discussion before applying it;
+     do not manually publish synchronization-success text on that route.
+     If an applicable operation is unavailable, retain its exact pending state
+     under the recovery rules below. An unavailable API or bootstrap default
+     does not prove a missing view, field or membership.
+   - **Established none:** continue issue-side reconciliation without Project
+     setup, fields or synchronization.
+   - **Unresolved:** inspect available configuration, requirements, direction and
+     issue records. Record the selection gap and keep Project work conditional;
+     there is no established mirror operation to report pending or unsynchronized.
+     Omitted information and API availability establish neither selection nor
+     an explicit choice to use no Project.
 2. **Inspect each affected record.** Read each outcome, increment and task
    against the minimum-information table above. Preserve its own owner/account,
    applicable agent/session, revision and acceptance; mark missing required

package/skills-codex/outcome-led-planning/references/github-project-checkpoint.md

@@ -0,0 +1,137 @@
+# Inspect and reconcile GitHub records
+
+Resolve `scripts/github-project-checkpoint.mjs` relative to this installed
+planning skill, including when called from `contribute`. Use the existing
+authenticated `gh` account and saved project configuration. The default is
+`.agents/planning.json`; an existing project-declared configuration path may be
+supplied last. These operations require no new grants, account changes or tokens.
+Local tracking keeps its existing path.
+
+## Inspect the hierarchy
+
+When reconciling an outcome, current Now, an affected provisional Next and a
+task together with working `gh`, planning and `contribute` MUST first use the
+read-only hierarchy inspector. Supply those actual distinct issue numbers;
+do not invent a Next issue to satisfy the command. Other record sets retain
+their existing coordination path.
+
+```json
+{
+  "outcome": 1,
+  "increment": {"issue": 2},
+  "next": {"issue": 3},
+  "task": {"issue": 4}
+}
+```
+
+Run `node <installed-planning-skill>/scripts/github-project-checkpoint.mjs inspect-hierarchy request.json`.
+This reads the four actual issues and their returned comments. It writes
+nothing and makes no Project or native-link request. Read the raw records and
+consume `findings` before claiming that the records are correct:
+
+- `projectSelection` reports configuration facts. `not-recorded` means selection
+  is unresolved from that configuration, not an explicit choice to use no
+  Project. `recorded` does not prove capability; consider actual project
+  requirements and explicit direction too. Preserve invalid configuration.
+- Each record's `inspection` reports literal owner, revision, acceptance and
+  Parent candidates with raw line evidence. `candidate` is text, not verified
+  ownership or passed acceptance. `explicitly-unresolved` preserves a recorded
+  unknown. Empty/missing literals, unsupported syntax and multiple candidates
+  remain unestablished by this inspector; they do not prove semantic information
+  is absent or that the issue is invalid. Inspect the actual prose/history
+  rather than forcing a new format or choosing a historical value.
+- `textLinks` compares the three requested textual relationships. A mention is
+  observed text, not proof of a current native relationship. Inspect both sides
+  and repair known reciprocal gaps under the existing coordination rules.
+- `capabilities` are `not-probed`; do not turn that into an outage or native-link
+  absence. `inspection-unavailable` means the read/report operation failed,
+  not that a Project mirror is pending.
+
+A successful command produces a diagnostic report, never a correctness or
+synchronization verdict. Identical drafts and saved bodies do not establish
+completeness. Before claiming completeness, account for every finding through
+actual semantic review, authorized repair with saved readback where needed, or
+honest unresolved recording in the existing plan or record. Follow the selection
+finding's conditional next action, which targets the existing outcome issue
+for saving and reading back a still-unresolved gap. Reuse an already saved gap
+without an unchanged write. Configuration alone may leave the choice unresolved
+while requirements or explicit direction establish it. Unsupported
+syntax does not force normalization or another artifact.
+Apply the existing per-record rules to known gaps, marking missing
+required information unresolved rather than inventing it; preserve completed
+acceptance and attribution. Read back authorized changes and compare reciprocal
+links before reporting reconciliation. Unsupported syntax needs actual review,
+not automatic normalization. Semantic acceptance remains with the caller and
+required independent review.
+
+## Synchronize selected Project fields
+
+For a join/resume checkpoint on an active open task with a selected GitHub Project and working `gh`,
+planning and `contribute` MUST use the bundled
+`scripts/github-project-checkpoint.mjs` operation. Do not manually publish a
+Project synchronization-success claim on this route. The operation reads the
+records/discussion, updates the two items, verifies their saved fields and only
+then generates the task's synchronization result. It does not allocate owners,
+approve a plan, acknowledge another person or complete the increment.
+
+This mutation route applies to its open outcome, increment and active task.
+GitHub Issues-only tracking uses no Project field mutations.
+
+## Inspect, decide, apply
+
+Create a request from the actual records and Project fields. IDs below are
+placeholders. Preserve each record's own verified agent/session; do not copy the
+task contributor onto the increment. The status option must be the existing
+In progress equivalent, never Done.
+
+```json
+{
+  "outcome": 1,
+  "increment": {"issue": 2, "itemId": "INCREMENT_ITEM_ID", "agent": "verified increment owner/session"},
+  "task": {"issue": 4, "itemId": "TASK_ITEM_ID", "agent": "verified task owner/session"},
+  "statusFieldId": "STATUS_FIELD_ID",
+  "agentFieldId": "AGENT_FIELD_ID",
+  "statusOptionId": "IN_PROGRESS_OPTION_ID",
+  "nextAction": "the actual next step in this task"
+}
+```
+
+1. Run `node <installed-planning-skill>/scripts/github-project-checkpoint.mjs inspect request.json`.
+   The default configuration is `.agents/planning.json` in the project. An
+   existing project-declared configuration path may be supplied as the final
+   argument. Save the returned JSON in a permitted working location.
+2. Read that inspection, including the increment discussion, current revision,
+   dependencies and claims. Acknowledge relevant handoffs through the authorized
+   channel and resolve overlap or material changes under the existing rules.
+   The operation reading a comment does not mean its recipient acknowledged it.
+   If that work changes these records, inspect again before applying.
+3. Run `node <installed-planning-skill>/scripts/github-project-checkpoint.mjs apply request.json inspection.json`.
+   Supply the same explicit configuration path last when one was used above.
+   The operation rechecks inspected context, updates only task/increment
+   Status/Agent, reads back the actual fields, then publishes generated task
+   progress and reads it back. It preserves Horizon and the rest of the brief.
+   The current brief needs a literal `Next action:` line; if absent, maintain
+   that field truthfully before inspecting again. Do not erase existing content.
+
+Use direct commands with literal paths supported by the runtime permissions.
+Do not infer unavailable authority from one rejected compound command when an
+already-authorized direct invocation remains available.
+
+## Read the result
+
+- `synchronized`: the requested fields and generated task update were read back.
+  This establishes this checkpoint only, not task or increment completion.
+- `changed-context`: inspect the returned facts and resolve the change. A body
+  changed before publication stays untouched, even if fields already changed.
+- `pending`: keep the precise affected operation and next action visible. A
+  partial or ambiguous field result cannot generate synchronization success.
+  The operation reads saved state before resolving uncertain writes and never
+  automatically repeats a mutation. If the pending note itself could not be
+  saved, its output does not prove the issue was updated.
+
+Do not treat an exit code, assignment or local note as a saved-field result.
+Keep useful authorized issue work moving while Project work is pending. If
+`gh` or this operation is unavailable, use other already-authorized capabilities
+under the coordination protocol, preserving the same truthful claim dependency.
+Do not request broader access while an existing authorized route works, or
+claim the executable operation enforced an untested browser/manual path.

package/skills-codex/outcome-led-planning/scripts/github-project-checkpoint.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { isDeepStrictEqual } from 'node:util';
+
+const itemQuery = `query($ids:[ID!]!,$agentFieldId:ID!){nodes(ids:$ids){... on ProjectV2Item{
+  id project{id url} content{... on Issue{number url parent{number url}}}
+  fieldValues(first:100){nodes{... on ProjectV2ItemFieldSingleSelectValue{
+    optionId name field{... on ProjectV2SingleSelectField{id}}
+  } ... on ProjectV2ItemFieldTextValue{text field{... on ProjectV2Field{id}}}}
+  pageInfo{hasNextPage}}
+}} agentField:node(id:$agentFieldId){... on ProjectV2Field{dataType}}}`;
+const start = '<!-- outcome-led-planning:project-checkpoint:start -->';
+const end = '<!-- outcome-led-planning:project-checkpoint:end -->';
+const load = path => JSON.parse(readFileSync(path, 'utf8'));
+const requireValue = (ok, message) => { if (!ok) throw new Error(message); };
+
+function call(args, input) {
+  const result = spawnSync('gh', args, { input, encoding: 'utf8', timeout: 60000 });
+  return { ...result, failure: result.error?.message || (result.status !== 0 ? result.stderr.trim() || `gh exited ${result.status}` : '') };
+}
+function json(args, input) {
+  const result = call(args, input);
+  if (result.failure) throw new Error(result.failure);
+  const value = JSON.parse(result.stdout);
+  if (value.errors?.length) throw new Error(value.errors.map(error => error.message).join('; '));
+  return value;
+}
+function repositoryFor(config) {
+  requireValue(config?.version === 1 && config.backend === 'github', 'This operation requires the saved GitHub backend.');
+  const repository = config.github?.repository;
+  requireValue(typeof repository === 'string' && /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\/[\w.-]+$/.test(repository) && !['.', '..'].includes(repository.split('/')[1]), 'Invalid configured GitHub repository.');
+  return repository;
+}
+function scope(request, config) {
+  const repository = repositoryFor(config);
+  const url = new URL(config.github?.projectUrl);
+  const match = url.pathname.match(/^\/(?:users|orgs)\/([\w.-]+)\/projects\/([1-9]\d*)(?:\/views\/[1-9]\d*)?\/?$/);
+  requireValue(url.protocol === 'https:' && url.hostname === 'github.com' && match && !url.username && !url.password, 'A selected GitHub Project URL is required.');
+  requireValue([request.outcome, request.increment?.issue, request.task?.issue].every(n => Number.isSafeInteger(n) && n > 0), 'Outcome, increment and task issue numbers are required.');
+  requireValue(new Set([request.outcome, request.increment.issue, request.task.issue]).size === 3, 'The three issue roles must be distinct.');
+  for (const value of [request.increment.itemId, request.task.itemId, request.statusFieldId, request.agentFieldId, request.statusOptionId]) {
+    requireValue(typeof value === 'string' && value.length > 0 && !/[\r\n\0]/.test(value), 'Existing item, field and option IDs are required.');
+  }
+  requireValue(request.increment.itemId !== request.task.itemId && request.statusFieldId !== request.agentFieldId, 'Item and field roles must be distinct.');
+  return { repository, owner: match[1], number: match[2], projectUrl: `https://github.com${url.pathname.split('/views/')[0].replace(/\/$/, '')}` };
+}
+function issue(number, bound) {
+  return json(['issue', 'view', String(number), '--repo', bound.repository, '--json', 'number,url,body,state,assignees,labels,comments']);
+}
+function briefField(body, pattern, cue) {
+  // shortcut: observed literal brief fields only; extend when an actual brief needs another syntax.
+  const lines = body.split(/\r?\n/).map((text, index) => ({ line: index + 1, text }));
+  const matches = lines.flatMap(line => {
+    const match = line.text.match(pattern);
+    return match ? [{ ...line, value: match[1].trim() }] : [];
+  });
+  const literalEvidence = matches.map(({ line, text }) => ({ line, text }));
+  if (matches.length > 1) return { state: 'multiple-candidates', evidence: literalEvidence };
+  if (matches.length === 1) {
+    const { value } = matches[0];
+    return { state: !value ? 'empty' : /^(?:unresolved|unknown|tbd|unclaimed)(?:\b|$)/i.test(value) ? 'explicitly-unresolved' : 'candidate', value, evidence: literalEvidence };
+  }
+  const evidence = lines.filter(line => cue.test(line.text));
+  return { state: evidence.length ? 'unsupported-format' : 'literal-field-missing', evidence };
+}
+function textReference(body, number, repository) {
+  const escaped = repository.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const reference = new RegExp(`(?:(?<![\\w./#:-])#${number}\\b|https://github\\.com/${escaped}/issues/${number}(?![\\w/]))`, 'i');
+  const evidence = body.split(/\r?\n/).flatMap((text, index) => reference.test(text) ? [{ line: index + 1, text }] : []);
+  return { observed: evidence.length > 0, evidence };
+}
+function inspectHierarchy(request, config) {
+  const repository = repositoryFor(config);
+  const roles = { outcome: request?.outcome, increment: request?.increment?.issue, next: request?.next?.issue, task: request?.task?.issue };
+  requireValue(Object.values(roles).every(n => Number.isSafeInteger(n) && n > 0) && new Set(Object.values(roles)).size === 4, 'Four distinct outcome, increment, next and task issue numbers are required.');
+  const projectSelection = { state: 'not-recorded', source: 'configuration' };
+  if (Object.hasOwn(config.github, 'projectUrl')) {
+    try {
+      const url = new URL(config.github.projectUrl);
+      requireValue(url.protocol === 'https:' && url.hostname === 'github.com' && !url.username && !url.password && !url.search && !url.hash && /^\/(?:users|orgs)\/[\w.-]+\/projects\/[1-9]\d*(?:\/views\/[1-9]\d*)?\/?$/.test(url.pathname), 'Invalid recorded Project URL.');
+      Object.assign(projectSelection, { state: 'recorded', url: `https://github.com${url.pathname.split('/views/')[0].replace(/\/$/, '')}` });
+    } catch { projectSelection.state = 'invalid'; }
+  }
+  const records = {};
+  const findings = projectSelection.state === 'recorded' ? [] : [{ issue: roles.outcome, field: 'projectSelection', state: projectSelection.state, nextAction: `Establish selection from applicable project requirements and explicit direction. If it remains unresolved, save that selection gap and conditional Project work on outcome #${roles.outcome} and read back its saved body before claiming reconciliation complete. Reuse an already saved gap without an unchanged write.` }];
+  for (const [role, number] of Object.entries(roles)) {
+    const record = issue(number, { repository });
+    requireValue(record.number === number && record.url?.toLowerCase() === `https://github.com/${repository}/issues/${number}`.toLowerCase() && typeof record.body === 'string', 'Returned issue does not match its requested repository/number or brief.');
+    const inspection = {
+      owner: briefField(record.body, /^\s*(?:(?:Outcome|Increment|Task) )?Owner:\s*(.*)$/i, /\bowner\b/i),
+      revision: briefField(record.body, /^\s*Revision:\s*(.*)$/i, /\brevision\b/i),
+      acceptance: briefField(record.body, /^\s*(?:Tentative )?Acceptance(?: criteria| evidence)?:\s*(.*)$/i, /\bacceptance\b/i),
+      parent: briefField(record.body, /^\s*Parent(?: outcome| increment)?:\s*(.*)$/i, /\bparent\b/i)
+    };
+    records[role] = { ...record, inspection };
+    for (const field of ['owner', 'revision', 'acceptance']) {
+      if (!['candidate', 'explicitly-unresolved'].includes(inspection[field].state)) findings.push({ issue: number, field, state: inspection[field].state });
+    }
+  }
+  const textLinks = [[records.outcome, records.increment], [records.outcome, records.next], [records.increment, records.task]].map(([parent, child]) => {
+    const parentMentionsChild = textReference(parent.body, child.number, repository);
+    const field = child.inspection.parent;
+    const referencesExpected = 'value' in field ? textReference(field.value, parent.number, repository).observed : null;
+    if (!parentMentionsChild.observed) findings.push({ issue: parent.number, field: 'child-text-reference', state: 'not-established', child: child.number });
+    if (referencesExpected !== true) findings.push({ issue: child.number, field: 'parent-text-reference', state: 'not-established', parent: parent.number });
+    return { parent: parent.number, child: child.number, parentMentionsChild, childParent: { ...field, referencesExpected } };
+  });
+  return { repository, projectSelection, capabilities: { project: 'not-probed', nativeLinks: 'not-probed' }, records, textLinks, findings };
+}
+function items(request, bound, projectId) {
+  const response = json(['api', 'graphql', '--input', '-'], JSON.stringify({ query: itemQuery, variables: { ids: [request.increment.itemId, request.task.itemId], agentFieldId: request.agentFieldId } }));
+  requireValue(response.data.agentField?.dataType === 'TEXT', 'The Agent field must be a text field.');
+  return response.data.nodes.map((item, index) => {
+    const record = index === 0 ? request.increment : request.task;
+    const parent = index === 0 ? request.outcome : request.increment.issue;
+    const expected = `https://github.com/${bound.repository}/issues/${record.issue}`;
+    requireValue(item && item.id === record.itemId && item.project.id === projectId && item.project.url === bound.projectUrl, 'Project item does not belong to the selected Project.');
+    requireValue(item.content?.url.toLowerCase() === expected.toLowerCase() && item.content.parent?.number === parent && item.content.parent.url.toLowerCase() === `https://github.com/${bound.repository}/issues/${parent}`.toLowerCase(), 'Current native issue parent or repository does not match the requested hierarchy.');
+    requireValue(!item.fieldValues.pageInfo.hasNextPage, 'Project field response is incomplete; inspect the remaining fields before applying.');
+    return { id: item.id, issue: record.issue, fields: Object.fromEntries(item.fieldValues.nodes.filter(value => value.field?.id).map(value => [value.field.id, 'text' in value ? { text: value.text } : { optionId: value.optionId, name: value.name }]).sort(([a], [b]) => a.localeCompare(b))) };
+  });
+}
+function inspect(request, config) {
+  const bound = scope(request, config);
+  const actor = json(['api', 'user']).login;
+  const project = json(['project', 'view', bound.number, '--owner', bound.owner, '--format', 'json']);
+  requireValue(project.url === bound.projectUrl && !project.closed, 'Selected Project is unavailable or closed.');
+  const allFields = json(['project', 'field-list', bound.number, '--owner', bound.owner, '--format', 'json']).fields;
+  const status = allFields.find(field => field.id === request.statusFieldId);
+  const agent = allFields.find(field => field.id === request.agentFieldId);
+  const option = status?.options?.find(value => value.id === request.statusOptionId);
+  requireValue(status?.name === 'Status' && status.type === 'ProjectV2SingleSelectField' && agent?.name === 'Agent' && agent.type === 'ProjectV2Field' && option, 'Requested fields must be the selected Project Status and Agent fields.');
+  requireValue(option.name.replace(/[-_\s]/g, '').toLowerCase() === 'inprogress', 'A resume checkpoint requires the existing In progress status option.');
+  const records = { outcome: issue(request.outcome, bound), increment: issue(request.increment.issue, bound), task: issue(request.task.issue, bound) };
+  requireValue(Object.values(records).every(record => record.state === 'OPEN'), 'This resume operation requires open outcome, increment and task records.');
+  return { context: { actor, repository: bound.repository, project: { id: project.id, url: project.url }, fields: { status: { id: status.id, option }, agent: { id: agent.id } }, issues: records, items: items(request, bound, project.id) } };
+}
+function bodyFor(body, request, status, observed, reason) {
+  // shortcut: only the observed literal Next action line; extend when an adopter needs another brief format.
+  requireValue(/^Next action:[^\r\n]*/m.test(body), 'Task brief needs its current literal Next action line; no body changes were made.');
+  const first = body.indexOf(start);
+  const last = body.indexOf(end);
+  requireValue((first === -1 && last === -1) || (first >= 0 && last > first && body.indexOf(start, first + 1) === -1 && body.indexOf(end, last + 1) === -1), 'Existing checkpoint block is malformed; preserve the body and repair that block first.');
+  let preserved = first < 0 ? body : body.slice(0, first) + body.slice(last + end.length);
+  const next = status === 'synchronized' ? request.nextAction : `Resolve the pending Project checkpoint: ${reason}`;
+  preserved = preserved.replace(/^Next action:[^\r\n]*/m, () => `Next action: ${next}`);
+  const rows = status === 'synchronized' ? observed.map(item => `- Issue #${item.issue}: Status ${JSON.stringify(item.fields[request.statusFieldId].name)}; Agent ${JSON.stringify(item.fields[request.agentFieldId].text)}.`).join('\n') : `Pending: ${reason}`;
+  return `${preserved.trimEnd()}\n\n${start}\n## Current Project checkpoint\n\nResult: ${status}\n${rows}\n${end}\n`;
+}
+function apply(request, inspection, config) {
+  for (const value of [request.increment?.agent, request.task?.agent, request.nextAction]) requireValue(typeof value === 'string' && value.trim() && !/[\r\n\0]/.test(value), 'Verified agent/session values and one next action are required.');
+  const current = inspect(request, config);
+  if (!isDeepStrictEqual(current.context, inspection.context)) return { status: 'changed-context', record: request.task.issue, nextAction: 'Read the returned current context and resolve its changes before applying.', ...current };
+  const bound = scope(request, config);
+  const projectId = current.context.project.id;
+  const originalBody = current.context.issues.task.body;
+  bodyFor(originalBody, request, 'pending', [], 'validation');
+  let observed = current.context.items;
+  let failure = '';
+  let operation = '';
+  try {
+    for (const record of [request.increment, request.task]) {
+      for (const [field, flag, value] of [[request.agentFieldId, '--text', record.agent], [request.statusFieldId, '--single-select-option-id', request.statusOptionId]]) {
+        operation = `Issue #${record.issue}, item ${record.itemId}, ${field === request.agentFieldId ? 'Agent' : 'Status'} field ${field}`;
+        const result = call(['project', 'item-edit', '--id', record.itemId, '--field-id', field, '--project-id', projectId, flag, value, '--format', 'json']);
+        if (result.failure) {
+          observed = items(request, bound, projectId);
+          const saved = observed.find(item => item.id === record.itemId).fields[field];
+          if ((flag === '--text' ? saved?.text : saved?.optionId) !== value) throw new Error(result.failure);
+        }
+      }
+    }
+    operation = `Saved Status/Agent readback for issues #${request.increment.issue} and #${request.task.issue}`;
+    observed = items(request, bound, projectId);
+    for (const record of [request.increment, request.task]) {
+      const saved = observed.find(item => item.id === record.itemId).fields;
+      requireValue(saved[request.agentFieldId]?.text === record.agent && saved[request.statusFieldId]?.optionId === request.statusOptionId, `Saved Project fields for issue #${record.issue} do not match the requested state.`);
+    }
+  } catch (error) { failure = `${operation}: ${error.message}`; }
+  const freshBody = json(['issue', 'view', String(request.task.issue), '--repo', bound.repository, '--json', 'body']).body;
+  if (freshBody !== originalBody) return { status: 'changed-context', record: request.task.issue, lastObservedFields: observed, nextAction: 'Preserve the changed task body; inspect it before publishing any checkpoint result.' };
+  const status = failure ? 'pending' : 'synchronized';
+  const body = bodyFor(freshBody, request, status, observed, failure);
+  const written = call(['issue', 'edit', String(request.task.issue), '--repo', bound.repository, '--body-file', '-'], body);
+  const saved = json(['issue', 'view', String(request.task.issue), '--repo', bound.repository, '--json', 'body']).body;
+  if (saved !== body) return { status: 'pending', record: request.task.issue, reason: written.failure || 'Saved issue body does not match the checkpoint update.', lastObservedFields: observed, nextAction: 'Read the saved issue body before deciding on another write.' };
+  return { status, record: request.task.issue, lastObservedFields: observed, ...(failure ? { reason: failure, nextAction: 'Resolve the pending operation before claiming synchronization.' } : {}) };
+}
+
+if (process.argv[2] === '--help') {
+  console.log('Hierarchy: node github-project-checkpoint.mjs inspect-hierarchy REQUEST.json [CONFIG.json]\nInspect: node github-project-checkpoint.mjs inspect REQUEST.json [CONFIG.json]\nApply: node github-project-checkpoint.mjs apply REQUEST.json INSPECTION.json [CONFIG.json]');
+} else {
+  try {
+    const [mode, requestPath, third, fourth] = process.argv.slice(2);
+    requireValue(['inspect', 'apply', 'inspect-hierarchy'].includes(mode), 'Expected inspect-hierarchy, inspect or apply; use --help for usage.');
+    const request = load(requestPath);
+    const config = load((mode === 'apply' ? fourth : third) || '.agents/planning.json');
+    const result = mode === 'inspect-hierarchy' ? inspectHierarchy(request, config) : mode === 'inspect' ? inspect(request, config) : apply(request, load(third), config);
+    console.log(JSON.stringify(result));
+    if (result.status && result.status !== 'synchronized') process.exitCode = 1;
+  } catch (error) {
+    console.log(JSON.stringify(process.argv[2] === 'inspect-hierarchy'
+      ? { status: 'inspection-unavailable', reason: error.message, nextAction: 'Read the affected configuration or record before claiming a completed inspection.' }
+      : { status: 'pending', reason: error.message, nextAction: 'Inspect the affected record and resolve this operation before claiming synchronization.' }));
+    process.exitCode = 1;
+  }
+}