[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M754T3GM3M60DV7SFG2GXHB4":3,"skill-same:01M754T3GM3M60DV7SFG2GXHB4":53},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":30,"commitSha":31,"skillDirectory":32,"forksCount":33,"repositoryHtmlUrl":34,"repositoryHomepageUrl":6,"ownerHtmlUrl":35,"ownerBlogUrl":36,"ownerDescription":37,"updatedAt":38,"install":39,"resources":52},"01M754T3GM3M60DV7SFG2GXHB4","x-internal-update-status",null,"Atomic read-modify-write of execution-state.json with flock-based concurrency, schema validation, and idempotency detection. Substitutes inline Edit-based mutations in orchestrator skills (x-implement-epic, x-implement-story, x-fix-epic-pr) that previously suffered race conditions in --parallel mode. PILOT skill for the x-internal-* convention: internal visibility, non-user-invocable, subdir scoping under internal\u002Fops\u002F.","review-bench\u002Federcnj_ia-dev-environment","review-bench","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F286778065?v=4","01M7517F9NTEPDZDAXJBR30FWT","ReviewBench","01M7517FAC9F4P7TGWCNJ8VYVW",0,"MIT","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring-fintech-pci\u002F.claude\u002Fskills\u002Fx-internal-update-status\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: x-internal-update-status\ndescription: \"Atomic read-modify-write of execution-state.json with flock-based concurrency, schema validation, and idempotency detection. Substitutes inline Edit-based mutations in orchestrator skills (x-implement-epic, x-implement-story, x-fix-epic-pr) that previously suffered race conditions in --parallel mode. PILOT skill for the x-internal-* convention: internal visibility, non-user-invocable, subdir scoping under internal\u002Fops\u002F.\"\nvisibility: internal\nuser-invocable: false\nallowed-tools: Bash\nargument-hint: \"--file \u003Cpath> --type \u003Cepic|story|task> --id \u003Cid> --field \u003Cname> --value \u003Cvalue> [--initialize] [--read-only]\"\ncategory: internal-ops\ncontext-budget: medium\nrequires-capabilities: []\n---\n\n## Global Output Policy\n\n- **Language**: English ONLY.\n- **Tone**: Technical, Direct, and Concise.\n- **Efficiency**: Remove all conversational fillers and greetings to save tokens.\n\n> 🔒 **INTERNAL SKILL**\n> Esta skill é invocada apenas por outras skills (orquestradores).\n> NÃO é destinada a invocação direta pelo usuário.\n> Caller principal: x-implement-epic, x-implement-story, x-fix-epic-pr.\n> Esta é a story PILOTO (story-0049-0005) da convenção `x-internal-*`:\n> frontmatter `visibility: internal`, subdir `internal\u002Fops\u002F`, marker 🔒, e\n> filtragem do menu `\u002Fhelp` via generator.\n\n# Skill: x-internal-update-status\n\n## Purpose\n\nPerform atomic read-modify-write mutations of\n`ai\u002Fepics\u002Fepic-XXXX\u002Fexecution-state.json` (the telemetry checkpoint file\nconsumed by every orchestrator skill). The operation:\n\n1. Acquires a `flock`-based advisory lock with 30s timeout.\n2. Reads the full JSON document.\n3. Validates the resolved path exists in the schema.\n4. Compares `previousValue` vs `newValue` — emits `noOp=true` when equal\n   (idempotency per RULE-002).\n5. Writes via tmp-file + rename (atomic on POSIX).\n6. Releases the lock.\n\nThis replaces ad-hoc `Edit`-tool invocations from inside orchestrators,\nwhich historically lost updates under `--parallel` execution (documented\nin EPIC-0042 post-mortems).\n\n## Convention Anchors (x-internal-* PILOT)\n\n| Aspect | Value | Rationale |\n| :--- | :--- | :--- |\n| Path | `internal\u002Fops\u002Fx-internal-update-status\u002F` | `internal\u002F` prefix scopes visibility; `ops\u002F` aligns with sibling runtime-ops skills |\n| Frontmatter `visibility` | `internal` | Generator filters these from `\u002Fhelp` menu |\n| Frontmatter `user-invocable` | `false` | Declarative complement to `visibility: internal` |\n| Body marker | `> 🔒 **INTERNAL SKILL**` block as first non-frontmatter content | Visible to humans browsing the repo; no parsing required |\n| Allowed tools | `Bash` only | Minimal surface; all logic is a single shell pipeline |\n| Naming | `x-internal-{subject}-{action}` | Mirrors Rule 04 skill taxonomy; `status-update` = subject+action |\n\nAudit rule: Rule 22 (Lifecycle Integrity) validates every skill under\n`internal\u002F**` satisfies all 6 anchors above. Violations fail the\n`LifecycleIntegrityAuditTest`.\n\n## Triggers\n\nBare-slash form is intentionally omitted — this skill is never invoked\nby a human typing `\u002Fx-internal-update-status` in chat. All invocations\nfollow Rule 13 INLINE-SKILL pattern from a calling orchestrator:\n\n```markdown\nSkill(skill: \"x-internal-update-status\",\n      args: \"--file ai\u002Fepics\u002Fepic-XXXX\u002Fexecution-state.json \\\n             --type story --id story-0049-0005 \\\n             --field status --value MERGED\")\n```\n\n## Parameters\n\n| Parameter | Required | Default | Description |\n| :--- | :--- | :--- | :--- |\n| `--file \u003Cpath>` | O | `execution-state.json` in cwd | Target state file |\n| `--type \u003Cepic\\|story\\|task>` | M | — | Scope of the node being mutated |\n| `--id \u003Cid>` | M | — | Epic ID (`0049`), story ID (`story-0049-0005`), or task ID (`TASK-0049-0005-001`) |\n| `--field \u003Cname>` | M | — | Schema field to update (e.g., `status`, `prNumber`, `commitSha`) |\n| `--value \u003Cvalue>` | M | — | New value; coerced to the schema-declared type |\n| `--initialize` | O | `false` | Create the file with an empty schema skeleton when absent |\n| `--read-only` | O | `false` | Read and return the current value without acquiring the write lock |\n\n## Response Contract\n\nWhen successful, the skill writes a single-line JSON object to stdout:\n\n| Field | Type | Always Present | Description |\n| :--- | :--- | :--- | :--- |\n| `previousValue` | `String\\|Null` | yes | Value before write; null when field was absent |\n| `newValue` | `String` | yes | Value after write (equal to previous on no-op) |\n| `fileSha` | `String(64)` | yes | sha256 of the file after the write |\n| `noOp` | `Boolean` | yes | `true` when `previousValue == newValue` |\n\n## Exit Codes\n\n| Code | Name | Condition | Message Format |\n| :--- | :--- | :--- | :--- |\n| 0 | SUCCESS | Write or no-op completed | — |\n| 1 | FILE_NOT_FOUND | File missing and `--initialize=false` | `State file not found: \u003Cpath>` |\n| 2 | LOCK_TIMEOUT | `flock` timed out after 30s | `Lock timeout on \u003Cpath>.lock` |\n| 3 | INVALID_PATH | `--type\u002F--id\u002F--field` tuple does not resolve | `Path '\u003Cresolved-path>' not found in schema` |\n| 4 | WRITE_FAILED | Atomic `mv` of tmp file failed | `Atomic write failed: \u003Cstderr>` |\n\n## Workflow\n\n### Step 1 — Argument parsing and validation\n\nParse flags; reject unknown flags; enforce mutual exclusivity of\n`--read-only` with any write-implying flag combination. When\n`--type=epic`, the resolved path is `\u003Cfield>` at document root; when\n`--type=story`, the path is `stories.\u003Cid>.\u003Cfield>`; when `--type=task`,\nthe path is `stories.\u003CparentStoryId>.tasks.\u003Cid>.\u003Cfield>`. Parent story\nID is inferred from the task ID prefix (`TASK-0049-0005-001` ⇒\n`story-0049-0005`).\n\n### Step 2 — Lock acquisition\n\n```bash\nlock_file=\"${file}.lock\"\nexec {fd}>\"${lock_file}\"\nif ! flock -w 30 \"${fd}\"; then\n  echo \"Lock timeout on ${lock_file}\" >&2\n  exit 2\nfi\n```\n\n### Step 3 — File existence and initialization\n\n- When the file is absent and `--initialize=false`: exit 1.\n- When absent and `--initialize=true`: write an empty skeleton\n  `{\"version\":1,\"stories\":{}}` via the same atomic tmp+rename contract\n  before proceeding.\n\n### Step 4 — Read and validate path\n\nParse JSON via `jq`; resolve the path per Step 1. When the path does\nnot exist, exit 3 with the resolved path in the message.\n\n### Step 5 — Idempotency check\n\nCompute `previousValue` at the resolved path. When\n`previousValue == newValue`, emit the response JSON with `noOp=true`\nand exit 0 without touching the file. The lock is still released via\n`flock` descriptor closure.\n\n### Step 6 — Atomic write\n\n```bash\ntmp=\"${file}.tmp.$$\"\njq --arg v \"${newValue}\" \"\u003Cpath-expression>\" \"${file}\" > \"${tmp}\"\nif ! mv \"${tmp}\" \"${file}\"; then\n  rm -f \"${tmp}\"\n  echo \"Atomic write failed: mv returned non-zero\" >&2\n  exit 4\nfi\n```\n\n### Step 7 — Emit response and release lock\n\n```bash\nfile_sha=$(shasum -a 256 \"${file}\" | cut -d' ' -f1)\nprintf '{\"previousValue\":%s,\"newValue\":\"%s\",\"fileSha\":\"%s\",\"noOp\":false}\\n' \\\n  \"${prev_json}\" \"${newValue}\" \"${file_sha}\"\n```\n\nThe `flock` descriptor is closed on process exit; no explicit unlock\nis required.\n\n### Step 8 — `--read-only` short-circuit\n\nWhen `--read-only=true`, Steps 2, 6, and 7 are skipped. The skill\nopens the file with a shared (`flock -s`) lock, reads the value,\nemits the response with `noOp=true` and `newValue==previousValue`,\nand exits 0.\n\n## Examples\n\n### Example 1 — Happy path: mark a story as MERGED\n\n```bash\nSkill(skill: \"x-internal-update-status\",\n      args: \"--file ai\u002Fepics\u002Fepic-XXXX\u002Fexecution-state.json \\\n             --type story --id story-0049-0005 \\\n             --field status --value MERGED\")\n```\n\nOutput:\n```json\n{\"previousValue\":\"IN_PROGRESS\",\"newValue\":\"MERGED\",\"fileSha\":\"a1b2...\",\"noOp\":false}\n```\nExit: 0.\n\n### Example 2 — No-op: value already matches\n\n```bash\nSkill(skill: \"x-internal-update-status\",\n      args: \"--file ai\u002Fepics\u002Fepic-XXXX\u002Fexecution-state.json \\\n             --type story --id story-0049-0005 \\\n             --field status --value MERGED\")\n```\n\nOutput:\n```json\n{\"previousValue\":\"MERGED\",\"newValue\":\"MERGED\",\"fileSha\":\"a1b2...\",\"noOp\":true}\n```\nExit: 0.\n\n### Example 3 — Initialize a fresh state file\n\n```bash\nSkill(skill: \"x-internal-update-status\",\n      args: \"--file ai\u002Fepics\u002Fepic-XXXX\u002Fexecution-state.json \\\n             --type epic --id 0049 \\\n             --field flowVersion --value 2 \\\n             --initialize\")\n```\n\nOutput:\n```json\n{\"previousValue\":null,\"newValue\":\"2\",\"fileSha\":\"c3d4...\",\"noOp\":false}\n```\nExit: 0.\n\n### Example 4 — Task-level update\n\n```bash\nSkill(skill: \"x-internal-update-status\",\n      args: \"--file ai\u002Fepics\u002Fepic-XXXX\u002Fexecution-state.json \\\n             --type task --id TASK-0049-0005-003 \\\n             --field prNumber --value 612\")\n```\n\nOutput:\n```json\n{\"previousValue\":null,\"newValue\":\"612\",\"fileSha\":\"e5f6...\",\"noOp\":false}\n```\nExit: 0.\n\n### Example 5 — Read-only query\n\n```bash\nSkill(skill: \"x-internal-update-status\",\n      args: \"--file ai\u002Fepics\u002Fepic-XXXX\u002Fexecution-state.json \\\n             --type story --id story-0049-0005 \\\n             --field status --value UNUSED \\\n             --read-only\")\n```\n\nOutput:\n```json\n{\"previousValue\":\"MERGED\",\"newValue\":\"MERGED\",\"fileSha\":\"a1b2...\",\"noOp\":true}\n```\nExit: 0. Note: `--value` is required by the argument schema but is\nignored under `--read-only`.\n\n### Example 6 — Invalid path (schema rejection)\n\n```bash\nSkill(skill: \"x-internal-update-status\",\n      args: \"--file ai\u002Fepics\u002Fepic-XXXX\u002Fexecution-state.json \\\n             --type story --id unknown-story \\\n             --field status --value DONE\")\n```\n\nStderr:\n```\nPath 'stories.unknown-story.status' not found in schema\n```\nExit: 3.\n\n## Outputs\n\n| Artifact | Path | Description |\n| :--- | :--- | :--- |\n| Updated state file | `\u003C--file>` | JSON document mutated in place via atomic rename |\n| Response envelope | stdout | Single-line JSON (`previousValue` \u002F `newValue` \u002F `fileSha` \u002F `noOp`) |\n| Lock file | `\u003C--file>.lock` | Created empty on first invocation; retained for reuse |\n\n## Error Handling\n\n| Scenario | Action |\n| :--- | :--- |\n| Missing required flag | Print `usage:` banner to stderr; exit 64 (sysexits EX_USAGE) |\n| `jq` absent on PATH | Exit 127 with `jq is required`; abort before lock |\n| Concurrent invocation exceeds 30s wait | Exit 2 (`LOCK_TIMEOUT`) — caller retries with backoff |\n| `mv` fails mid-write | Delete tmp file; exit 4 (`WRITE_FAILED`); state file is left untouched |\n| `--initialize` collides with existing non-JSON file | Exit 4 — do not overwrite |\n| Schema version mismatch | Log warning to stderr; proceed (non-blocking per RULE-006) |\n\n## Concurrency Contract\n\n- All readers and writers must acquire the same `\u003Cfile>.lock` file\n  descriptor. Exclusive (`flock -x`) for writes; shared (`flock -s`)\n  for `--read-only`.\n- Two concurrent invocations targeting **different fields** of the\n  same file serialize through the lock; both updates are preserved.\n- Two concurrent invocations targeting **the same field** serialize;\n  the later caller observes the earlier caller's value as\n  `previousValue` — this is the correct \"last writer wins\" semantic.\n- Lock is released automatically on process exit (file descriptor\n  closure). No `trap`-based cleanup required.\n\n## Trailer Injection Contract (story-0059-0004)\n\nEvery write operation that stages and commits `execution-state.json`\n**MUST** inject the canonical trailer into the commit message so that\nthe `.githooks\u002Fcommit-msg` hook (story-0059-0004 surface F guard) allows\nthe commit to proceed.\n\n### Canonical Trailer Format\n\n```\nCo-Authored-By: x-internal-update-status@\u003C40-char-git-sha>\n```\n\n- The `\u003Csha>` is the HEAD commit of the repository at the moment the\n  skill executes (`$(git rev-parse HEAD)`).\n- Uses the standard Git trailer key `Co-Authored-By:` (parseable via\n  `git interpret-trailers`).\n\n### Commit Invocation Pattern\n\nWhen this skill issues a `git commit` that includes `execution-state.json`\nin the staged files, it MUST pass the trailer:\n\n```bash\nSKILL_SHA=$(git rev-parse HEAD)\ngit commit -m \"\u003Csubject>\" \\\n  --trailer \"Co-Authored-By: x-internal-update-status@${SKILL_SHA}\"\n```\n\nThis trailer is validated by `.githooks\u002Fcommit-msg` which checks:\n\n```bash\ngit interpret-trailers --parse \u003C \"$COMMIT_MSG_FILE\" \\\n  | grep -qE '^Co-Authored-By:\\s+x-internal-update-status@[0-9a-f]{40}$'\n```\n\n### Recovery escape\n\nIn documented recovery operations where the operator manually edits\n`execution-state.json` (e.g., state corruption), the trailer MUST\nstill be present. The operator adds the trailer with an approved SHA.\nThe hook validates format only, not SHA authenticity (RULE-059).\n\n## Testing\n\nThe PILOT story (story-0049-0005) ships the following acceptance test\nscenarios, which are the reference contract every future `x-internal-*`\nskill MUST replicate in its own directory:\n\n1. **Write happy path** — status transition PENDING → MERGED;\n   assert `noOp=false` and fileSha changes.\n2. **No-op detection** — same value twice; assert `noOp=true`, file\n   mtime unchanged.\n3. **Read-only** — assert no write occurs; shared lock only.\n4. **Lock contention** — spawn 2 concurrent processes mutating\n   distinct fields; both updates present in final file; JSON valid.\n5. **FILE_NOT_FOUND** — absent file without `--initialize`; exit 1.\n6. **INVALID_PATH** — unknown story ID; exit 3 with path in message.\n\nGoldens under\n`src\u002Ftest\u002Fresources\u002Fgolden\u002Finternal\u002Fops\u002Fx-internal-update-status\u002F`\nlock the SKILL.md rendering. Coverage requirement: ≥ 95% line \u002F\n≥ 90% branch across the invoking Bash codepaths.\n\n## Generator Filter Contract\n\nThe `ia-dev-env` generator MUST exclude skills with\n`visibility: internal` from:\n\n1. The `.claude\u002FREADME.md` skill-inventory table.\n2. The `\u002Fhelp` menu listing surfaced by Claude Code.\n3. User-facing autocomplete in the chat input.\n\nInternal skills are still copied into `.claude\u002Fskills\u002F` (flat layout)\nso `Skill(skill: \"x-internal-...\")` invocations from other skills\nresolve correctly. The invariant: **user cannot see them; orchestrators\ncan invoke them.**\n\n## Telemetry\n\nInternal skills DO NOT emit `phase.start` \u002F `phase.end` markers —\ntelemetry is produced by the invoking orchestrator (the `phase` wrapping\nthe orchestrator's own step is the correct aggregation boundary).\nPassive hooks still capture `tool.call` for the underlying `Bash`\ninvocation.\n\nReference: Rule 13 (Skill Invocation Protocol), Rule 22 (Lifecycle\nIntegrity Audit), ADR-0010 (Interactive Gates Convention — exempts\ninternal skills from the 3-option menu contract).\n\n## Integration Notes\n\n| Skill | Relationship | Context |\n| :--- | :--- | :--- |\n| `x-implement-epic` | caller | Phase 2 (per-story status transitions) + Phase 4 (epic finalization) |\n| `x-implement-story` | caller | Phase 2 (per-task status transitions) + Phase 3 (story finalization) |\n| `x-fix-epic-pr` | caller | Records per-PR correction state when fanning out across an epic |\n| `x-reconcile-status` | peer | Reads the same file to diagnose drift against markdown; never mutates concurrently with this skill (Rule 22) |\n| `x-evaluate-parallelism` | consumer | Reads the resulting state file to build the collision matrix |\n\nDownstream stories that depend on this PILOT: story-0049-0013,\nstory-0049-0018, story-0049-0019.\n","## Global Output Policy\n\n- **Language**: English ONLY.\n- **Tone**: Technical, Direct, and Concise.\n- **Efficiency**: Remove all conversational fillers and greetings to save tokens.\n\n> 🔒 **INTERNAL SKILL**\n> Esta skill é invocada apenas por outras skills (orquestradores).\n> NÃO é destinada a invocação direta pelo usuário.\n> Caller principal: x-implement-epic, x-implement-story, x-fix-epic-pr.\n> Esta é a story PILOTO (story-0049-0005) da convenção `x-internal-*`:\n> frontmatter `visibility: internal`, subdir `internal\u002Fops\u002F`, marker 🔒, e\n> filtragem do menu `\u002Fhelp` via generator.\n\n# Skill: x-internal-update-status\n\n## Purpose\n\nPerform atomic read-modify-write mutations of\n`ai\u002Fepics\u002Fepic-XXXX\u002Fexecution-state.json` (the telemetry checkpoint file\nconsumed by every orchestrator skill). The operation:\n\n1. Acquires a `flock`-based advisory lock with 30s timeout.\n2. Reads the full JSON document.\n3. Validates the resolved path exists in the schema.\n4. Compares `previousValue` vs `newValue` — emits `noOp=true` when equal\n   (idempotency per RULE-002).\n5. Writes via tmp-file + rename (atomic on POSIX).\n6. Releases the lock.\n\nThis replaces ad-hoc `Edit`-tool invocations from inside orchestrators,\nwhich historically lost updates under `--parallel` execution (documented\nin EPIC-0042 post-mortems).\n\n## Convention Anchors (x-internal-* PILOT)\n\n| Aspect | Value | Rationale |\n| :--- | :--- | :--- |\n| Path | `internal\u002Fops\u002Fx-internal-update-status\u002F` | `internal\u002F` prefix scopes visibility; `ops\u002F` aligns with sibling runtime-ops skills |\n| Frontmatter `visibility` | `internal` | Generator filters these from `\u002Fhelp` menu |\n| Frontmatter `user-invocable` | `false` | Declarative complement to `visibility: internal` |\n| Body marker | `> 🔒 **INTERNAL SKILL**` block as first non-frontmatter content | Visible to humans browsing the repo; no parsing required |\n| Allowed tools | `Bash` only | Minimal surface; all logic is a single shell pipeline |\n| Naming | `x-internal-{subject}-{action}` | Mirrors Rule 04 skill taxonomy; `status-update` = subject+action |\n\nAudit rule: Rule 22 (Lifecycle Integrity) validates every skill under\n`internal\u002F**` satisfies all 6 anchors above. Violations fail the\n`LifecycleIntegrityAuditTest`.\n\n## Triggers\n\nBare-slash form is intentionally omitted — this skill is never invoked\nby a human typing `\u002Fx-internal-update-status` in chat. All invocations\nfollow Rule 13 INLINE-SKILL pattern from a calling orchestrator:\n\n```markdown\nSkill(skill: \"x-internal-update-status\",\n      args: \"--file ai\u002Fepics\u002Fepic-XXXX\u002Fexecution-state.json \\\n             --type story --id story-0049-0005 \\\n             --field status --value MERGED\")\n```\n\n## Parameters\n\n| Parameter | Required | Default | Description |\n| :--- | :--- | :--- | :--- |\n| `--file \u003Cpath>` | O | `execution-state.json` in cwd | Target state file |\n| `--type \u003Cepic\\|story\\|task>` | M | — | Scope of the node being mutated |\n| `--id \u003Cid>` | M | — | Epic ID (`0049`), story ID (`story-0049-0005`), or task ID (`TASK-0049-0005-001`) |\n| `--field \u003Cname>` | M | — | Schema field to update (e.g., `status`, `prNumber`, `commitSha`) |\n| `--value \u003Cvalue>` | M | — | New value; coerced to the schema-declared type |\n| `--initialize` | O | `false` | Create the file with an empty schema skeleton when absent |\n| `--read-only` | O | `false` | Read and return the current value without acquiring the write lock |\n\n## Response Contract\n\nWhen successful, the skill writes a single-line JSON object to stdout:\n\n| Field | Type | Always Present | Description |\n| :--- | :--- | :--- | :--- |\n| `previousValue` | `String\\|Null` | yes | Value before write; null when field was absent |\n| `newValue` | `String` | yes | Value after write (equal to previous on no-op) |\n| `fileSha` | `String(64)` | yes | sha256 of the file after the write |\n| `noOp` | `Boolean` | yes | `true` when `previousValue == newValue` |\n\n## Exit Codes\n\n| Code | Name | Condition | Message Format |\n| :--- | :--- | :--- | :--- |\n| 0 | SUCCESS | Write or no-op completed | — |\n| 1 | FILE_NOT_FOUND | File missing and `--initialize=false` | `State file not found: \u003Cpath>` |\n| 2 | LOCK_TIMEOUT | `flock` timed out after 30s | `Lock timeout on \u003Cpath>.lock` |\n| 3 | INVALID_PATH | `--type\u002F--id\u002F--field` tuple does not resolve | `Path '\u003Cresolved-path>' not found in schema` |\n| 4 | WRITE_FAILED | Atomic `mv` of tmp file failed | `Atomic write failed: \u003Cstderr>` |\n\n## Workflow\n\n### Step 1 — Argument parsing and validation\n\nParse flags; reject unknown flags; enforce mutual exclusivity of\n`--read-only` with any write-implying flag combination. When\n`--type=epic`, the resolved path is `\u003Cfield>` at document root; when\n`--type=story`, the path is `stories.\u003Cid>.\u003Cfield>`; when `--type=task`,\nthe path is `stories.\u003CparentStoryId>.tasks.\u003Cid>.\u003Cfield>`. Parent story\nID is inferred from the task ID prefix (`TASK-0049-0005-001` ⇒\n`story-0049-0005`).\n\n### Step 2 — Lock acquisition\n\n```bash\nlock_file=\"${file}.lock\"\nexec {fd}>\"${lock_file}\"\nif ! flock -w 30 \"${fd}\"; then\n  echo \"Lock timeout on ${lock_file}\" >&2\n  exit 2\nfi\n```\n\n### Step 3 — File existence and initialization\n\n- When the file is absent and `--initialize=false`: exit 1.\n- When absent and `--initialize=true`: write an empty skeleton\n  `{\"version\":1,\"stories\":{}}` via the same atomic tmp+rename contract\n  before proceeding.\n\n### Step 4 — Read and validate path\n\nParse JSON via `jq`; resolve the path per Step 1. When the path does\nnot exist, exit 3 with the resolved path in the message.\n\n### Step 5 — Idempotency check\n\nCompute `previousValue` at the resolved path. When\n`previousValue == newValue`, emit the response JSON with `noOp=true`\nand exit 0 without touching the file. The lock is still released via\n`flock` descriptor closure.\n\n### Step 6 — Atomic write\n\n```bash\ntmp=\"${file}.tmp.$$\"\njq --arg v \"${newValue}\" \"\u003Cpath-expression>\" \"${file}\" > \"${tmp}\"\nif ! mv \"${tmp}\" \"${file}\"; then\n  rm -f \"${tmp}\"\n  echo \"Atomic write failed: mv returned non-zero\" >&2\n  exit 4\nfi\n```\n\n### Step 7 — Emit response and release lock\n\n```bash\nfile_sha=$(shasum -a 256 \"${file}\" | cut -d' ' -f1)\nprintf '{\"previousValue\":%s,\"newValue\":\"%s\",\"fileSha\":\"%s\",\"noOp\":false}\\n' \\\n  \"${prev_json}\" \"${newValue}\" \"${file_sha}\"\n```\n\nThe `flock` descriptor is closed on process exit; no explicit unlock\nis required.\n\n### Step 8 — `--read-only` short-circuit\n\nWhen `--read-only=true`, Steps 2, 6, and 7 are skipped. The skill\nopens the file with a shared (`flock -s`) lock, reads the value,\nemits the response with `noOp=true` and `newValue==previousValue`,\nand exits 0.\n\n## Examples\n\n### Example 1 — Happy path: mark a story as MERGED\n\n```bash\nSkill(skill: \"x-internal-update-status\",\n      args: \"--file ai\u002Fepics\u002Fepic-XXXX\u002Fexecution-state.json \\\n             --type story --id story-0049-0005 \\\n             --field status --value MERGED\")\n```\n\nOutput:\n```json\n{\"previousValue\":\"IN_PROGRESS\",\"newValue\":\"MERGED\",\"fileSha\":\"a1b2...\",\"noOp\":false}\n```\nExit: 0.\n\n### Example 2 — No-op: value already matches\n\n```bash\nSkill(skill: \"x-internal-update-status\",\n      args: \"--file ai\u002Fepics\u002Fepic-XXXX\u002Fexecution-state.json \\\n             --type story --id story-0049-0005 \\\n             --field status --value MERGED\")\n```\n\nOutput:\n```json\n{\"previousValue\":\"MERGED\",\"newValue\":\"MERGED\",\"fileSha\":\"a1b2...\",\"noOp\":true}\n```\nExit: 0.\n\n### Example 3 — Initialize a fresh state file\n\n```bash\nSkill(skill: \"x-internal-update-status\",\n      args: \"--file ai\u002Fepics\u002Fepic-XXXX\u002Fexecution-state.json \\\n             --type epic --id 0049 \\\n             --field flowVersion --value 2 \\\n             --initialize\")\n```\n\nOutput:\n```json\n{\"previousValue\":null,\"newValue\":\"2\",\"fileSha\":\"c3d4...\",\"noOp\":false}\n```\nExit: 0.\n\n### Example 4 — Task-level update\n\n```bash\nSkill(skill: \"x-internal-update-status\",\n      args: \"--file ai\u002Fepics\u002Fepic-XXXX\u002Fexecution-state.json \\\n             --type task --id TASK-0049-0005-003 \\\n             --field prNumber --value 612\")\n```\n\nOutput:\n```json\n{\"previousValue\":null,\"newValue\":\"612\",\"fileSha\":\"e5f6...\",\"noOp\":false}\n```\nExit: 0.\n\n### Example 5 — Read-only query\n\n```bash\nSkill(skill: \"x-internal-update-status\",\n      args: \"--file ai\u002Fepics\u002Fepic-XXXX\u002Fexecution-state.json \\\n             --type story --id story-0049-0005 \\\n             --field status --value UNUSED \\\n             --read-only\")\n```\n\nOutput:\n```json\n{\"previousValue\":\"MERGED\",\"newValue\":\"MERGED\",\"fileSha\":\"a1b2...\",\"noOp\":true}\n```\nExit: 0. Note: `--value` is required by the argument schema but is\nignored under `--read-only`.\n\n### Example 6 — Invalid path (schema rejection)\n\n```bash\nSkill(skill: \"x-internal-update-status\",\n      args: \"--file ai\u002Fepics\u002Fepic-XXXX\u002Fexecution-state.json \\\n             --type story --id unknown-story \\\n             --field status --value DONE\")\n```\n\nStderr:\n```\nPath 'stories.unknown-story.status' not found in schema\n```\nExit: 3.\n\n## Outputs\n\n| Artifact | Path | Description |\n| :--- | :--- | :--- |\n| Updated state file | `\u003C--file>` | JSON document mutated in place via atomic rename |\n| Response envelope | stdout | Single-line JSON (`previousValue` \u002F `newValue` \u002F `fileSha` \u002F `noOp`) |\n| Lock file | `\u003C--file>.lock` | Created empty on first invocation; retained for reuse |\n\n## Error Handling\n\n| Scenario | Action |\n| :--- | :--- |\n| Missing required flag | Print `usage:` banner to stderr; exit 64 (sysexits EX_USAGE) |\n| `jq` absent on PATH | Exit 127 with `jq is required`; abort before lock |\n| Concurrent invocation exceeds 30s wait | Exit 2 (`LOCK_TIMEOUT`) — caller retries with backoff |\n| `mv` fails mid-write | Delete tmp file; exit 4 (`WRITE_FAILED`); state file is left untouched |\n| `--initialize` collides with existing non-JSON file | Exit 4 — do not overwrite |\n| Schema version mismatch | Log warning to stderr; proceed (non-blocking per RULE-006) |\n\n## Concurrency Contract\n\n- All readers and writers must acquire the same `\u003Cfile>.lock` file\n  descriptor. Exclusive (`flock -x`) for writes; shared (`flock -s`)\n  for `--read-only`.\n- Two concurrent invocations targeting **different fields** of the\n  same file serialize through the lock; both updates are preserved.\n- Two concurrent invocations targeting **the same field** serialize;\n  the later caller observes the earlier caller's value as\n  `previousValue` — this is the correct \"last writer wins\" semantic.\n- Lock is released automatically on process exit (file descriptor\n  closure). No `trap`-based cleanup required.\n\n## Trailer Injection Contract (story-0059-0004)\n\nEvery write operation that stages and commits `execution-state.json`\n**MUST** inject the canonical trailer into the commit message so that\nthe `.githooks\u002Fcommit-msg` hook (story-0059-0004 surface F guard) allows\nthe commit to proceed.\n\n### Canonical Trailer Format\n\n```\nCo-Authored-By: x-internal-update-status@\u003C40-char-git-sha>\n```\n\n- The `\u003Csha>` is the HEAD commit of the repository at the moment the\n  skill executes (`$(git rev-parse HEAD)`).\n- Uses the standard Git trailer key `Co-Authored-By:` (parseable via\n  `git interpret-trailers`).\n\n### Commit Invocation Pattern\n\nWhen this skill issues a `git commit` that includes `execution-state.json`\nin the staged files, it MUST pass the trailer:\n\n```bash\nSKILL_SHA=$(git rev-parse HEAD)\ngit commit -m \"\u003Csubject>\" \\\n  --trailer \"Co-Authored-By: x-internal-update-status@${SKILL_SHA}\"\n```\n\nThis trailer is validated by `.githooks\u002Fcommit-msg` which checks:\n\n```bash\ngit interpret-trailers --parse \u003C \"$COMMIT_MSG_FILE\" \\\n  | grep -qE '^Co-Authored-By:\\s+x-internal-update-status@[0-9a-f]{40}$'\n```\n\n### Recovery escape\n\nIn documented recovery operations where the operator manually edits\n`execution-state.json` (e.g., state corruption), the trailer MUST\nstill be present. The operator adds the trailer with an approved SHA.\nThe hook validates format only, not SHA authenticity (RULE-059).\n\n## Testing\n\nThe PILOT story (story-0049-0005) ships the following acceptance test\nscenarios, which are the reference contract every future `x-internal-*`\nskill MUST replicate in its own directory:\n\n1. **Write happy path** — status transition PENDING → MERGED;\n   assert `noOp=false` and fileSha changes.\n2. **No-op detection** — same value twice; assert `noOp=true`, file\n   mtime unchanged.\n3. **Read-only** — assert no write occurs; shared lock only.\n4. **Lock contention** — spawn 2 concurrent processes mutating\n   distinct fields; both updates present in final file; JSON valid.\n5. **FILE_NOT_FOUND** — absent file without `--initialize`; exit 1.\n6. **INVALID_PATH** — unknown story ID; exit 3 with path in message.\n\nGoldens under\n`src\u002Ftest\u002Fresources\u002Fgolden\u002Finternal\u002Fops\u002Fx-internal-update-status\u002F`\nlock the SKILL.md rendering. Coverage requirement: ≥ 95% line \u002F\n≥ 90% branch across the invoking Bash codepaths.\n\n## Generator Filter Contract\n\nThe `ia-dev-env` generator MUST exclude skills with\n`visibility: internal` from:\n\n1. The `.claude\u002FREADME.md` skill-inventory table.\n2. The `\u002Fhelp` menu listing surfaced by Claude Code.\n3. User-facing autocomplete in the chat input.\n\nInternal skills are still copied into `.claude\u002Fskills\u002F` (flat layout)\nso `Skill(skill: \"x-internal-...\")` invocations from other skills\nresolve correctly. The invariant: **user cannot see them; orchestrators\ncan invoke them.**\n\n## Telemetry\n\nInternal skills DO NOT emit `phase.start` \u002F `phase.end` markers —\ntelemetry is produced by the invoking orchestrator (the `phase` wrapping\nthe orchestrator's own step is the correct aggregation boundary).\nPassive hooks still capture `tool.call` for the underlying `Bash`\ninvocation.\n\nReference: Rule 13 (Skill Invocation Protocol), Rule 22 (Lifecycle\nIntegrity Audit), ADR-0010 (Interactive Gates Convention — exempts\ninternal skills from the 3-option menu contract).\n\n## Integration Notes\n\n| Skill | Relationship | Context |\n| :--- | :--- | :--- |\n| `x-implement-epic` | caller | Phase 2 (per-story status transitions) + Phase 4 (epic finalization) |\n| `x-implement-story` | caller | Phase 2 (per-task status transitions) + Phase 3 (story finalization) |\n| `x-fix-epic-pr` | caller | Records per-PR correction state when fanning out across an epic |\n| `x-reconcile-status` | peer | Reads the same file to diagnose drift against markdown; never mutates concurrently with this skill (Rule 22) |\n| `x-evaluate-parallelism` | consumer | Reads the resulting state file to build the collision matrix |\n\nDownstream stories that depend on this PILOT: story-0049-0013,\nstory-0049-0018, story-0049-0019.\n",{"name":5,"category":24,"visibility":25,"description":7,"allowed-tools":26,"argument-hint":27,"context-budget":28,"user-invocable":20,"requires-capabilities":29},"internal-ops","internal","Bash","--file \u003Cpath> --type \u003Cepic|story|task> --id \u003Cid> --field \u003Cname> --value \u003Cvalue> [--initialize] [--read-only]","medium",[],"main","952a630c6f38d193a349d86fa18db1de8843e837","src\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring-fintech-pci\u002F.claude\u002Fskills\u002Fx-internal-update-status",1,"https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment","https:\u002F\u002Fgithub.com\u002Freview-bench","https:\u002F\u002Freview-bench.ai","An open benchmark for AI code review.","2026-10-27 06:56:37",{"source":8,"skillName":5,"commands":40,"prompt":50,"zipAvailable":51},[41,44,47],{"tool":42,"command":43},"npx","npx skills add review-bench\u002Federcnj_ia-dev-environment --skill x-internal-update-status",{"tool":45,"command":46},"bunx","bunx skills add review-bench\u002Federcnj_ia-dev-environment --skill x-internal-update-status",{"tool":48,"command":49},"pnpm","pnpm dlx skills add review-bench\u002Federcnj_ia-dev-environment --skill x-internal-update-status","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring-fintech-pci\u002F.claude\u002Fskills\u002Fx-internal-update-status\u002FSKILL.md",true,[],[54,61,68,75,82,89],{"skillNo":55,"name":56,"nameZh":6,"description":57,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":58,"categories":59,"keywords":60,"publishedAt":19},"01M757M8J48TQ1Y3X25GSJBXAS","x-parallel-eval","Detects and classifies file-collision risks between work units (tasks, stories, or epic phases) before parallel execution. Reads ## File Footprint blocks produced by x-task-plan \u002F x-story-plan, applies the parallelism-heuristics knowledge pack (hard \u002F regen \u002F soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fx-parallel-eval\u002FSKILL.md",[],[],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":19},"01M757M57XMR9546S69466HDWT","parallelism-heuristics","Canonical catalog of file-collision heuristics for parallel task, story, and epic execution. Defines the File Footprint block format, the three Conflict Categories (hard \u002F regen \u002F soft), a hotspot list of high-contention paths, and the degrade-with-warning policy. Consumed by x-task-plan, x-story-plan, x-epic-map, x-parallel-eval, and x-dev-*-implement.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fparallelism-heuristics\u002FSKILL.md",[],[],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":19},"01M757M11SZ8P1VCQABT08QVYA","x-watch-pr-ci","Polls a PR's CI checks and Copilot review status, blocking until checks complete or timeout. Returns one of 8 stable exit codes (SUCCESS=0, CI_PENDING_PROCEED=10, CI_FAILED=20, TIMEOUT=30, PR_ALREADY_MERGED=40, NO_CI_CONFIGURED=50, PR_CLOSED=60, PR_NOT_FOUND=70). Writes a versioned state-file for session resume.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring\u002Fplatform-claude-code\u002F.claude\u002Fskills\u002Fx-watch-pr-ci\u002FSKILL.md",[],[],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M757KW53K8KFPGADFB4PH949","x-validate-docs","Documentation freshness gate: validates 6 dimensions (readme, api-specs, grpc-proto, adr, skill-docs, system-architecture) against code changes in a PR. Stack-aware — only validates targets declared\u002Fauto-detected from ProjectConfig.documentation.targets. Returns exit non-zero on staleness; produces structured report.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring\u002Fplatform-claude-code\u002F.claude\u002Fskills\u002Fx-validate-docs\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M757KQZHSA10MKC0CR571D60","x-update-system-architecture","Incrementally updates docs\u002Farchitecture\u002Fsystem.md after an epic completes. Appends new entries to the Decision Log (§11) using x-internal-write-report --append (dedup by ## ID: marker) and surgically inserts component\u002Fintegration changes into sections 1-10 via Edit. Idempotent: re-running with the same epic produces a byte-identical system.md.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring\u002Fplatform-claude-code\u002F.claude\u002Fskills\u002Fx-update-system-architecture\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":19},"01M757KKBT5Q1SVF8DMJBVF46M","x-update-architecture","Incrementally updates the service architecture document with changes from architecture plans. Adds new components, integrations, flows, and ADR references without rewriting existing content. Use after implementation to keep architecture documentation current.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring\u002Fplatform-claude-code\u002F.claude\u002Fskills\u002Fx-update-architecture\u002FSKILL.md",[],[]]