Docs: align invariant reconciliation and devcontainer discovery guides with runtime behavior #4485

New issue

Closed

opened 2026-04-08 13:34:17 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-08 13:34:17 +00:00

Owner

Summary

Document the canonical invocation cadence for the InvariantReconciliationActor, including the Strategize gate required by the spec and the additional guard rails executed by PlanLifecycleService before Execute and Apply
Align the devcontainer discovery module guide with the implementation by documenting when discover_devcontainers() raises ValueError (empty location/type) versus when it returns an empty list for non-trigger resource types

Motivation

The documentation review for PR #4381 flagged two accuracy gaps: the new actor API docs overstated when reconciliation runs, and the module guide implied discover_devcontainers() raised on non-trigger types. Capturing these fixes under a tracked issue keeps the documentation synced with the runtime behavior and satisfies the CONTRIBUTING requirement for a closing keyword.

Proposed Changes

Update docs/api/actor.md so the InvariantReconciliationActor section reflects the Strategize requirement, mentions the Execute/Apply guard rails, and cross-references ADR-016 for background
Update docs/modules/devcontainer-discovery.md so the Raises section matches discover_devcontainers() behavior (ValueError only for empty arguments)

Definition of Done

Actor API docs accurately describe when reconciliation runs and cite the relevant ADR
Devcontainer discovery module guide lists the correct circumstances for raising ValueError
Linked PR references this issue with a closing keyword

## Summary - Document the canonical invocation cadence for the `InvariantReconciliationActor`, including the Strategize gate required by the spec and the additional guard rails executed by `PlanLifecycleService` before Execute and Apply - Align the devcontainer discovery module guide with the implementation by documenting when `discover_devcontainers()` raises `ValueError` (empty location/type) versus when it returns an empty list for non-trigger resource types ## Motivation The documentation review for PR #4381 flagged two accuracy gaps: the new actor API docs overstated when reconciliation runs, and the module guide implied `discover_devcontainers()` raised on non-trigger types. Capturing these fixes under a tracked issue keeps the documentation synced with the runtime behavior and satisfies the CONTRIBUTING requirement for a closing keyword. ## Proposed Changes - Update `docs/api/actor.md` so the `InvariantReconciliationActor` section reflects the Strategize requirement, mentions the Execute/Apply guard rails, and cross-references ADR-016 for background - Update `docs/modules/devcontainer-discovery.md` so the Raises section matches `discover_devcontainers()` behavior (ValueError only for empty arguments) ## Definition of Done - [ ] Actor API docs accurately describe when reconciliation runs and cite the relevant ADR - [ ] Devcontainer discovery module guide lists the correct circumstances for raising `ValueError` - [ ] Linked PR references this issue with a closing keyword

HAL9000 added this to the v3.8.0 milestone

2026-04-08 13:35:09 +00:00

~~HAL9000 referenced this issue 2026-04-08 13:35:31 +00:00~~

docs: add InvariantReconciliationActor API docs, devcontainer discovery module guide, and mkdocs nav #4381

HAL9000 referenced this issue

2026-04-08 13:37:59 +00:00

docs: add InvariantReconciliationActor API docs, devcontainer discovery module guide, and mkdocs nav #4381

HAL9000 commented

2026-04-08 13:59:25 +00:00

Author

Owner

MoSCoW classification: Should Have

Rationale: Documentation accuracy is important — the invariant reconciliation and devcontainer discovery guides need to match runtime behavior to avoid developer confusion. However, this is documentation alignment, not a functional blocker. Should Have for v3.8.0.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner

MoSCoW classification: **Should Have** Rationale: Documentation accuracy is important — the invariant reconciliation and devcontainer discovery guides need to match runtime behavior to avoid developer confusion. However, this is documentation alignment, not a functional blocker. Should Have for v3.8.0. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

Rows
Columns