Skip to content

Add reconcile-opsmill preset overriding speckit.reconcile.run#4

Draft
polmichel wants to merge 8 commits into
mainfrom
pmi-add-reconcile-preset
Draft

Add reconcile-opsmill preset overriding speckit.reconcile.run#4
polmichel wants to merge 8 commits into
mainfrom
pmi-add-reconcile-preset

Conversation

@polmichel

@polmichel polmichel commented Jun 3, 2026

Copy link
Copy Markdown
Contributor

What

New preset presets/reconcile-opsmill/ that overrides /speckit.reconcile.run — the drift-fixing command provided by Stanislav Deviatov's stn1slv/spec-kit-reconcile extension. The override only registers when the reconcile extension is installed in the consumer repo, and removing the preset restores the extension's original command.

The first commit lifts the upstream command body verbatim as the baseline; each adaptation is its own commit so the diff against upstream stays reviewable.

OpsMill adaptations (one commit each)

  • Phase-block task placement — remediation tasks land under ## Phase <N>: blocks (new ## Phase <max+1>: Remediation — Gap Report when none fits) instead of upstream's ## Remediation: Gaps heading, which the taskstoissues-jira fan-out silently skips.
  • Core [P] semantics[P] means "can run in parallel" (spec-kit core), not upstream's priority/urgency flag.
  • Wider compliance gate — CRITICAL-conflict checks also load MUSTs from dev/guidelines/ and decisions from dev/adr/, not just .specify/memory/constitution.md.
  • Jira-aware Next Step — when dev/jira.yml exists, the Sync Impact Report flags that remediation tasks have no Jira issue yet and warns against wholesale /speckit.taskstoissues re-runs (not idempotent).
  • Extraction staleness — reconciling a spec already marked EXTRACTED.md flags that knowledge promoted by /speckit.opsmill.extract may be stale.

Verification

Smoke-tested against specify 0.8.8 in a scratch project: extension install → preset add (skill source flips to preset:reconcile-opsmill, {SCRIPT} resolved, all five adaptations present in the registered body) → preset remove (source reverts to extension:reconcile).

🤖 Generated with Claude Code

polmichel and others added 8 commits June 3, 2026 10:18
New preset in the presets/ collection (v1.1.0) that overrides
speckit.reconcile.run, the drift-fixing command of the
stn1slv/spec-kit-reconcile extension. v1.0.0 of the preset ships the
upstream command body verbatim (MIT, license vendored alongside) as the
baseline for later OpsMill-specific adaptations.

The override only registers when the reconcile extension is installed
in the consumer repo; removing the preset restores the extension's
command. Verified end-to-end against specify 0.8.8 in a scratch
project (install extension -> add preset -> skill source flips to
preset:reconcile-opsmill with {SCRIPT} resolved -> remove preset ->
source reverts to extension:reconcile).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Upstream parks orphan remediation tasks under a '## Remediation: Gaps'
heading. Core spec-kit (tasks-template.md) and the taskstoissues-jira
preset structure tasks.md strictly as '## Phase <N>:' blocks — the Jira
fan-out splits on those headers only, so tasks under any other heading
never become issues. Append a '## Phase <max+1>: Remediation — Gap
Report' block instead.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Upstream redefines [P] on remediation tasks as a priority/urgency flag.
In core spec-kit (tasks-template.md: 'Can run in parallel') and the
taskstoissues-jira preset, [P] is parallelism taxonomy preserved
verbatim on task lines — stamping it as 'urgent' corrupts that signal.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Upstream's CRITICAL-conflict check only reads
.specify/memory/constitution.md. The OpsMill documentation system
promotes durable MUSTs into dev/guidelines/ and decisions into dev/adr/
(via /speckit.opsmill.extract) — remediation items must be checked
against those constraints too.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
In the OpsMill flow, phases are usually fanned out to Jira by the
taskstoissues-jira preset before implementation, so reconcile-appended
remediation tasks exist only in tasks.md. Surface that in the report's
Next Step when dev/jira.yml exists — with an explicit warning not to
re-run /speckit.taskstoissues wholesale (one issue per phase with
unchecked tasks, not idempotent).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
/speckit.opsmill.extract drops EXTRACTED.md in the spec directory once
durable content is promoted to dev/knowledge, dev/guidelines, dev/adr.
Reconcile amends spec.md after the fact, so flag the marker in the Sync
Impact Report and suggest a re-extract once remediation lands.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Preset version 1.0.0 stays in history as the verbatim upstream
baseline; 1.1.0 is what the collection ships. Preset README, presets
CHANGELOG, and top-level README now describe the five adaptations
instead of promising them for later.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The baseline was fetched from stn1slv/spec-kit-reconcile @ 886f1dd;
drop the incidental cross-references to other vendored copies so the
documented lineage is strictly upstream -> opsmill preset.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@polmichel

