Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 41 additions & 14 deletions .plan/orchestrator/libraries-initial-implementation/epic.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,8 +53,8 @@ Out of scope: `doc/app/` (CISOs-Friend), which gets its own orchestrator epic, a
(`git-timestamp/`).
- PLAN-12 — Can start once PLAN-08 has landed, in parallel with PLAN-09..11 (multi-file overlap on `pom.xml`,
`general.adoc`, `AGENTS.md` → the gate puts it to the operator).
- PLAN-08 — Staged, passes the admission tests, deliberately not emitted with PLAN-21 (three shared files); emit it when PLAN-21 lands.
PLAN-07's analysis folded the bound of `save.max-attempts` into its deliverable 2 (no new surface).
- PLAN-08 — Staged, passes the admission tests; it was deliberately not emitted with PLAN-21 (three shared files), and PLAN-21 has
landed (PR #46, `9e3cfb0`), so it is emittable. PLAN-07's analysis folded the bound of `save.max-attempts` into its deliverable 2 (no new surface).
- PLAN-10, PLAN-12, PLAN-13, PLAN-17 — Each opens with an owner decision on a third-party library; expect a question
early in the plan's refine phase.
- PLAN-18 — Shipped (PR #28). It was the collection plan for the minor leftovers of PLAN-01; once started its spec is
Expand All @@ -70,11 +70,12 @@ Out of scope: `doc/app/` (CISOs-Friend), which gets its own orchestrator epic, a
`main` and reaches the 0.1.0 release unless that is cut first or leaves it out. The operator merged #42 (the AGENTS.md merge
authorisation) and #43 (a comment-only change in `StoreConfiguration.java`) after it. The spec said four deliverables, the lane
reported six (the outline split them, fix tasks followed).
- PLAN-21 — Merge of `git-worktrees` into `git-core` (staged 2026-11-20 on the operator's word): four deliverables, code and tests,
build configuration, specifications, concepts, ADR, client, index and root documents. Its five-file overlap with PLAN-07 is gone
(PLAN-07 shipped), but PLAN-07 added `git-store` to the same documents and the module table, so its outline reads them at
`a558afd`; it runs before PLAN-20 and the 0.1.0 release. Owner decisions inside it (requirement ids, log identifiers, ADR form)
are put to the owner at its outline; the package is decided.
- PLAN-21 — Shipped (PR #46, `9e3cfb0`, `landings/PLAN-21.md`): `git-worktrees` is merged into `git-core` as the package
`de.cuioss.git.document.core.worktrees` (33 paths, +660/-935), the reactor has three modules (`git-core`, `git-store`,
`git-testing`). It ran alone after PLAN-07, emitted alone because it shared three files with PLAN-08. The owner decisions put at its
outline differ from the spec's defaults: the requirement ids were renumbered (`GDR-WT-1..4` became `GDR-CORE-12..15`), the log ids
became INFO 2-4 and WARN 102-104 (the worktrees refusal stays the separate record `WORKTREE_CAPABILITY_REFUSED`), and ADR-0004 was
rewritten in place with no new ADR. The names `GDR-WT-n` and `GIT_WORKTREES` in older landing reports and decisions are superseded.
- PLAN-20 — Second collection plan (staged 2026-11-19 on the operator's word): the layer-3 defects of PLAN-19 and PLAN-04, the
test gaps beside them and the `git-testing` leftovers of PLAN-18, in one plan. **Held back from `next` until the operator
releases it**; later analyses fold further leftovers into it, in the same edit as its Expected Surface. PLAN-05, with
Expand All @@ -86,9 +87,11 @@ Out of scope: `doc/app/` (CISOs-Friend), which gets its own orchestrator epic, a
deliverables, at the split guard, and proceeds unsplit because the operator asked for one collection plan and each
deliverable is independent (the operator may split it when releasing it). PLAN-07's analysis added deliverable 7 (`git-store`: a
token in a remote's query, a throwing `id()`, eager anchor providers, the textual anchor-key check and three test residues) and the
`git-store` entries to its surface; it now has seven deliverables and proceeds unsplit on the same ground. It now depends on PLAN-21: after the merge its
`git-worktrees/` paths move into `git-core`, and the orchestrator re-grounds deliverables 1 and 2, the surface and the claims
when PLAN-21 lands.
`git-store` entries to its surface; it now has seven deliverables and proceeds unsplit on the same ground. PLAN-21 has landed and PLAN-20
was re-grounded in the same act (2026-11-20): its worktrees paths, the spec references (`git-core.adoc` § Working Trees), the Expected
Surface and the Done-when base (`9e3cfb0`) moved into `git-core`, the five worktrees claims were re-stamped at `9e3cfb0`, deliverable 2
gained item (e) (two documentation residues of PLAN-21's analysis) and item (g) of deliverable 7 collapsed (the fourth domain-term copy
went with the module). It is still held back until the operator names it in a `next` round.

## Decisions

Expand Down Expand Up @@ -323,6 +326,21 @@ Out of scope: `doc/app/` (CISOs-Friend), which gets its own orchestrator epic, a
- 2026-11-20 — Emit round after PLAN-07 (nothing in flight): PLAN-08 and PLAN-21 both pass the three admission tests, and share three files
(`AGENTS.md`, `doc/README.adoc`, `doc/specification/general.adoc`). The operator chose PLAN-21 only: the merge comes first (artifact
coordinates before 0.1.0, PLAN-20 depends on it), PLAN-08 stays staged and is emitted when PLAN-21 lands, so there is no hand merge.
- 2026-11-20 — PLAN-21 recorded launched, then running, on the operator's word ("#21 is running"); `auto_emit=false`, so `launched` was
not recorded before the operator confirmed. The outline's three owner questions were answered by the operator (renumber the
requirement ids, merge the log ids under `GIT_CORE` with the worktrees refusal as its own record, rewrite ADR-0004 in place with no new
ADR), which differ from the defaults the spec proposed; the outline then re-froze the success criteria on its own authority and the
operator approved that afterwards through the question tool (the lesson `2026-11-20-07-001`, extended).
- 2026-11-20 — PLAN-21 landed (PR #46, `9e3cfb0`) and was analysed on three layers: no blocker, no major, no layer-3 defect (the move is
behaviour-neutral; the one source change, the S4449 null-check, is neutral); layer 2: one deliberate minor (the worktrees refusal
and `CAPABILITY_REFUSED` carry the same template under ids 102 and 101), one minor residue (the committed
`.plan/project-architecture/` inventory still names the removed module, see Watches) and two documentation infos folded into PLAN-20
deliverable 2 (e). Layer 1: the spec's own text (the `GDR-WT-n` display names, no new ADR, "root pom lists `git-core` and `git-testing`
only") differs from the owner decisions and the base, info. Not shown by reading: the build, the 883 to 882 test count, the Sonar read
(undecidable on a merged PR), and whether JGit commands the package drives reach a translation bundle beyond `JGitText` (GDR-NFR-4).
PLAN-20 was re-grounded in the same act. The seven candidate lessons: six recurrences, one new (`2026-11-20-17-001`, the realized
footprint drops rename sources), plus one new from the landing residue (`2026-11-20-18-001`, the merge-queue squash message carries
the PR body with the review bot's release-notes block).

## Open Defects

Expand Down Expand Up @@ -364,8 +382,12 @@ Out of scope: `doc/app/` (CISOs-Friend), which gets its own orchestrator epic, a
`plan-18-leftover-fixes-016.md`, PLAN-03 `plan-03-git-worktrees-import-020.md`, PLAN-19
`plan-19-git-worktrees-hardening-018.md`, PLAN-04 `git-core-incore-write-cas-017.md`, PLAN-05
`plan-05-git-core-merge-read-notes-013.md`, PLAN-06 `implement-plan-06-build-guards-014.md`, PLAN-07
`plan-07-store-module-registry-spi-011.md`): `inbox landing-check` reports
`complete: false`. PLAN-07 misses `cleanup_owed`, the three review numbers and `sonar_open_new_issues` (all `unknown`: no finalize
`plan-07-store-module-registry-spi-011.md`, PLAN-21 `plan-21-merge-worktrees-into-core-008.md`): `inbox landing-check` reports
`complete: false`. PLAN-21 misses `effort` and the three review numbers (all `unknown`; `cleanup_owed=false` and
`sonar_open_new_issues=0` were supplied); its `review-gate` re-read shows 0 unresolved threads and 1 review-body finding with no
disposition (the lane's own account says four findings, three CodeRabbit and one Sourcery, were all handled; the handled count is not
re-verified), and the Sonar read is undecidable (`head_revision_unavailable` on a merged PR), so `sonar_open_new_issues=0` is not
re-verified either. PLAN-07 misses `cleanup_owed`, the three review numbers and `sonar_open_new_issues` (all `unknown`: no finalize
step records them; `sonar-roundtrip` records `new_code_issue_count=0` under its own name); nothing was re-read. PLAN-06 misses the three review numbers; its `review-gate` re-read is decidable (0 unresolved threads, 3
review-body findings, `handled: 0`) and the Sonar gate reads OK. PLAN-05 misses the three review numbers and `sonar_open_new_issues` (`effort` is `medium`, self-reported); its
`review-gate` re-read is undecidable (the CodeRabbit "Minor comments: 1" section), the Sonar gate reads OK, and
Expand Down Expand Up @@ -402,8 +424,13 @@ Out of scope: `doc/app/` (CISOs-Friend), which gets its own orchestrator epic, a
cannot be withdrawn). PLAN-20 changes the behaviour of public `git-core` and `git-worktrees` operations and adds guards. —
question to the operator, open: release PLAN-20 before 0.1.0, or release 0.1.0 first and carry the fixes into the next version.
PLAN-07 has landed: `git-store` is on `main` and in the reactor, so 0.1.0 would publish it unless the release is cut first or
`git-store` is left out of the cut; PLAN-21 (the merge) should land before the release too, because artifact coordinates are
cheapest to change before it.
`git-store` is left out of the cut. PLAN-21 (the merge) has landed (PR #46), so the artifact `git-worktrees` no longer exists and the
coordinates are settled before 0.1.0; PLAN-20 and the remaining `git-store` plans are what is still open against the cut.
- The committed architecture inventory `.plan/project-architecture/` still names the removed module `git-worktrees` (`_project.json`,
`git-document-repository/enriched.json` and a whole `git-worktrees/enriched.json`) after PLAN-21 (`landings/PLAN-21.md` L2-4). It is
derived data of the steward, not repository source, and `.plan/` was outside the plan's content search, so no Done-when is broken. —
regenerate it with the plan-marshall architecture refresh (an operator or steward act, not a queue row); open until then. It can
mislead module resolution (`manage-architecture which-module`) for paths of the merged package.
- The execution manifest of PLAN-04 carried `final_merge_without_asking=true`, which contradicted the AGENTS.md rule "do not merge
unless the user says so". — resolved by the operator's #42 (`3c609a7`): AGENTS.md on `main` now authorises a plan-marshall run
to merge its own pull request once the checks are green and every review comment is handled (never a PR that changes
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
envelope_version=1
sender_type=plan
sender_id=plan-21-merge-worktrees-into-core
epic=libraries-initial-implementation
kind=candidate-lesson
created=2026-11-20T17:45:58Z

## Candidate lesson: the outline step re-froze success criteria on its own authority

Source plan: plan-21-merge-worktrees-into-core (PLAN-21, PR #46). Phase: 3-outline.

What happened. On outline re-entry with relayed operator answers (wt_ids, log_ids, adr_form), the outline leaf wrote a `criteria-integrity` decision that authorized re-freezing the criteria snapshot itself, citing those answers (decision log 2026-11-20T15:34:56Z, hash b71121). The answers changed frozen success criteria of deliverables 1-4: they renumbered GDR-WT-1..4 to GDR-CORE-12..15, which overrides the spec's Done-when on the GDR-WT-n display names, and chose to rewrite ADR-0004 in place with no ADR-0009. The orchestrator then had to get the operator to approve the re-freeze (25 criteria) after the fact through the question tool (decision log 15:36:40Z, hash b2b52a).

Why it matters. A re-freeze of frozen criteria is an operator decision. An answer to a design question is not consent to drop or replace a frozen criterion, and a dispatched leaf cannot reach the operator to confirm it.

Candidate corrective rule. When applying relayed answers would replace or override a frozen success criterion, the outline step returns a prompt-required envelope that names the affected criteria. It does not record an authorizing `criteria-integrity` decision on its own. The orchestrator asks the operator, and only the operator's answer authorizes the re-freeze.

Likely owning component: plan-marshall:phase-3-outline (the criteria-integrity re-freeze path).
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
envelope_version=1
sender_type=plan
sender_id=plan-21-merge-worktrees-into-core
epic=libraries-initial-implementation
kind=candidate-lesson
created=2026-11-20T17:46:09Z

## Candidate lesson: a success criterion named a file its verification command never checked

Source plan: plan-21-merge-worktrees-into-core (PLAN-21, PR #46). Phase: 3-outline Q-Gate.

What happened. The success criterion of deliverable 4 read "The AsciiDoc link check over doc/ and over README.adoc reports nothing unresolved". The deliverable's verification command ran only `asciidoc verify-links --directory doc --recursive`, so the root README.adoc, which lies outside doc/, was never checked. The outline Q-Gate scope_criterion_validator caught it as under_coverage (finding e18e3f, severity warning, file README.adoc). It was resolved taken_into_account: TASK-005 verification gained a second call, `asciidoc verify-links --file README.adoc`.

Why it matters. The gate caught it this time. The authoring gap is the general one: a criterion that names several scopes (a directory plus a root-level file) must have a verification command for each named scope. A directory-recursive check does not reach a file at the repository root.

Candidate corrective rule. When the outline writes a success criterion that names more than one scope, it writes one verification call per scope, or narrows the criterion to what the command checks. A root-level file named beside a directory gets its own file-scoped check.

Likely owning component: plan-marshall:phase-3-outline (deliverable verification authoring). The Q-Gate validator worked as intended.
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
envelope_version=1
sender_type=plan
sender_id=plan-21-merge-worktrees-into-core
epic=libraries-initial-implementation
kind=candidate-lesson
created=2026-11-20T17:46:23Z

## Candidate lesson: a Sonar finding in moved code cost a full loop-back round

Source plan: plan-21-merge-worktrees-into-core (PLAN-21, PR #46). Phase: 6-finalize sonar-roundtrip and triage.

What happened. The plan moved the git-worktrees code into git-core as the package de.cuioss.git.document.core.worktrees, with no behaviour change. Sonar analysed the moved file as new code and reported java:S4449 (MAJOR code smell) at JGitWorktreeOperations.java:500: a possibly-null `getObjectId()` result was passed to `StartPoint.of` (finding 6fc761, Sonar key AaH5xw0Z3vkKQN2l-ecl). The operator chose to fix it in the PR: read `getObjectId()` once into a local, null-check it, then pass it on (decision log 16:35:34Z). This added TASK-006 and loop-back iteration 1/3 from 6-finalize to 5-execute (commit 6b45edb). It also re-ran the simplify step, the pre-push quality gate, push and CI, and the review-bot round, which then waited out a CodeRabbit rate window of 2100 s.

Why it matters. A move or rename makes every relocated line new code to Sonar, so issues the old module already had reappear on the PR. The finding was only found after the PR was opened, where each fix costs a whole loop-back.

Candidate corrective rule. When a plan moves or renames source files, check the moved files for open Sonar issues (or run the equivalent static check) before the PR is opened. Then either fix them in the move deliverable or record a decision to accept them. Do not find them first in the post-PR sonar-roundtrip.

Likely owning component: plan-marshall:phase-6-finalize (sonar-roundtrip timing), or the phase-3-outline handling of tech_debt / move change types.
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
envelope_version=1
sender_type=plan
sender_id=plan-21-merge-worktrees-into-core
epic=libraries-initial-implementation
kind=candidate-lesson
created=2026-11-20T17:46:34Z

## Candidate lesson: the simplify and quality-gate steps re-ran in full for a 3-line loop-back commit

Source plan: plan-21-merge-worktrees-into-core (PLAN-21, PR #46). Phase: 6-finalize, after loop-back.

What happened. The loop-back commit 6b45edb was a behaviour-neutral, 3-line null-check in one file (TASK-006, Sonar java:S4449). After it landed, 6-finalize re-fired `finalize-step-simplify` because the verdict was invalidated (work log 16:43:51Z: "verdict_currency=invalidated, verdict_inputs_undeclared"). It also re-ran the `pre-push-quality-gate` as four whole-tree Maven builds (16:44:27Z to 16:47:26Z). This came on top of the two builds 5-execute had already run for the same commit (verify:quality-gate and verify:module-tests, 16:38:22Z to 16:42:34Z).

Why it matters. The re-run was triggered because the simplify step declares no verdict inputs, so any new commit invalidates its verdict whatever the commit touched. The quality gate repeated builds that 5-execute had just passed on the same HEAD. For a small loop-back fix, that is most of the round's time.

Candidate corrective rule. Steps that re-fire after a loop-back should declare their verdict inputs, so a commit outside those inputs, or below a size threshold, keeps the earlier verdict. The pre-push quality gate should reuse a green 5-execute verify on the same HEAD instead of rebuilding.

Likely owning components: plan-marshall:phase-6-finalize (finalize-step-simplify verdict currency, pre-push-quality-gate reuse).
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
envelope_version=1
sender_type=plan
sender_id=plan-21-merge-worktrees-into-core
epic=libraries-initial-implementation
kind=candidate-lesson
created=2026-11-20T17:46:50Z

## Candidate lesson: manage-findings qgate calls were rejected by argparse (an invented verb, then a missing flag)

Source plan: plan-21-merge-worktrees-into-core (PLAN-21, PR #46). Signal: script-failure cluster, notation plan-marshall:manage-findings:manage-findings (signal-scan: script_failure class).

What happened. Two calls to the same notation in this run were rejected by argparse (exit 2):

1. 3-outline re-entry, work log 2026-11-20T15:31:29Z (hash c3533b): a call to `manage-findings qgate query`. `query` is not a registered verb. The registered `qgate` verbs are add, clear, list, resolve, resolve-by-rule and resolve-evidenced.
2. 6-finalize lessons-capture, work log 17:45:06Z (hash 771256): a call to `manage-findings qgate list --plan-id ...` without `--phase`, which `qgate list` requires. This was the lessons-capture leaf itself, reading the Q-Gate findings to write these candidates. It retried with `--phase 3-outline`.

Why it matters. The first is the verb-paraphrase signature (a likely-sounding verb taken from the prose, not from the script's surface). The second is the missing-required-flag signature: a reader wants every phase at once, but `qgate list` only answers per phase. Both cost a retry. The second also means a caller that wants Q-Gate findings across all phases has to make five calls.

Candidate corrective rule. Take the verb and flag set from the script's canonical-invocation block or its `--help`, never from workflow prose. For the owning component, consider letting `qgate list` omit `--phase` to list every phase, because the lessons-capture body reads Q-Gate findings across 2-refine through 6-finalize.

Related, outside this signal's count: `manage-change-ledger append` was also rejected twice with exit 2 on an undeclared `--changed-paths-file` and retried with `--changed-paths` (work log 15:57:45Z and 16:40:28Z, phase-5-execute). Those were logged as plain [ERROR] lines, not script_failure markers.

Likely owning components: plan-marshall:manage-findings (qgate list surface), plan-marshall:phase-3-outline (the call site of the invented verb), plan-marshall:phase-5-execute (the change-ledger call site).
Loading