6.5 KiB
6.5 KiB
Planning-artifact reconciliation
Use this procedure when Scope, Architecture, Kanban, Ways of Working, Engineering, or release-readiness documentation changes while Feature implementation remains gated.
Procedure
- Read the latest same-project channel activity and identify human actions separately from Hermes-authored status reports.
- Re-fetch the documentation repository and resolve the current remote default/test head. Do not reuse a SHA from an earlier channel report.
- Read back relevant pull requests and distinguish
open,closed, andmerged; a human merge is evidence that documentation landed, not evidence that a Feature changed lifecycle state. - Resolve the current source ref and full head SHA from the fresh PR API response before fetching. Do not infer the branch name from a PR title, an older checkout, a prior report, or a similarly named local branch. Fetch that exact
head.refinto an unambiguous temporary remote-tracking ref, create a clean detached worktree from it, and assertgit rev-parse HEADequals the API-reported full SHA before validation. - Validate the exact head in that clean or detached worktree using the repository's own validation command. Explicitly execute package-manager commands with the worktree as the process working directory (or begin the shell block with
cd "$worktree"); setting up the worktree in an earlier command does not make it the current directory for a later process. Install dependencies with the repository's declared frozen-lockfile command when the clean worktree has no installed dependencies. If the package manager shim is unavailable, use the repository-declared package-manager launcher rather than changing project files. Before running a composite package script, verify that child scripts can resolve the package-manager executable too:corepack pnpm validatecan start successfully yet fail whenvalidateinvokes nestedpnpm ...commands. In that case, create a writable temporary shim directory withcorepack enable --install-directory <cache>/pnpm-bin, prepend it toPATH, and run the declared command (for example,PATH=<cache>/pnpm-bin:$PATH pnpm validate). Keep the shim and dependency cache outside committed content, rungit diff --check, and confirm the worktree remains clean afterward. - Query Gitea Actions tasks and match the full exact head SHA. Require each matching task to report
success; do not transfer a PR-head result to the eventual merge head. Keep Gitea identifiers distinct: the Actions task APIid, itsrun_number, and any UI run URL/ID are separate fields and may not have the same value. Report the exact field actually returned by the verified endpoint (for example,task id 684, run_number 66) rather than relabeling a channel-reported UI run ID as a task ID. - Read back the changed planning artifacts through the authenticated raw-file API at the exact PR source ref and verify their semantics, not merely keyword presence. Headings and lifecycle guidance naturally contain terms such as
READY_FOR_DELIVERY, so keyword presence alone does not prove a Task is pickup-ready. For Kanban, assert the exact Task row and status, the evidence timestamp, and any newly cited head/task pairs; also assert superseded pairs are absent when the change claims reconciliation. Parse each lifecycle section independently and verify the Task's actual row rather than using loose whole-file heuristics such as a state-name count. If an automated semantic probe disagrees with the rendered Markdown, read the relevant numbered lines and correct the probe before reporting. - Apply
development-integrity's evidence-first checkpoint sequence immediately before reporting: refresh PR state, source/default refs and exact-SHA tasks. If the source head advanced, revalidate it. If the PR merged or closed during validation, stop calling it open; validate the fresh merge/default SHA in a clean detached worktree, including semantic probes and a successful Actions task with matching fullhead_sha. PR-head CI is not merge-head CI. Refresh again after validation and require PR state, default head, local validated head and latest exact-SHA terminal task to agree. Stay silent if Delivery already reported identical evidence. - Reconcile Kanban separately:
- Proposed Epics/Features may appear in an ideation view.
- An exact Task is Focus-admitted and pickup-ready when its status is
READY_FOR_DELIVERY; there is no second Focus-admission gate. - A newly added Kanban page or merged board does not itself move an exact Task to
READY_FOR_DELIVERY.
- Re-evaluate every implementation gate from the source files and approvals: Approved for Implementation, FR/NFR and ADR context, task/dependency plan, target version, acceptance evidence, and exact Task
READY_FOR_DELIVERYstate. - If the gate remains closed, do not create application changes. A useful delivery activity can be exact-head build/CI verification, durable documentation reconciliation, or a newly evidenced blocker report.
- Before reporting, load
development-integrityfrom its source for evidence-first checkpoint claims, then status-and-reporting.md for Delivery formatting. Retain repository, branch, full SHA, commands/results and exact-SHA task IDs as audit evidence; report only new deltas and the specific missing gate. This reporting load does not change review ownership, gate order, repair/help or scheduler authority.
Evidence interpretation
| Evidence | What it proves | What it does not prove |
|---|---|---|
| Documentation PR merged by a human | The reviewed documentation landed | Feature implementation approval |
| Architecture hierarchy/validator passes | Documentation structure meets its contract | A proposed Feature has an accepted solution |
| Kanban Board lists an item in ideation | The unfinished scope record is visible | Exact Task READY_FOR_DELIVERY handoff |
| Documentation CI succeeds | That documentation head passed its checks | Application CI or release readiness |
| Application baseline CI succeeds | The observed application head is healthy | A new Task PR, deployment, or release |
Avoid duplicate status
Before posting, compare the proposed report with enough Delivery history to find the newest marker, head SHA, CI task, and blocker set. If there is no new human decision, repository head, CI result, actionable failure, or durable documentation change, return the configured silent response instead of restating the same gate.