Add intent reconciliation extension

[SuhaibAslam]

What changed

• add a bundled, opt-in reconcile extension
• establish a mandatory pre-implementation intent gate
• capture implementation-discovered decisions in an append-only ledger after each implementation pass
• classify discoveries as implementation defects, contract discoveries, design decisions, intent changes, or accidental divergence
• require explicit human resolution before propagating a decision into intent, specs, plans, tests, tasks, or code
• document the workflow and package the extension in the wheel

Why

Implementation often reveals constraints and decisions that were not knowable when the original spec was written. Convergence can verify code against existing artifacts, but it cannot determine which artifact should change when implementation produces new evidence.

This extension adds that missing authority checkpoint without changing the default SDD workflow. Implementation remains evidence rather than becoming authority by accident.

Developer impact

Teams opt in with:

specify extension add reconcile

The extension then runs:

speckit.reconcile.intent -> speckit.implement -> speckit.reconcile.decisions

Validation

• 123 passed across the focused extension, registration, and skills tests
• 220 passed, 63 skipped across the complete extension test suite
• built the wheel and verified all reconcile extension files are included under specify_cli/core_pack/extensions/reconcile
• git diff --check

Agent disclosure

This change was implemented autonomously on behalf of @SuhaibAslam by Codex (model: GPT-5). The commit includes the required Assisted-by trailer.

[Copilot]

Pull request overview

Adds an opt-in intent reconciliation extension with mandatory implementation hooks and human-authorized decision tracking.

Changes:

• Adds intent and decision reconciliation commands.
• Registers and packages the bundled extension.
• Adds documentation and extension tests.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
extensions/reconcile/extension.yml	Defines commands and lifecycle hooks.
extensions/reconcile/README.md	Documents extension behavior.
extensions/reconcile/commands/speckit.reconcile.intent.md	Defines the pre-implementation intent gate.
extensions/reconcile/commands/speckit.reconcile.decisions.md	Defines decision capture and propagation.
extensions/catalog.json	Registers the bundled extension.
pyproject.toml	Includes extension files in wheels.
docs/toc.yml	Adds reference navigation.
docs/reference/overview.md	Introduces the extension.
docs/reference/agentic-reconciliation.md	Provides workflow documentation.
tests/extensions/reconcile/__init__.py	Initializes the test package.
tests/extensions/reconcile/test_reconcile_extension.py	Tests layout, registration, packaging, and hooks.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

tests/extensions/reconcile/test_reconcile_extension.py:141

• This verifies HookExecutor sorting, but /speckit.implement does not call that API: templates/commands/implement.md reads the hook list from .specify/extensions.yml directly in configured order. Since these tests install git first, the real lifecycle surfaces the Git hook before reconciliation despite priority: 1; docs/reference/extensions.md:224,232 explicitly documents this limitation. Exercise the actual hook-consumption path and either sort hooks when registering them or update the core command path to honor priority.

        hooks = HookExecutor(tmp_path).get_hooks_for_event("after_implement")
        assert hooks[0]["command"] == "speckit.reconcile.decisions"
        assert hooks[0]["priority"] == 1

[mnriem]

Please host this as an extension in your own GitHub repository as per our guide

Nice work!

[SuhaibAslam]

Moved the extension to its own repository as requested:

• Repository: https://github.com/SuhaibAslam/spec-kit-reconcile
• Release: https://github.com/SuhaibAslam/spec-kit-reconcile/releases/tag/v1.0.0
• Catalog submission: [Extension]: Add reconcile #3852
• Standalone commit: 071faea585c0454ea82d5703592ce9aea1111e89

The standalone design also addresses the technical feedback:

• corrected .specify/feature.json lookup to use feature_directory;
• removed lifecycle hooks and the misleading priority assertion;
• added speckit.reconcile.implement as the supported entrypoint;
• added explicit fail-closed status contracts between intent, implementation, and decision phases;
• documented that direct use of core speckit.implement bypasses reconciliation.

Validation includes a clean public-archive install, six focused tests, green GitHub Actions, and real-agent smoke runs confirming unapproved intent blocks before implementation and decision reconciliation returns PENDING without writes.

I am closing this core PR because no core repository change remains after following the publishing guide.

Posted on behalf of @SuhaibAslam by Codex (model: GPT-5, autonomous).