Files
channel-delivery-skic/references/planning-artifact-reconciliation.md

35 lines
6.5 KiB
Markdown

# 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
1. Read the latest same-project channel activity and identify human actions separately from Hermes-authored status reports.
2. Re-fetch the documentation repository and resolve the current remote default/test head. Do not reuse a SHA from an earlier channel report.
3. Read back relevant pull requests and distinguish `open`, `closed`, and `merged`; a human merge is evidence that documentation landed, not evidence that a Feature changed lifecycle state.
4. 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.ref` into an unambiguous temporary remote-tracking ref, create a clean detached worktree from it, and assert `git rev-parse HEAD` equals the API-reported full SHA before validation.
5. 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 validate` can start successfully yet fail when `validate` invokes nested `pnpm ...` commands. In that case, create a writable temporary shim directory with `corepack enable --install-directory <cache>/pnpm-bin`, prepend it to `PATH`, and run the declared command (for example, `PATH=<cache>/pnpm-bin:$PATH pnpm validate`). Keep the shim and dependency cache outside committed content, run `git diff --check`, and confirm the worktree remains clean afterward.
6. 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 API `id`, its `run_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.
7. 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.
8. 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 full `head_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.
9. 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`.
10. 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_DELIVERY` state.
11. 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.
12. Before reporting, load `development-integrity` from [its source](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/development-integrity) for evidence-first checkpoint claims, then [status-and-reporting.md](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.