From f013ad7707b36959ddca891fe0d52f81bba3ee80 Mon Sep 17 00:00:00 2001 From: sechmachine <97589681+sechmachine727@users.noreply.github.com> Date: Sat, 15 Aug 2026 14:18:13 +0700 Subject: [PATCH] docs: define durable fix branch workflow --- AGENTS.md | 1 + DEVELOPMENT.md | 8 ++++ README.md | 6 +++ TESTING.md | 6 +++ ...15-access-navigation-icon-intern-picker.md | 29 +++++++++++++++ ...ss-navigation-icon-intern-picker-design.md | 37 +++++++++++++++++++ 6 files changed, 87 insertions(+) create mode 100644 docs/superpowers/plans/2026-08-15-access-navigation-icon-intern-picker.md create mode 100644 docs/superpowers/specs/2026-08-15-access-navigation-icon-intern-picker-design.md diff --git a/AGENTS.md b/AGENTS.md index d285057..62b065e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -120,6 +120,7 @@ For a multi-branch iteration: - Use one worktree and one named owner/subagent per branch. Tell every owner that other agents share the repository and it must not revert others' work. - Before starting assigned module work, every owner verifies its worktree is clean, fetches or uses the taskmaster-verified latest `main`, and fast-forwards its persistent branch to that exact main SHA. Do not build new work on a stale pre-integration branch, and do not use a merge that would rewrite or discard branch history. +- A targeted repair uses a clean, isolated `work/fix//` branch and worktree from the taskmaster-verified current `main`. Do not use `work//fix/`: the persistent `work/` ref already occupies that Git ref prefix. - Establish and commit the platform foundation before dependent persistence work. - Exchange only full immutable SHAs from clean worktrees; never merge a moving branch or ambiguous short SHA. - Preserve branch ownership. Request a producer-owned service/DTO boundary instead of reading its tables from a consumer. diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 8ae0ef6..6e66971 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -62,6 +62,14 @@ npm ci npm run build ``` +### Use an isolated repair branch + +For a targeted repair, start a clean worktree from the taskmaster-verified +current `main` on `work/fix//`. Keep it separate from the +five persistent `work/` branches. Do not use +`work//fix/` because the persistent `work/` ref +already occupies that Git ref prefix. + ## 3. Start the development containers ### PostgreSQL 18.4 diff --git a/README.md b/README.md index 2fa5fc8..f12babf 100644 --- a/README.md +++ b/README.md @@ -126,6 +126,12 @@ companion record under [`docs/tests`](docs/tests/README.md). | `work/attendance` | Policy, calendar, attendance workflows | | `work/reports-ui` | Shared UI, dashboards, reporting presentation | +For a targeted repair, create a clean isolated branch and worktree from the +taskmaster-verified current `main` named +`work/fix//`. Do not nest it as +`work//fix/`: the persistent `work/` ref already +uses that Git ref prefix. + Iteration 2 work must start from the merged Iteration 1 `main`, continue with strict RED-to-GREEN TDD, add Javadoc during implementation, and update the matching Markdown evidence record before each milestone commit. diff --git a/TESTING.md b/TESTING.md index 5fa17a7..6697aec 100644 --- a/TESTING.md +++ b/TESTING.md @@ -120,6 +120,12 @@ Simple configuration or documentation changes use the smallest useful shell check, followed by the affected Maven suite. Do not create an artificial Java test only to check that a text file exists. +Run that check from the clean targeted-fix branch named +`work/fix//` when repairing one feature. Do not use +`work//fix/`: a persistent `work/` ref already +occupies that Git ref prefix. Record the expected RED and the matching GREEN +shell output in the evidence record. + ## 4. Useful commands Run one test method: diff --git a/docs/superpowers/plans/2026-08-15-access-navigation-icon-intern-picker.md b/docs/superpowers/plans/2026-08-15-access-navigation-icon-intern-picker.md new file mode 100644 index 0000000..59ac8eb --- /dev/null +++ b/docs/superpowers/plans/2026-08-15-access-navigation-icon-intern-picker.md @@ -0,0 +1,29 @@ +# Access, Navigation, Icon, and Intern Picker Fix Plan + +## Scope + +Record the durable workflow for the targeted fixes in this plan. This plan does +not change product behavior, dependencies, schemas, or the five persistent +feature-branch ownership areas. + +## Implementation steps + +1. Prove RED: the contributor guides lack the realizable repair-branch name. +2. Add one branch rule everywhere contributors, coordinators, and requirement + reviewers rely on it: `work/fix//` from verified `main`. +3. State why `work//fix/` is invalid while its persistent + `work/` ref exists. +4. Regenerate the local SRS after amending the existing operational requirement; + do not add a requirement ID or a use case. +5. Prove GREEN with exact searches, requirement/use-case counts, local-link + resolution, and whitespace validation. Commit the tracked guidance locally; + do not push or merge. + +## Exit criteria + +- The tracked guides, design record, implementation plan, and evidence record + agree on the same repair-branch spelling. +- The local authoritative, explained, simple, and generated SRS catalogues keep + exactly 260 unique requirement IDs and the SRS keeps 14 use cases. +- The forbidden nested form is documented only as forbidden, not as a usable + branch name. diff --git a/docs/superpowers/specs/2026-08-15-access-navigation-icon-intern-picker-design.md b/docs/superpowers/specs/2026-08-15-access-navigation-icon-intern-picker-design.md new file mode 100644 index 0000000..ffcac8a --- /dev/null +++ b/docs/superpowers/specs/2026-08-15-access-navigation-icon-intern-picker-design.md @@ -0,0 +1,37 @@ +# Design Record: Durable Fix-Branch Workflow + +- **Date:** 2026-08-15 +- **Status:** Accepted +- **Related plan:** [Access, Navigation, Icon, and Intern Picker Fix Plan](../plans/2026-08-15-access-navigation-icon-intern-picker.md) + +## Context + +The repository keeps five persistent feature refs: `work/platform`, +`work/projects`, `work/tasks`, `work/attendance`, and `work/reports-ui`. +A proposed nested repair name such as `work/platform/fix/example` cannot coexist +with the existing `work/platform` ref because Git cannot use one ref as both a +leaf and a prefix. + +## Decision + +Use `work/fix//` for each targeted repair. Create its clean, +isolated worktree from the taskmaster-verified current `main`. The `` +segment identifies the owning persistent area; it does not nest below that +persistent branch. + +The forbidden form is `work//fix/`. A repair owner preserves +other worktrees, records RED and GREEN evidence, commits locally, and does not +push or merge without separate authority. + +## Consequences + +- Persistent feature branches remain available for their iteration ownership. +- A repair can be reviewed and handed off as one immutable branch head. +- Contributor documentation, local coordination authority, and generated SRS + traceability use the same spelling. + +## Validation + +The documentation evidence record checks the required spelling, rejects the +nested form, verifies requirement counts and generated SRS use-case count, and +resolves local Markdown links.