Copy link
Copy Markdown
Contributor Author

Code review summary (/code-review max)

9 finder angles → verified (1-vote) → gap sweep. 15 findings; 6 candidates refuted along the way (frontmatter ../../scripts/ path is correct — the registrar rewrites it to .specify/scripts/; em-dash phase titles are already normative in the Jira preset's examples; the vendored MIT LICENSE is appropriate).

🔴 Ship-blockers

  1. --subdir flag doesn't exist in specify 0.8.8 preset add, and without it the main.zip can't be discovered (preset.yml isn't at the zip's top dir) — so every documented zip install of this preset fails. Three new instances: README.md:121, presets/reconcile-opsmill/README.md:29, presets/CHANGELOG.md:23. (Inherited from the existing taskstoissues-jira docs, but this PR adds copies.)
  2. Install-order trap (presets/reconcile-opsmill/README.md:22): if the preset is added before the reconcile extension, nothing re-applies the override when the extension arrives later — preset shows installed but the extension body stays active forever. Doc states the skip but not the permanence or the remove+re-add recovery.

🟠 Correctness risks

  1. preset.yml:13>=0.8.0 floor copied from a core-command-override sibling; the extension-command-override mechanism's true floor (≤0.8.8) is unverified. Safest: >=0.8.8.
  2. README.md:19 / :117 — third-party extension pinned to moving refs/heads/main.zip despite an upstream v1.0.0 tag and the body being authored against commit 886f1dd; upstream drift silently desyncs the override.
  3. commands/speckit.reconcile.run.md:144[{story}] placeholder format undefined vs the Jira parser's [US<n>] expectation → US labels silently dropped.
  4. commands/speckit.reconcile.run.md:146 — always-appended [Sync: Gap Report] trailing tag pollutes the Jira preset's file-path extraction and verbatim issue checklists.
  5. commands/speckit.reconcile.run.md:190 — Done Criteria not extended for the two new gates (guidelines/ADR compliance, EXTRACTED.md staleness) → an executing agent can self-certify "done" having skipped them.

🟡 Doc inconsistencies

  1. README.md:110 — "Provided by the preset, not the extension" is wrong: the stn1slv extension does provide /speckit.reconcile.run; the preset only overrides the body.
  2. presets/CHANGELOG.md:11 — "(preset version 1.1.0) — initial release" plus references to a v1.0.0 that exists only as a branch commit (no tag/release/changelog entry); self-contradictory version story (repeated at preset README:5).

⚪ Cleanup / altitude

  1. commands/speckit.reconcile.run.md:57 — Step 0.2 reads all of dev/guidelines/ + dev/adr/ every run; house pattern (extract.md) indexes via first-20-lines. ~5–10× cost in a mature repo.
  2. :185 — recommends /speckit.opsmill.extract and bakes in dev-layout assumptions the Prerequisite section never discloses (preset only declares the stn1slv extension as a dep).
  3. :182 — restates taskstoissues-jira's non-idempotence caveat with no backlink; goes stale when that preset becomes idempotent.
  4. :150 — phase-placement rule justified by naming the sibling parser instead of citing the shared tasks-template.md contract.
  5. preset.yml:21replaces: field is inert (CLI matches on name) but CHANGELOG:17 documents it as the override mechanism.
  6. Five-adaptation list duplicated in full across three files (README:28-33, preset README:7-11, CHANGELOG); already differently worded, will drift.

Proposed fix set for this PR: #1, #2, #4, #7, #8, #9 (all small, contained). The rest are judgment calls / pre-existing conventions.

🤖 Generated with Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant