AGENT SKILL

x-internal-update-status

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/ops/.

License 许可
MIT
最近更新
2026-10-27
Stars
★ 0
Forks
1

01 前言 Front Matter

name
x-internal-update-status
category
internal-ops
visibility
internal
description
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/ops/.
allowed-tools
Bash
argument-hint
--file <path> --type <epic|story|task> --id <id> --field <name> --value <value> [--initialize] [--read-only]
context-budget
medium
user-invocable
false
requires-capabilities
[]

03 SKILL.md 正文

Global Output Policy

  • Language: English ONLY.
  • Tone: Technical, Direct, and Concise.
  • Efficiency: Remove all conversational fillers and greetings to save tokens.

🔒 INTERNAL SKILL Esta skill é invocada apenas por outras skills (orquestradores). NÃO é destinada a invocação direta pelo usuário. Caller principal: x-implement-epic, x-implement-story, x-fix-epic-pr. Esta é a story PILOTO (story-0049-0005) da convenção x-internal-*: frontmatter visibility: internal, subdir internal/ops/, marker 🔒, e filtragem do menu /help via generator.

Skill: x-internal-update-status

Purpose

Perform atomic read-modify-write mutations of ai/epics/epic-XXXX/execution-state.json (the telemetry checkpoint file consumed by every orchestrator skill). The operation:

  1. Acquires a flock-based advisory lock with 30s timeout.
  2. Reads the full JSON document.
  3. Validates the resolved path exists in the schema.
  4. Compares previousValue vs newValue — emits noOp=true when equal (idempotency per RULE-002).
  5. Writes via tmp-file + rename (atomic on POSIX).
  6. Releases the lock.

This replaces ad-hoc Edit-tool invocations from inside orchestrators, which historically lost updates under --parallel execution (documented in EPIC-0042 post-mortems).

Convention Anchors (x-internal-* PILOT)

Aspect Value Rationale
Path internal/ops/x-internal-update-status/ internal/ prefix scopes visibility; ops/ aligns with sibling runtime-ops skills
Frontmatter visibility internal Generator filters these from /help menu
Frontmatter user-invocable false Declarative complement to visibility: internal
Body marker > 🔒 **INTERNAL SKILL** block as first non-frontmatter content Visible to humans browsing the repo; no parsing required
Allowed tools Bash only Minimal surface; all logic is a single shell pipeline
Naming x-internal-{subject}-{action} Mirrors Rule 04 skill taxonomy; status-update = subject+action

