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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "3.4.0-preview.1368",
+  "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,21 +188,31 @@ actual acknowledgement.
 
 At each work checkpoint, reconcile tracking in this order:
 
-For a join/resume checkpoint with a selected Project and 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. Other checkpoints and
-authorized alternatives retain the rules below.
-
-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

@@ -1,6 +1,72 @@
-# Execute a selected-Project resume checkpoint
+# Inspect and reconcile GitHub records
 
-For a join/resume checkpoint with a selected GitHub Project and working `gh`,
+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
@@ -8,10 +74,8 @@ 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.
 
-Resolve the script relative to this installed planning skill, including when
-called from `contribute`. Use the existing authenticated `gh` account and saved
-project configuration; no new grants, account changes or tokens are required by
-the operation. Local and GitHub Issues-only tracking keep their existing paths.
+This mutation route applies to its open outcome, increment and active task.
+GitHub Issues-only tracking uses no Project field mutations.
 
 ## Inspect, decide, apply
 

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

@@ -26,10 +26,14 @@ function json(args, input) {
   if (value.errors?.length) throw new Error(value.errors.map(error => error.message).join('; '));
   return value;
 }
-function scope(request, config) {
-  requireValue(config.version === 1 && config.backend === 'github', 'This operation requires the saved GitHub backend.');
+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' && /^[\w.-]+\/[\w.-]+$/.test(repository), 'Invalid configured 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.');
@@ -44,6 +48,66 @@ function scope(request, config) {
 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.');
@@ -125,18 +189,20 @@ function apply(request, inspection, config) {
 }
 
 if (process.argv[2] === '--help') {
-  console.log('Inspect: node github-project-checkpoint.mjs inspect REQUEST.json [CONFIG.json]\nApply: node github-project-checkpoint.mjs apply REQUEST.json INSPECTION.json [CONFIG.json]');
+  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(mode === 'inspect' || mode === 'apply', 'Expected inspect or apply; use --help for usage.');
+    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 === 'inspect' ? third : fourth) || '.agents/planning.json');
-    const result = mode === 'inspect' ? inspect(request, config) : apply(request, load(third), config);
+    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({ status: 'pending', reason: error.message, nextAction: 'Inspect the affected record and resolve this operation before claiming synchronization.' }));
+    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,21 +188,31 @@ actual acknowledgement.
 
 At each work checkpoint, reconcile tracking in this order:
 
-For a join/resume checkpoint with a selected Project and 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. Other checkpoints and
-authorized alternatives retain the rules below.
-
-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

@@ -1,6 +1,72 @@
-# Execute a selected-Project resume checkpoint
+# Inspect and reconcile GitHub records
 
-For a join/resume checkpoint with a selected GitHub Project and working `gh`,
+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
@@ -8,10 +74,8 @@ 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.
 
-Resolve the script relative to this installed planning skill, including when
-called from `contribute`. Use the existing authenticated `gh` account and saved
-project configuration; no new grants, account changes or tokens are required by
-the operation. Local and GitHub Issues-only tracking keep their existing paths.
+This mutation route applies to its open outcome, increment and active task.
+GitHub Issues-only tracking uses no Project field mutations.
 
 ## Inspect, decide, apply
 

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

@@ -26,10 +26,14 @@ function json(args, input) {
   if (value.errors?.length) throw new Error(value.errors.map(error => error.message).join('; '));
   return value;
 }
-function scope(request, config) {
-  requireValue(config.version === 1 && config.backend === 'github', 'This operation requires the saved GitHub backend.');
+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' && /^[\w.-]+\/[\w.-]+$/.test(repository), 'Invalid configured 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.');
@@ -44,6 +48,66 @@ function scope(request, config) {
 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.');
@@ -125,18 +189,20 @@ function apply(request, inspection, config) {
 }
 
 if (process.argv[2] === '--help') {
-  console.log('Inspect: node github-project-checkpoint.mjs inspect REQUEST.json [CONFIG.json]\nApply: node github-project-checkpoint.mjs apply REQUEST.json INSPECTION.json [CONFIG.json]');
+  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(mode === 'inspect' || mode === 'apply', 'Expected inspect or apply; use --help for usage.');
+    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 === 'inspect' ? third : fourth) || '.agents/planning.json');
-    const result = mode === 'inspect' ? inspect(request, config) : apply(request, load(third), config);
+    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({ status: 'pending', reason: error.message, nextAction: 'Inspect the affected record and resolve this operation before claiming synchronization.' }));
+    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;
   }
 }