AGENT SKILL

x-reconcile-status

Reconciles execution-state.json (telemetry) against the **Status:** field of Epic / Story markdown artifacts. Default mode (diagnose) is read-only and prints a divergence table. Opt-in --apply rewrites the markdowns atomically via StatusFieldParser and commits via x-commit-changes. Respects Rule 19 (legacy v1 epics skip silently) and Rule 22 (markdown is SoT; state.json is telemetry). Use for manual recovery of legacy epics whose markdown status drifted from execution checkpoints.

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

01 前言 Front Matter

name
x-reconcile-status
category
ops
description
Reconciles execution-state.json (telemetry) against the **Status:** field of Epic / Story markdown artifacts. Default mode (diagnose) is read-only and prints a divergence table. Opt-in --apply rewrites the markdowns atomically via StatusFieldParser and commits via x-commit-changes. Respects Rule 19 (legacy v1 epics skip silently) and Rule 22 (markdown is SoT; state.json is telemetry). Use for manual recovery of legacy epics whose markdown status drifted from execution checkpoints.
allowed-tools
Read, Write, Edit, Bash, Grep, Glob, Skill, AskUserQuestion
argument-hint
--epic XXXX | --story story-XXXX-YYYY [--apply] [--non-interactive] [--dry-run]
context-budget
light
user-invocable
true
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.

Skill: Status Reconciler

Purpose

Reconcile drift between ai/epics/epic-XXXX/execution-state.json (telemetry, per RULE-046-07) and the canonical **Status:** field of Epic / Story markdown artifacts (source of truth, per Rule 22 — Lifecycle Integrity).

Typical use case: legacy epic EPIC-0024 has 16 stories with status: SUCCESS in execution-state.json but every story markdown still says **Status:** Pendente. Running /x-reconcile-status --epic 0024 --apply rewrites the 16 markdowns (plus the epic-level rollup) and emits a single audit commit.

Triggers

  • /x-reconcile-status --epic 0024 — diagnose mode (read-only)
  • /x-reconcile-status --epic 0024 --apply — apply + commit
  • /x-reconcile-status --epic 0024 --apply --non-interactive — CI
  • /x-reconcile-status --story story-0024-0005 --apply — narrow scope
  • /x-reconcile-status --epic 0024 --apply --dry-run — force diagnose even with --apply

Parameters

Parameter Required Description
--epic XXXX one of (--epic, --story) Full epic scope
--story story-XXXX-YYYY one of (--epic, --story) Single-story scope
--apply no Rewrites markdowns + commits; default is diagnose
--non-interactive no Skips the PROCEED/FIX/ABORT gate (assumes PROCEED)
--dry-run no Forces diagnose output even when --apply is present

Exit Codes

Code Name Meaning
0 SUCCESS No divergence OR diagnose mode
10 APPLIED --apply succeeded (commit created)
20 STATUS_SYNC_FAILED Markdown write failure
30 STATE_FILE_INVALID execution-state.json missing or malformed
40 STATUS_TRANSITION_INVALID Suspicious transition (e.g., CONCLUIDA→PENDENTE)
50 USER_ABORTED Operator chose ABORT at gate

Workflow

Phase 0 — Parse args + locate epic dir

  1. Extract epic id from --epic XXXX or parse story id from --story.
  2. Resolve ai/epics/epic-XXXX/execution-state.json.
  3. If the file is absent → exit 30 with stderr explanation.

Phase 1 — Rule 19 check

Delegate to LifecycleReconciler.isLegacyV1(epicDir). When true, print "legacy epic; skipping per Rule 19" and exit 0 without any side effect.

Phase 2 — Diagnose

Call LifecycleReconciler.diff(epicDir) and render a table:

Divergence report for epic 0024:
  story-0024-0001.md: Pendente → Concluída
  story-0024-0002.md: Pendente → Concluída
  ...
  epic-0024.md:       Em Andamento → Concluída

Total divergences: N

When --apply is NOT present (or --dry-run forces diagnose), print the final JSON with "mode": "diagnose" and exit 0.

Phase 3 — Gate (only when --apply and NOT --non-interactive)

Present the canonical 3-option menu (reuse Rule 20 / EPIC-0043 when available):

AskUserQuestion(
  question: "N divergences detected for epic XXXX. Apply?",
  options: [
    { header: "Proceed", label: "Continue (Recommended)",
      description: "Apply all markdown rewrites and commit." },
    { header: "Fix",     label: "Regenerate diagnose",
      description: "Re-run diagnose with verbose detail; menu reappears." },
    { header: "Abort",   label: "Cancel",
      description: "Exit 50 — no markdown is touched." }
  ]
)
  • PROCEED → Phase 4
  • FIX → re-render diagnose with each Divergence's file path; menu reappears (max 3 iterations, RULE-20 guard-rail)
  • ABORT → exit 50

Phase 4 — Apply + commit

  1. LifecycleReconciler.apply(divergences) — validates every transition against LifecycleTransitionMatrix BEFORE any write (atomicity). A forbidden transition → exit 40.

  2. Delegate the commit to x-commit-changes via Rule 13 INLINE-SKILL:

    Skill(skill: "x-commit-changes",
          args: "--type chore --scope epic-XXXX --subject 'reconcile lifecycle status backfill'")
    
  3. On success, print the final JSON with "mode": "apply", "commitSha": "<sha>", and exit 10.

Final JSON contract (last line of stdout)

{
  "status": "APPLIED",
  "epicId": "0024",
  "divergences": [
    {"artifact": "story-0024-0001.md",
     "from": "Pendente", "to": "Concluída"}
  ],
  "divergenceCount": 33,
  "commitSha": "abc1234",
  "mode": "apply"
}

Consumer tests parse the final line as JSON; everything preceding is human-readable diagnostics.

Invariants

  • NEVER writes execution-state.json (RULE-046-07).
  • NEVER modifies files outside ai/epics/epic-XXXX/ (path canonicalization; no traversal).
  • Every markdown write goes through StatusFieldParser (atomic temp-file + rename, per Rule 22).
  • Legacy v1 epics are NEVER upgraded implicitly (Rule 19).
  • Commit is created iff --apply AND divergences exist AND gate = PROCEED AND apply() succeeds.

Error Handling

Condition Action
--epic and --story both missing exit 2 with usage
execution-state.json missing or malformed exit 30
Legacy v1 epic exit 0 with "skipping" message
Forbidden transition exit 40; no markdown rewritten
Markdown write failure exit 20; partial writes possible (rare — rename is atomic); operator inspects git status
Gate → ABORT exit 50; working tree unchanged

Related

  • Rule 22 — Lifecycle Integrity (SoT contract).
  • Rule 19 — Backward Compatibility (v1 skip).
  • Rule 20 — Interactive Gates Convention (PROCEED / FIX / ABORT).
  • Rule 13 — Skill Invocation Protocol (INLINE-SKILL for x-commit-changes).
  • Helpers: StatusFieldParser, LifecycleTransitionMatrix, LifecycleReconciler (story-0046-0001 + 0046-0006).

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