Audit rule: Rule 22 (Lifecycle Integrity) validates every skill under internal/** satisfies all 6 anchors above. Violations fail the LifecycleIntegrityAuditTest.

Triggers

Bare-slash form is intentionally omitted — this skill is never invoked by a human typing /x-internal-update-status in chat. All invocations follow Rule 13 INLINE-SKILL pattern from a calling orchestrator:

Skill(skill: "x-internal-update-status",
      args: "--file ai/epics/epic-XXXX/execution-state.json \
             --type story --id story-0049-0005 \
             --field status --value MERGED")

Parameters

Parameter Required Default Description
--file <path> O execution-state.json in cwd Target state file
--type <epic|story|task> M — Scope of the node being mutated
--id <id> M — Epic ID (0049), story ID (story-0049-0005), or task ID (TASK-0049-0005-001)
--field <name> M — Schema field to update (e.g., status, prNumber, commitSha)
--value <value> M — New value; coerced to the schema-declared type
--initialize O false Create the file with an empty schema skeleton when absent
--read-only O false Read and return the current value without acquiring the write lock

Response Contract

When successful, the skill writes a single-line JSON object to stdout:

Field Type Always Present Description
previousValue String|Null yes Value before write; null when field was absent
newValue String yes Value after write (equal to previous on no-op)
fileSha String(64) yes sha256 of the file after the write
noOp Boolean yes true when previousValue == newValue

Exit Codes

Code Name Condition Message Format
0 SUCCESS Write or no-op completed —
1 FILE_NOT_FOUND File missing and --initialize=false State file not found: <path>
2 LOCK_TIMEOUT flock timed out after 30s Lock timeout on <path>.lock
3 INVALID_PATH --type/--id/--field tuple does not resolve Path '<resolved-path>' not found in schema
4 WRITE_FAILED Atomic mv of tmp file failed Atomic write failed: <stderr>

Workflow

Step 1 — Argument parsing and validation

Parse flags; reject unknown flags; enforce mutual exclusivity of --read-only with any write-implying flag combination. When --type=epic, the resolved path is <field> at document root; when --type=story, the path is stories.<id>.<field>; when --type=task, the path is stories.<parentStoryId>.tasks.<id>.<field>. Parent story ID is inferred from the task ID prefix (TASK-0049-0005-001 ⇒ story-0049-0005).

Step 2 — Lock acquisition

lock_file="${file}.lock"
exec {fd}>"${lock_file}"
if ! flock -w 30 "${fd}"; then
  echo "Lock timeout on ${lock_file}" >&2
  exit 2
fi

Step 3 — File existence and initialization

  • When the file is absent and --initialize=false: exit 1.
  • When absent and --initialize=true: write an empty skeleton {"version":1,"stories":{}} via the same atomic tmp+rename contract before proceeding.

Step 4 — Read and validate path

Parse JSON via jq; resolve the path per Step 1. When the path does not exist, exit 3 with the resolved path in the message.

Step 5 — Idempotency check

Compute previousValue at the resolved path. When previousValue == newValue, emit the response JSON with noOp=true and exit 0 without touching the file. The lock is still released via flock descriptor closure.

Step 6 — Atomic write

tmp="${file}.tmp.$$"
jq --arg v "${newValue}" "<path-expression>" "${file}" > "${tmp}"
if ! mv "${tmp}" "${file}"; then
  rm -f "${tmp}"
  echo "Atomic write failed: mv returned non-zero" >&2
  exit 4
fi

Step 7 — Emit response and release lock

file_sha=$(shasum -a 256 "${file}" | cut -d' ' -f1)
printf '{"previousValue":%s,"newValue":"%s","fileSha":"%s","noOp":false}\n' \
  "${prev_json}" "${newValue}" "${file_sha}"

The flock descriptor is closed on process exit; no explicit unlock is required.

Step 8 — --read-only short-circuit

When --read-only=true, Steps 2, 6, and 7 are skipped. The skill opens the file with a shared (flock -s) lock, reads the value, emits the response with noOp=true and newValue==previousValue, and exits 0.

Examples

Example 1 — Happy path: mark a story as MERGED

Skill(skill: "x-internal-update-status",
      args: "--file ai/epics/epic-XXXX/execution-state.json \
             --type story --id story-0049-0005 \
             --field status --value MERGED")

Output:

{"previousValue":"IN_PROGRESS","newValue":"MERGED","fileSha":"a1b2...","noOp":false}

Exit: 0.

Example 2 — No-op: value already matches

Skill(skill: "x-internal-update-status",
      args: "--file ai/epics/epic-XXXX/execution-state.json \
             --type story --id story-0049-0005 \
             --field status --value MERGED")

Output:

{"previousValue":"MERGED","newValue":"MERGED","fileSha":"a1b2...","noOp":true}

Exit: 0.

Example 3 — Initialize a fresh state file

Skill(skill: "x-internal-update-status",
      args: "--file ai/epics/epic-XXXX/execution-state.json \
             --type epic --id 0049 \
             --field flowVersion --value 2 \
             --initialize")

Output:

{"previousValue":null,"newValue":"2","fileSha":"c3d4...","noOp":false}

Exit: 0.

Example 4 — Task-level update

Skill(skill: "x-internal-update-status",
      args: "--file ai/epics/epic-XXXX/execution-state.json \
             --type task --id TASK-0049-0005-003 \
             --field prNumber --value 612")

Output:

{"previousValue":null,"newValue":"612","fileSha":"e5f6...","noOp":false}

Exit: 0.

Example 5 — Read-only query

Skill(skill: "x-internal-update-status",
      args: "--file ai/epics/epic-XXXX/execution-state.json \
             --type story --id story-0049-0005 \
             --field status --value UNUSED \
             --read-only")

Output:

{"previousValue":"MERGED","newValue":"MERGED","fileSha":"a1b2...","noOp":true}

Exit: 0. Note: --value is required by the argument schema but is ignored under --read-only.

Example 6 — Invalid path (schema rejection)

Skill(skill: "x-internal-update-status",
      args: "--file ai/epics/epic-XXXX/execution-state.json \
             --type story --id unknown-story \
             --field status --value DONE")

Stderr:

Path 'stories.unknown-story.status' not found in schema

Exit: 3.

Outputs

Artifact Path Description
Updated state file <--file> JSON document mutated in place via atomic rename
Response envelope stdout Single-line JSON (previousValue / newValue / fileSha / noOp)
Lock file <--file>.lock Created empty on first invocation; retained for reuse

Error Handling

Scenario Action
Missing required flag Print usage: banner to stderr; exit 64 (sysexits EX_USAGE)
jq absent on PATH Exit 127 with jq is required; abort before lock
Concurrent invocation exceeds 30s wait Exit 2 (LOCK_TIMEOUT) — caller retries with backoff
mv fails mid-write Delete tmp file; exit 4 (WRITE_FAILED); state file is left untouched
--initialize collides with existing non-JSON file Exit 4 — do not overwrite
Schema version mismatch Log warning to stderr; proceed (non-blocking per RULE-006)

Concurrency Contract

  • All readers and writers must acquire the same <file>.lock file descriptor. Exclusive (flock -x) for writes; shared (flock -s) for --read-only.
  • Two concurrent invocations targeting different fields of the same file serialize through the lock; both updates are preserved.
  • Two concurrent invocations targeting the same field serialize; the later caller observes the earlier caller's value as previousValue — this is the correct "last writer wins" semantic.
  • Lock is released automatically on process exit (file descriptor closure). No trap-based cleanup required.

Trailer Injection Contract (story-0059-0004)

Every write operation that stages and commits execution-state.json MUST inject the canonical trailer into the commit message so that the .githooks/commit-msg hook (story-0059-0004 surface F guard) allows the commit to proceed.

Canonical Trailer Format

Co-Authored-By: x-internal-update-status@<40-char-git-sha>
  • The <sha> is the HEAD commit of the repository at the moment the skill executes ($(git rev-parse HEAD)).
  • Uses the standard Git trailer key Co-Authored-By: (parseable via git interpret-trailers).

Commit Invocation Pattern

When this skill issues a git commit that includes execution-state.json in the staged files, it MUST pass the trailer:

SKILL_SHA=$(git rev-parse HEAD)
git commit -m "<subject>" \
  --trailer "Co-Authored-By: x-internal-update-status@${SKILL_SHA}"

This trailer is validated by .githooks/commit-msg which checks:

git interpret-trailers --parse < "$COMMIT_MSG_FILE" \
  | grep -qE '^Co-Authored-By:\s+x-internal-update-status@[0-9a-f]{40}$'

Recovery escape

In documented recovery operations where the operator manually edits execution-state.json (e.g., state corruption), the trailer MUST still be present. The operator adds the trailer with an approved SHA. The hook validates format only, not SHA authenticity (RULE-059).

Testing

The PILOT story (story-0049-0005) ships the following acceptance test scenarios, which are the reference contract every future x-internal-* skill MUST replicate in its own directory:

  1. Write happy path — status transition PENDING → MERGED; assert noOp=false and fileSha changes.
  2. No-op detection — same value twice; assert noOp=true, file mtime unchanged.
  3. Read-only — assert no write occurs; shared lock only.
  4. Lock contention — spawn 2 concurrent processes mutating distinct fields; both updates present in final file; JSON valid.
  5. FILE_NOT_FOUND — absent file without --initialize; exit 1.
  6. INVALID_PATH — unknown story ID; exit 3 with path in message.

Goldens under src/test/resources/golden/internal/ops/x-internal-update-status/ lock the SKILL.md rendering. Coverage requirement: ≥ 95% line / ≥ 90% branch across the invoking Bash codepaths.

Generator Filter Contract

The ia-dev-env generator MUST exclude skills with visibility: internal from:

  1. The .claude/README.md skill-inventory table.
  2. The /help menu listing surfaced by Claude Code.
  3. User-facing autocomplete in the chat input.

Internal skills are still copied into .claude/skills/ (flat layout) so Skill(skill: "x-internal-...") invocations from other skills resolve correctly. The invariant: user cannot see them; orchestrators can invoke them.

Telemetry

Internal skills DO NOT emit phase.start / phase.end markers — telemetry is produced by the invoking orchestrator (the phase wrapping the orchestrator's own step is the correct aggregation boundary). Passive hooks still capture tool.call for the underlying Bash invocation.

Reference: Rule 13 (Skill Invocation Protocol), Rule 22 (Lifecycle Integrity Audit), ADR-0010 (Interactive Gates Convention — exempts internal skills from the 3-option menu contract).

Integration Notes

Skill Relationship Context
x-implement-epic caller Phase 2 (per-story status transitions) + Phase 4 (epic finalization)
x-implement-story caller Phase 2 (per-task status transitions) + Phase 3 (story finalization)
x-fix-epic-pr caller Records per-PR correction state when fanning out across an epic
x-reconcile-status peer Reads the same file to diagnose drift against markdown; never mutates concurrently with this skill (Rule 22)
x-evaluate-parallelism consumer Reads the resulting state file to build the collision matrix

Downstream stories that depend on this PILOT: story-0049-0013, story-0049-0018, story-0049-0019.

04 同仓库更多 Skills

review-bench
review-bench/edercnj_ia-dev-environment

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 / x-story-plan, applies the parallelism-heuristics knowledge pack (hard / regen / soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

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 / regen / 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.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

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/auto-detected from ProjectConfig.documentation.targets. Returns exit non-zero on staleness; produces structured report.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

x-update-system-architecture

Incrementally updates docs/architecture/system.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/integration changes into sections 1-10 via Edit. Idempotent: re-running with the same epic produces a byte-identical system.md.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0