diff --git a/.agents/PROJECT_PLAN.md b/.agents/PROJECT_PLAN.md index 49617b7..2fec728 100644 --- a/.agents/PROJECT_PLAN.md +++ b/.agents/PROJECT_PLAN.md @@ -55,6 +55,7 @@ Conflict-prevention rules: - `work/platform` owns `src/main/resources/db/migration/**`, Maven/dependency configuration, Compose, container build files, and CI workflow files. Other branches request schema changes instead of independently allocating migration versions. - `work/reports-ui` owns shared templates/fragments, shared design tokens, and general UI assets. Each domain branch owns its module-specific controllers and pages while consuming those shared fragments. +- A targeted repair shall use 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. - `work/tasks` exposes focused Task query/transfer operations required by Project workflows. `work/projects` owns the transaction that removes a member or completes a Project. - `work/platform` owns HolidayAPI credential storage and the tested HTTP client. `work/attendance` owns preview interpretation, selection, deduplication, import, and day-off effects. - Attendance time and Task work time remain separate. No branch may make one mutate or prove the other. diff --git a/.agents/skills/orchestrate-labtimesheet-iteration/SKILL.md b/.agents/skills/orchestrate-labtimesheet-iteration/SKILL.md index 6eefa35..245e4c5 100644 --- a/.agents/skills/orchestrate-labtimesheet-iteration/SKILL.md +++ b/.agents/skills/orchestrate-labtimesheet-iteration/SKILL.md @@ -70,6 +70,11 @@ Use exactly these persistent branches unless the user changes the plan: | `work/attendance` | Policy, calendar, attendance, corrections, leave, metrics | | `work/reports-ui` | Shared Thymeleaf UI, dashboards, reports, exports | +For a targeted repair outside the next iteration, create a clean isolated +`work/fix//` worktree from the taskmaster-verified current +`main`. Do not use `work//fix/`: the persistent +`work/` ref already occupies that Git ref prefix. + Create one isolated worktree per branch. Give each implementation agent explicit ownership, tell it other agents share the repository, forbid reverting others' work, require medium-milestone local commits, and forbid push unless separately authorized. Before any owner edits its module, require it to: diff --git a/AGENTS.md b/AGENTS.md index d285057..353fe91 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -120,6 +120,8 @@ 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. +- Every targeted repair starts from the taskmaster-verified latest `main`, uses TDD RED → GREEN, adds Javadoc during implementation, records companion evidence, undergoes independent review, and uses a normal, non-force merge only when separately authorized. - 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..350b893 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -62,6 +62,16 @@ 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. + +Every targeted repair starts from the taskmaster-verified latest `main`, uses TDD RED → GREEN, adds Javadoc during implementation, records companion evidence, undergoes independent review, and uses a normal, non-force merge only when separately authorized. + ## 3. Start the development containers ### PostgreSQL 18.4 diff --git a/PRODUCT.md b/PRODUCT.md index 6eedce0..177f00b 100644 --- a/PRODUCT.md +++ b/PRODUCT.md @@ -79,6 +79,7 @@ The product joins attendance oversight and Project delivery without pretending t 3. **Attendance and Project work stay distinct.** The product may report them together, but one never derives or proves the other. 4. **Deadlines are enforced at every path.** Scheduled workers improve timeliness, while request-time guards preserve correctness when scheduling is late. 5. **Prefer explicit, reviewable operations.** Feature-owned controller/service/repository flows, constrained state transitions, focused integrations, and shared report datasets serve clarity over speculative machinery. +6. **Fixes preserve branch ownership.** A targeted repair uses a clean `work/fix//` branch from verified `main`, not `work//fix/`; persistent `work/` refs already occupy that Git ref prefix. ## Accessibility & Inclusion diff --git a/README.md b/README.md index 2fa5fc8..e8be202 100644 --- a/README.md +++ b/README.md @@ -126,6 +126,14 @@ 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. + +Every targeted repair starts from the taskmaster-verified latest `main`, uses TDD RED → GREEN, adds Javadoc during implementation, records companion evidence, undergoes independent review, and uses a normal, non-force merge only when separately authorized. + 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..1cf3015 100644 --- a/TESTING.md +++ b/TESTING.md @@ -120,6 +120,14 @@ 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. + +Every targeted repair starts from the taskmaster-verified latest `main`, uses TDD RED → GREEN, adds Javadoc during implementation, records companion evidence, undergoes independent review, and uses a normal, non-force merge only when separately authorized. + ## 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..4900915 --- /dev/null +++ b/docs/superpowers/plans/2026-08-15-access-navigation-icon-intern-picker.md @@ -0,0 +1,35 @@ +# 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 to contributor guides, design records, plans, and tracked + coordination authority: `work/fix//` from verified + `main`. +3. State why `work//fix/` is invalid while its persistent + `work/` ref exists. + +Every targeted repair starts from the taskmaster-verified latest `main`, uses TDD RED → GREEN, adds Javadoc during implementation, records companion evidence, undergoes independent review, and uses a normal, non-force merge only when separately authorized. + +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 the executable six-guide regression that independently + rejects a positive nested-form recommendation in every guide, + coordination-authority consistency, requirement/use-case counts, local-link + resolution, and an immutable base-to-candidate whitespace check. Commit the + tracked guidance locally; do not push or merge. + +## Exit criteria + +- The tracked guides, design record, implementation plan, root coordination + authority, 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..c9fcf2c --- /dev/null +++ b/docs/superpowers/specs/2026-08-15-access-navigation-icon-intern-picker-design.md @@ -0,0 +1,42 @@ +# 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. + +Every targeted repair starts from the taskmaster-verified latest `main`, uses TDD RED → GREEN, adds Javadoc during implementation, records companion evidence, undergoes independent review, and uses a normal, non-force merge only when separately authorized. + +## 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 executable documentation validator checks the exact approved statement in +each of the six tracked guides and independently rejects an injected positive +nested-branch recommendation in every guide. The copied root coordination +authority uses the same rule and is checked separately for consistency. The +evidence record also verifies requirement counts, generated SRS use-case count, +and local Markdown links. diff --git a/docs/tests/unit/fix-branch-workflow-documentation.md b/docs/tests/unit/fix-branch-workflow-documentation.md new file mode 100644 index 0000000..34f06ae --- /dev/null +++ b/docs/tests/unit/fix-branch-workflow-documentation.md @@ -0,0 +1,210 @@ +# Test Evidence: durable fix-branch documentation workflow + +- **Test type:** Unit (documentation contract) +- **Requirement IDs:** `OPS-019`, `TST-009`, `TST-010` +- **Scenario IDs:** `AC-TST-001` +- **Test class/method:** `scripts/verify-fix-branch-workflow.cjs --self-test` +- **Implementation commit:** `f013ad7707b36959ddca891fe0d52f81bba3ee80` +- **Round-1 review-fix commits:** `d617769499362e92d058684501af3c1ae6b145b0`, `719e02ea902bfb2dbeddc04f12be3617be3427b5` +- **Round-2 all-guide regression commit:** `97e991317d55db4f7414678a89a45921802a14b8` +- **Round-2 coordination-authority commit:** `9802d5d17f5c07511e1f9cf59ace4b7e48fcdc0e` +- **Round-2 plan-contract commit:** `f98e7f39ef38c7882106ffb250155d2a72dcf0dd` +- **Round-3 complete-workflow commit:** `445e4fedeb0e06724b876c5731437d2c355cacb2` + +## Protected behavior + +Targeted repairs use the realizable `work/fix//` branch and +clean worktree from taskmaster-verified `main`. Contributor guidance must reject +the impossible `work//fix/` form while persistent +`work/` refs exist. The tracked copies of root coordination authority +must use the same rule. Every targeted-fix guide must also require the complete +lifecycle: latest `main`, TDD RED → GREEN, Javadoc during implementation, +companion evidence, independent review, and an authorized normal, non-force +merge. + +## Test method + +Use the tracked Node validator rather than an artificial Java test. It requires +the exact approved branch statement and complete targeted-repair lifecycle in +each of the six guides. Its self-test independently removes each of the six +lifecycle elements from every guide and asserts the file-specific rejection. It +also retains a fresh positive nested-branch mutation for every guide. The copied +root coordination files are compared byte-for-byte with their main-root sources +and checked for their exact approved rules. The original RED proves the +required branch name was absent from the four contributor guides; the first +review-fix RED proves the executable regression was absent. + +## Hand-derived expected result + +The required fix-branch spelling appears exactly once in each of the six tracked +documentation artifacts, and the only nested-form reference is inside that +artifact's exact approved statement. Each independent simulated positive +nested-branch recommendation must fail. The three tracked coordination files +must exactly match the authorized main-root versions. Loss of any lifecycle +element from any guide must fail. The existing SRS generator must still report +260 requirements and 14 use cases. + +## RED + +**Command** + +```text +rg -n -F 'work/fix//' AGENTS.md README.md DEVELOPMENT.md TESTING.md +``` + +**Observed result** + +```text +exit 1; no matching lines +``` + +The failure was expected: the required realizable repair-branch rule was absent +before this documentation change. + +### Review-fix RED + +**Command** + +```text +node scripts/verify-fix-branch-workflow.cjs --self-test +``` + +**Observed result** + +```text +exit 1 +Error: Cannot find module '.../scripts/verify-fix-branch-workflow.cjs' +``` + +The executable regression required to reject a positive nested-branch +recommendation did not exist. + +### Round-2 RED + +**Command** + +```text +node scripts/verify-fix-branch-workflow.cjs --self-test | rg -x 'Positive nested branch recommendations: 6/6 rejected' +``` + +**Observed result** + +```text +exit 1; no matching line +``` + +The prior self-test reported only a singular rejection and mutated only +`AGENTS.md`; it did not prove an independent rejection for each of the six +guides. + +### Round-3 RED + +**Command** + +```text +node --check scripts/verify-fix-branch-workflow.cjs +node scripts/verify-fix-branch-workflow.cjs --self-test +``` + +**Observed result** + +```text +exit 1 +Error: AGENTS.md must contain the complete required targeted-repair workflow exactly once +README.md must contain the complete required targeted-repair workflow exactly once +DEVELOPMENT.md must contain the complete required targeted-repair workflow exactly once +TESTING.md must contain the complete required targeted-repair workflow exactly once +docs/superpowers/specs/2026-08-15-access-navigation-icon-intern-picker-design.md must contain the complete required targeted-repair workflow exactly once +docs/superpowers/plans/2026-08-15-access-navigation-icon-intern-picker.md must contain the complete required targeted-repair workflow exactly once +``` + +The six guides had branch naming but not the complete lifecycle contract. + +## Initial GREEN + +**Command** + +```text +node scripts/verify-fix-branch-workflow.cjs --self-test +``` + +**Observed result** + +```text +Fix-branch workflow documentation: 6 approved statements validated +Positive nested branch recommendation: rejected +``` + +### Round-2 GREEN + +**Command** + +```text +node --check scripts/verify-fix-branch-workflow.cjs +node scripts/verify-fix-branch-workflow.cjs --self-test +``` + +**Observed result** + +```text +Fix-branch workflow documentation: 6 approved statements validated +Positive nested branch recommendations: 6/6 rejected +``` + +### Round-3 GREEN + +**Command** + +```text +node --check scripts/verify-fix-branch-workflow.cjs +node scripts/verify-fix-branch-workflow.cjs --self-test +``` + +**Observed result** + +```text +Fix-branch workflow documentation: 6 approved statements validated +Targeted-repair workflow element removals: 36/36 rejected +Positive nested branch recommendations: 6/6 rejected +``` + +## Affected suite + +**Command and result** + +```text +node labtimesheet-docs-hub/ui-mockups/build-srs.cjs +node -e 'const fs=require("node:fs"); const checks=[["authoritative","labtimesheet-docs-hub/requirements-specification.md",/^\| ([A-Z]{2,4}-\d{3}) \|/gm],["explained","labtimesheet-docs-hub/explained/requirements-specification.md",/^\| ([A-Z]{2,4}-\d{3}) \|/gm],["simple","labtimesheet-docs-hub/explained/requirements-specification-simple.md",/^- \*\*([A-Z]{2,4}-\d{3}):\*\*/gm],["generated SRS","labtimesheet-docs-hub/software-requirements-specification.md",/^\| ([A-Z]{2,4}-\d{3}) \|/gm]]; for (const [name,file,pattern] of checks) { const ids=[...fs.readFileSync(file,"utf8").matchAll(pattern)].map(match=>match[1]); if (ids.length !== 260 || new Set(ids).size !== 260) throw new Error(`${name}: ${ids.length} rows, ${new Set(ids).size} unique`); console.log(`${name}: ${ids.length} rows, ${new Set(ids).size} unique IDs`); } const srs=fs.readFileSync("labtimesheet-docs-hub/software-requirements-specification.md","utf8"); const useCases=(srs.match(/^### 5\.\d+ UC-\d{2} —/gm)||[]).length; if (useCases !== 14) throw new Error(`SRS use cases: ${useCases}`); console.log(`generated SRS: ${useCases} use cases`);' +node -e 'const fs=require("node:fs"); const path=require("node:path"); let checked=0; const broken=[]; for (const file of process.argv.slice(1)) { const text=fs.readFileSync(file,"utf8"); for (const match of text.matchAll(/!?\[[^\]]*\]\(([^)]+)\)/g)) { const target=match[1].trim().replace(/^<|>$/g,"").split("#")[0].split("?")[0]; if (!target || /^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith("//")) continue; checked += 1; if (!fs.existsSync(path.resolve(path.dirname(file), decodeURIComponent(target)))) broken.push(`${file}: ${target}`); } } if (broken.length) throw new Error(`Broken local Markdown links:\n${broken.join("\n")}`); console.log(`Local Markdown links: ${checked} resolved`);' AGENTS.md README.md DEVELOPMENT.md TESTING.md docs/superpowers/specs/2026-08-15-access-navigation-icon-intern-picker-design.md docs/superpowers/plans/2026-08-15-access-navigation-icon-intern-picker.md docs/tests/unit/fix-branch-workflow-documentation.md +cmp -s .agents/PROJECT_PLAN.md /Users/sechmachine/Documents/WebProjects/labtimesheet/.agents/PROJECT_PLAN.md && cmp -s .agents/skills/orchestrate-labtimesheet-iteration/SKILL.md /Users/sechmachine/Documents/WebProjects/labtimesheet/.agents/skills/orchestrate-labtimesheet-iteration/SKILL.md && cmp -s PRODUCT.md /Users/sechmachine/Documents/WebProjects/labtimesheet/PRODUCT.md && node -e 'const fs=require("node:fs"); const files=[".agents/PROJECT_PLAN.md",".agents/skills/orchestrate-labtimesheet-iteration/SKILL.md","PRODUCT.md"]; const forms=["work/fix//","work//fix/"]; for (const file of files) { const text=fs.readFileSync(file,"utf8"); for (const form of forms) { if (text.split(form).length !== 2) throw new Error(file+": expected one "+form); } } console.log("Root coordination authority: "+files.length+" approved branch rules match exactly");' +git diff --check 8be1b754e188367b260981718a5d33fc2d4d8a3b 445e4fedeb0e06724b876c5731437d2c355cacb2 +``` + +The SRS regeneration and count assertion ran from the main root because the +ignored requirements hub is local authority there. The root-authority +comparisons, link assertion, and exact base-to-candidate `git diff --check` +ran from this fix worktree; the SRS generator also rejects a broken local SRS +target before it writes the generated file. + +```text +Wrote labtimesheet-docs-hub/software-requirements-specification.md +Requirements: 260; use cases: 14; screens: 48; mockup embeds: 48 +authoritative: 260 rows, 260 unique IDs +explained: 260 rows, 260 unique IDs +simple: 260 rows, 260 unique IDs +generated SRS: 260 rows, 260 unique IDs +generated SRS: 14 use cases +Fix-branch workflow documentation: 6 approved statements validated +Targeted-repair workflow element removals: 36/36 rejected +Positive nested branch recommendations: 6/6 rejected +Root coordination authority: 3 approved branch rules match exactly +Local Markdown links: 7 resolved +git diff --check 8be1b754e188367b260981718a5d33fc2d4d8a3b 445e4fedeb0e06724b876c5731437d2c355cacb2: exit 0 +``` + +## External-test boundaries + +This documentation contract does not create or manipulate Git branches, start +the application, or replace branch-owner review. It validates the durable rule +and SRS traceability only; a taskmaster still authorizes branch creation, +integration, and any push. diff --git a/scripts/verify-fix-branch-workflow.cjs b/scripts/verify-fix-branch-workflow.cjs new file mode 100644 index 0000000..2a20cb5 --- /dev/null +++ b/scripts/verify-fix-branch-workflow.cjs @@ -0,0 +1,108 @@ +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); + +const repositoryRoot = path.resolve(__dirname, '..'); +const validForm = '`work/fix//`'; +const invalidForm = '`work//fix/`'; +const requiredWorkflow = 'Every targeted repair starts from the taskmaster-verified latest `main`, uses TDD RED → GREEN, adds Javadoc during implementation, records companion evidence, undergoes independent review, and uses a normal, non-force merge only when separately authorized.'; +const workflowElements = [ + 'taskmaster-verified latest `main`', + 'TDD RED → GREEN', + 'Javadoc during implementation', + 'companion evidence', + 'independent review', + 'normal, non-force merge' +]; +const documents = [ + { + file: 'AGENTS.md', + approved: '- 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.' + }, + { + file: 'README.md', + approved: 'For a targeted repair, create a clean isolated branch and worktree from the\ntaskmaster-verified current `main` named\n`work/fix//`. Do not nest it as\n`work//fix/`: the persistent `work/` ref already\nuses that Git ref prefix.' + }, + { + file: 'DEVELOPMENT.md', + approved: 'For a targeted repair, start a clean worktree from the taskmaster-verified\ncurrent `main` on `work/fix//`. Keep it separate from the\nfive persistent `work/` branches. Do not use\n`work//fix/` because the persistent `work/` ref\nalready occupies that Git ref prefix.' + }, + { + file: 'TESTING.md', + approved: 'Run that check from the clean targeted-fix branch named\n`work/fix//` when repairing one feature. Do not use\n`work//fix/`: a persistent `work/` ref already\noccupies that Git ref prefix. Record the expected RED and the matching GREEN\nshell output in the evidence record.' + }, + { + file: 'docs/superpowers/specs/2026-08-15-access-navigation-icon-intern-picker-design.md', + approved: 'Use `work/fix//` for each targeted repair. Create its clean,\nisolated worktree from the taskmaster-verified current `main`. The ``\nsegment identifies the owning persistent area; it does not nest below that\npersistent branch.\n\nThe forbidden form is `work//fix/`. A repair owner preserves\nother worktrees, records RED and GREEN evidence, commits locally, and does not\npush or merge without separate authority.' + }, + { + file: 'docs/superpowers/plans/2026-08-15-access-navigation-icon-intern-picker.md', + approved: '2. Add one branch rule to contributor guides, design records, plans, and tracked\n coordination authority: `work/fix//` from verified\n `main`.\n3. State why `work//fix/` is invalid while its persistent\n `work/` ref exists.' + } +]; + +/** Validates that every tracked guide contains only its approved branch wording. */ +function validate(contents) { + const failures = []; + + for (const {file, approved} of documents) { + const content = contents.get(file); + if (count(content, validForm) !== 1) failures.push(`${file} must contain ${validForm} exactly once`); + if (!content.includes(approved)) failures.push(`${file} is missing its approved branch workflow statement`); + if (count(content, requiredWorkflow) !== 1) { + failures.push(`${file} must contain the complete required targeted-repair workflow exactly once`); + } + + const outsideApprovedStatement = content.replace(approved, ''); + if (outsideApprovedStatement.includes(validForm) || outsideApprovedStatement.includes(invalidForm)) { + failures.push(`${file} contains an unapproved branch-form reference`); + } + } + + if (failures.length) throw new Error(failures.join('\n')); +} + +function count(content, value) { + return content.split(value).length - 1; +} + +function readContents() { + return new Map(documents.map(({file}) => [file, fs.readFileSync(path.join(repositoryRoot, file), 'utf8')])); +} + +const contents = readContents(); +validate(contents); + +let workflowElementRejections = 0; + +if (process.argv.includes('--self-test')) { + for (const {file} of documents) { + for (const workflowElement of workflowElements) { + const missingWorkflowElement = new Map(contents); + missingWorkflowElement.set( + file, + contents.get(file).replace(requiredWorkflow, requiredWorkflow.replace(workflowElement, '')) + ); + assert.throws( + () => validate(missingWorkflowElement), + (error) => error instanceof Error + && error.message.includes(`${file} must contain the complete required targeted-repair workflow exactly once`) + ); + workflowElementRejections += 1; + } + + const positiveRecommendation = new Map(contents); + positiveRecommendation.set(file, `${contents.get(file)}\nUse ${invalidForm} for a targeted repair.\n`); + assert.throws( + () => validate(positiveRecommendation), + (error) => error instanceof Error + && error.message.includes(`${file} contains an unapproved branch-form reference`) + ); + } +} + +console.log(`Fix-branch workflow documentation: ${documents.length} approved statements validated`); +if (process.argv.includes('--self-test')) { + console.log(`Targeted-repair workflow element removals: ${workflowElementRejections}/${workflowElements.length * documents.length} rejected`); + console.log(`Positive nested branch recommendations: ${documents.length}/${documents.length} rejected`); +}