agileflow 4.0.0-alpha.1 → 4.0.0-alpha.10

package/CHANGELOG.md

@@ -3,6 +3,85 @@
 All notable changes to `agileflow` v4 are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [4.0.0-alpha.3] — 2026-04-20
+
+Flow audit fixes for the alpha.2 wizard + install path. Wiring/persistence
+came back PASS; this patch closes the test gap and fixes the safety +
+feedback gaps the audit surfaced.
+
+### Fixed
+
+- **P0 test gap** (`tests/unit/config/writer.test.js`): the per-field
+  round-trip block tests every other config field but skipped
+  `behaviors`. A future PR that drops the `behaviors:` line from
+  `writer.js`'s payload would have shipped silently. Added explicit
+  mixed-shape round-trip test (not all-true, not all-false) so the
+  serializer-loader pair is contractually pinned.
+- **P1 damage-control silent fail-open**
+  (`damage-control-bash.js`/`-edit.js`/`-write.js`): when
+  `damage-control-patterns.yaml` is missing or unreadable, all three
+  hooks used to `process.exit(0)` silently — guards disabled, no
+  signal to the user. Now emit a stderr WARNING with the error code
+  and the path. Repeated warnings on every Bash/Edit/Write are
+  intentional: they signal "fix this or disable the preset". Hooks
+  still fail-open (the contract is "block dangerous things, don't
+  block legit work just because we can't read our own config").
+- **P1 missing behaviors visibility**:
+  - `setup --yes` console output now prints `behaviors enabled: ...`
+    after the plugin list, gated on `caps.hooks` so non-Claude-Code
+    IDEs don't see a noisy line. Listed-as-CSV in the order: any
+    `loadContext, babysitDefault, damageControl, preCompactState`
+    that are `true`.
+  - Interactive `prompts.outro` now includes `behaviors active: ...`
+    or `behaviors active: (none — no hooks will run; re-run setup to
+enable)`. A user who deselected all four behaviors no longer
+    finishes the wizard celebrating "X plugins enabled" while
+    actually getting zero hooks.
+  - `agileflow update` console output mirrors the same pattern.
+  - Install spinner message changed from `Installing N plugin(s)` to
+    `Installing N plugin(s) — writing hooks, skills, mirrors` so
+    first-time users have a clearer mental model of what `.agileflow/`
+    will contain.
+- **P2 fresh-project context-loader / pre-compact-state**: when
+  `docs/09-agents/status.json` is absent (brand new project), both
+  hooks used to silently omit the stories section. Now emit
+  `(no story tracker yet — docs/09-agents/status.json not found)` so
+  Claude knows the section was reached, not skipped due to error. Also
+  surfaces `(none in progress, none ready)` when status.json exists
+  but is empty.
+
+### Tests
+
+- 305 passing (+1 from alpha.2's 304).
+
+## [4.0.0-alpha.2] — 2026-04-20
+
+Curated behavior presets — first hooks ship, but never as a free-for-all.
+
+### Added
+
+- **Behavior presets in `agileflow.config.json`** (`behaviors: { loadContext, babysitDefault, damageControl, preCompactState }`). Each preset maps 1:N to hooks declared in plugin manifests via a new `behavior: <key>` field. Disabling a preset excludes its hooks from the generated `.agileflow/hook-manifest.yaml` — the script literally does not run.
+- **Wizard step**: `pickBehaviors()` (`src/cli/wizard/behaviors-picker.js`) — Clack multiselect with all four presets pre-checked. Only shown for IDEs that support hooks (claude-code today; cursor/windsurf/codex skip it).
+- **Six behavior-gated hooks in the `core` plugin**:
+  - `context-loader` (SessionStart, gated by `loadContext`) — lean v4 replacement for v3's 79KB welcome banner. Prints stories, dirty files, and recent commits.
+  - `babysit-mentor-injector` (SessionStart, gated by `babysitDefault`) — HARD mode mentor injection. Claude defaults to the `/agileflow:babysit` mentor pattern without explicit invocation.
+  - `damage-control-bash` / `-edit` / `-write` (PreToolUse, gated by `damageControl`, `skipOnError: false`) — pattern-driven safety net (`damage-control-patterns.yaml`). Blocks `rm -rf /`, `dd to /dev/sda`, fork bombs, writes to `.env`/`.ssh/`, and similar.
+  - `pre-compact-state` (PreCompact, gated by `preCompactState`) — dumps active stories, current command, and dirty git state so they survive Claude's compaction summary.
+- **Schema + loader + writer updates**: `behaviors` is now a first-class config section. `mergeConfig` deep-merges across one level so partial user overrides don't wipe defaults.
+- **Aggregator behavior gating**: `buildHookManifest(orderedPlugins, behaviors)` filters hooks where `behaviors[entry.behavior] === false`. Missing keys treated as enabled (preserves intent of partial configs).
+- **15 new tests** covering behaviors filtering in the aggregator, behaviors-picker pure helpers, and the install-time integration test that asserts the manifest reflects the toggle map. Total: **304 passing** (+15 from alpha.1).
+
+### Changed
+
+- `installPlugins(options)` accepts a `behaviors` option threaded through to `writeAggregatedManifest`.
+- `agileflow setup` now includes a behaviors step after personalization for hook-capable IDEs.
+- `agileflow update` re-reads `behaviors` from the saved config so manual edits to `agileflow.config.json` propagate without re-running the wizard.
+- `defaultConfig()` ships with all four behaviors enabled. Users opt **out** at the wizard, never opt in.
+
+### Why curated, not free configuration
+
+Per user feedback in alpha.1: "I don't want it to be super customizable. Users would be able to customize pretty much anything." Free hook configuration (declare any event + any matcher + any script) is technically possible via the `hooks:` map, but the wizard surface is restricted to four presets. This keeps the install path predictable and prevents the v3-era anti-pattern of every plugin author shipping their own SessionStart welcome banner.
+
 ## [4.0.0-alpha.1] — Unreleased
 
 v4 Phase 1 skeleton. Not yet publishable.
@@ -254,6 +333,7 @@ The path from "green test suite" to "user can `npm i agileflow@alpha`" closes he
 - **Verified `npm pack --dry-run`** from `apps/cli/`: ships 52 files (bin/, src/, content/, README.md, LICENSE, CHANGELOG.md) — 65 KB tarball, 210 KB unpacked. Tests + vitest config + node_modules excluded.
 
 **To ship `4.0.0-alpha.1` now**:
+
 ```bash
 cd apps/cli && npm version 4.0.0-alpha.1 --no-git-tag-version
 git commit -am "release(v4): 4.0.0-alpha.1"

package/content/plugins/accessibility/plugin.yaml

@@ -0,0 +1,14 @@
+id: accessibility
+name: Accessibility
+description: WCAG 2.2 compliance, screen reader support, keyboard navigation, and a11y testing.
+version: 1.0.0
+enabledByDefault: false
+cannotDisable: false
+depends: []
+provides:
+  skills:
+    - id: agileflow-accessibility
+      dir: skills/agileflow-accessibility
+  agents: []
+  hooks: []
+  templates: []

package/content/plugins/accessibility/skills/agileflow-accessibility/SKILL.md

@@ -0,0 +1,392 @@
+---
+name: agileflow-accessibility
+version: 1.0.0
+category: agileflow/accessibility
+description: |
+  Use when implementing accessible UI, auditing for WCAG 2.2 compliance,
+  fixing screen reader issues, improving keyboard navigation, or preparing
+  for an accessibility review. Covers semantic HTML, ARIA patterns,
+  color contrast, focus management, and automated + manual testing.
+triggers:
+  keywords:
+    - accessibility
+    - a11y
+    - screen reader
+    - WCAG
+    - aria
+    - keyboard navigation
+    - focus
+    - color contrast
+    - tab order
+    - semantic html
+    - alt text
+    - accessible
+    - ADA
+    - Section 508
+    - voiceover
+    - NVDA
+    - skip link
+  priority: 50
+  exclude:
+    - accessible parking
+    - accessible tourism
+provides:
+  agents: []
+learns:
+  enabled: true
+  file: _learnings/accessibility.yaml
+  maxEntries: 50
+depends:
+  skills: []
+  plugins: [core]
+---
+
+# AgileFlow Accessibility
+
+Helps you build, audit, and fix accessible user interfaces — from semantic HTML foundations through ARIA patterns, focus management, screen reader compatibility, and automated testing integration.
+
+## When this skill activates
+
+- User wants to audit a page, component, or flow for WCAG 2.2 compliance
+- User is implementing a new UI component and wants it to be accessible from the start
+- User is fixing screen reader issues, keyboard trap bugs, or missing focus indicators
+- User needs to add axe-core tests, eslint-plugin-jsx-a11y, or Lighthouse accessibility CI
+- User is preparing for an ADA/Section 508 compliance review or legal audit
+- User mentions VoiceOver, NVDA, JAWS, TalkBack, or any assistive technology
+
+## Opening discovery flow
+
+**When invoked without clear context, ask one focused question to understand the task.**
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[
+  {
+    "question": "What accessibility work do you need to do?",
+    "header": "Accessibility task",
+    "multiSelect": false,
+    "options": [
+      {"label": "Audit an existing page or component for WCAG 2.2 issues (Recommended)", "description": "I'll run through automated scanning + manual keyboard + screen reader checks and give you a prioritised fix list"},
+      {"label": "Build a new UI component accessibly from scratch", "description": "Choose the right HTML element, add ARIA only where needed, wire up keyboard behaviour, write axe-core tests"},
+      {"label": "Fix a specific accessibility bug", "description": "Describe the issue — focus trap, missing label, colour contrast failure — and I'll diagnose and patch it"},
+      {"label": "Set up automated a11y testing in CI", "description": "Integrate axe-core, eslint-plugin-jsx-a11y, Pa11y, or Lighthouse into your test pipeline"},
+      {"label": "Prepare for an ADA / Section 508 compliance review", "description": "Systematic WCAG 2.2 AA checklist, VPAT preparation, audit report structure"}
+    ]
+  }
+]</parameter>
+</invoke>
+```
+
+**Route based on answer:**
+
+| Task                          | Next action                                                             |
+| ----------------------------- | ----------------------------------------------------------------------- |
+| Audit existing page/component | Follow `workflows/audit-page.md`                                        |
+| Build new component           | Follow `workflows/implement-accessible-component.md`                    |
+| Fix specific bug              | Diagnose with `references/aria-patterns.md`, apply fix, verify with axe |
+| Set up CI testing             | See Testing Checklist in `references/testing-checklist.md`              |
+| Compliance review             | Walk WCAG 2.2 AA checklist in `references/wcag-guide.md`                |
+
+## The POUR principles
+
+WCAG 2.2 organises all success criteria under four principles. Every accessibility decision maps to one of these.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  PERCEIVABLE    Content must be presentable to users in ways    │
+│                 they can perceive — text alternatives, captions, │
+│                 sufficient contrast, adaptable layout.          │
+├─────────────────────────────────────────────────────────────────┤
+│  OPERABLE       UI components and navigation must be operable   │
+│                 — keyboard accessible, no seizure triggers,     │
+│                 enough time, findable content.                  │
+├─────────────────────────────────────────────────────────────────┤
+│  UNDERSTANDABLE Information and UI operation must be            │
+│                 understandable — readable, predictable,         │
+│                 input assistance, error prevention.             │
+├─────────────────────────────────────────────────────────────────┤
+│  ROBUST         Content must be robust enough for current and   │
+│                 future assistive technologies — valid markup,   │
+│                 name/role/value, status messages.               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Conformance levels:**
+
+- **Level A** — Minimum. Critical barriers that prevent access entirely.
+- **Level AA** — Industry standard. Required for ADA, Section 508, EN 301 549. Target for all products.
+- **Level AAA** — Enhanced. Not required for full-site conformance; implement where feasible.
+
+## Who benefits and how
+
+Accessibility is not a niche concern. It benefits the majority of users.
+
+| Disability category               | Affected population                         | Assistive technology                              | WCAG principle      |
+| --------------------------------- | ------------------------------------------- | ------------------------------------------------- | ------------------- |
+| Visual (blind)                    | ~39M globally blind                         | Screen readers (JAWS, NVDA, VoiceOver)            | Perceivable, Robust |
+| Visual (low vision)               | ~246M globally                              | Screen magnifiers, large text, high contrast      | Perceivable         |
+| Visual (colour blind)             | ~300M globally (~8% men)                    | Colour contrast, pattern alternatives             | Perceivable         |
+| Motor (limited dexterity)         | ~2M wheelchair users in US                  | Keyboard navigation, switch access, voice control | Operable            |
+| Motor (tremor, repetitive strain) | Tens of millions                            | Larger touch targets, reduced motion              | Operable            |
+| Cognitive / learning              | ~15–20% of population                       | Plain language, consistent layout, error recovery | Understandable      |
+| Deaf / hard of hearing            | ~430M globally                              | Captions, transcripts, visual alerts              | Perceivable         |
+| Vestibular / seizure              | ~3M epilepsy in US                          | Reduced motion, no flashing content               | Operable            |
+| Temporary (broken arm, surgery)   | Situational, affects everyone at some point | All of the above                                  | All                 |
+
+**The business case:**
+
+- **1 billion+ people** worldwide have some form of disability (WHO).
+- In the US, people with disabilities control **~$490B in discretionary spending**.
+- ADA Title III digital lawsuits have exceeded **4,000 per year** in recent years; most settle for $25K–$100K+.
+- Inaccessible sites face procurement exclusion from government and enterprise buyers (Section 508 requirements).
+- Screen reader users abandon inaccessible sites at very high rates — directly lost revenue.
+- Accessibility improvements also benefit SEO (semantic HTML, alt text, structured content).
+
+## Semantic HTML as the foundation
+
+The single most impactful accessibility change you can make is using the correct HTML element.
+
+```html
+<!-- Bad: div soup — no semantics, no keyboard access, screen reader silent -->
+<div class="btn" onclick="submit()">Submit</div>
+<div class="nav">
+  <div onclick="goto('home')">Home</div>
+</div>
+
+<!-- Good: native semantics — keyboard accessible, screen reader announces role -->
+<button type="submit">Submit</button>
+<nav aria-label="Main navigation">
+  <a href="/">Home</a>
+</nav>
+```
+
+**Why native HTML wins:**
+
+- Built-in keyboard support (Enter/Space for buttons, arrows for radio groups, etc.)
+- Built-in ARIA role, name, and state (no extra attributes needed)
+- Works across all browsers and assistive technologies without additional scripting
+- Fewer bugs — browsers have tested these for decades
+
+**HTML element quick reference:**
+
+| Use case         | Correct element                                      | Common mistake                    |
+| ---------------- | ---------------------------------------------------- | --------------------------------- |
+| Clickable action | `<button>`                                           | `<div onclick>`, `<span onclick>` |
+| Navigation link  | `<a href>`                                           | `<div onclick>`                   |
+| Page sections    | `<main>`, `<nav>`, `<header>`, `<footer>`, `<aside>` | `<div id="main">`                 |
+| Content sections | `<section>`, `<article>`                             | nested `<div>`                    |
+| Headings         | `<h1>`–`<h6>` in logical order                       | `<div class="heading">`           |
+| Form inputs      | `<input>`, `<select>`, `<textarea>` with `<label>`   | Unlabelled inputs                 |
+| Data tables      | `<table>` with `<th scope>`, `<caption>`             | CSS grid faking a table           |
+| Lists            | `<ul>/<ol>` + `<li>`                                 | `<div>` with bullet CSS           |
+| Collapsible      | `<details>/<summary>`                                | Custom accordion with no ARIA     |
+
+## ARIA: last resort, not first choice
+
+ARIA (Accessible Rich Internet Applications) supplements HTML — it does not replace it.
+
+**Use ARIA only when:**
+
+1. No native HTML element exists for the pattern (custom combobox, tree view, data grid)
+2. Dynamic content updates need announcement (loading spinners, live search results)
+3. Relationships cannot be expressed in HTML (cross-section labelling, ownership)
+
+**The five ARIA rules (W3C):**
+
+1. **Use native HTML first.** `<button>` is always better than `<div role="button">`.
+2. **Don't override native semantics.** Don't put `role="heading"` on a `<p>`.
+3. **All interactive ARIA widgets must support keyboard.** If you add a role, add keyboard handlers.
+4. **Don't hide focusable elements.** `aria-hidden="true"` must not be on or contain focusable elements.
+5. **Interactive elements need an accessible name.** Button, input, link — must have a label.
+
+## Focus management
+
+Focus management is one of the most commonly broken accessibility requirements in SPAs and dynamic UIs.
+
+**Rules:**
+
+- Focus must always be visible — never `outline: none` without a custom focus style
+- Focus order must follow reading order (DOM order, not CSS visual order)
+- Modal dialogs must trap focus inside while open; release on close
+- On modal close, focus returns to the element that triggered it
+- Route changes in SPAs: move focus to the page `<h1>` or `<main>` landmark
+- Dynamically added content: announce via `aria-live` or move focus if triggered by user action
+
+```css
+/* Acceptable: custom focus style instead of removing outline */
+:focus-visible {
+  outline: 2px solid #005fcc;
+  outline-offset: 2px;
+}
+
+/* Unacceptable: removing focus indicator entirely */
+* {
+  outline: none;
+} /* Never do this */
+```
+
+## Colour and contrast
+
+**WCAG 2.2 AA thresholds:**
+
+| Content type                       | Minimum ratio  | Notes                                 |
+| ---------------------------------- | -------------- | ------------------------------------- |
+| Normal text (< 18pt / < 14pt bold) | 4.5:1          | Most body text                        |
+| Large text (≥ 18pt or ≥ 14pt bold) | 3:1            | Headlines, display text               |
+| UI components (borders, icons)     | 3:1            | Against adjacent colour               |
+| Focus indicators                   | 3:1            | Against adjacent colour (2.4.11)      |
+| Disabled controls                  | No requirement | But should be clearly distinguishable |
+| Decorative images                  | No requirement | Alt="" to mark as decorative          |
+
+**Tools:**
+
+- Browser DevTools — Elements panel shows contrast ratio in colour picker
+- [Colour Contrast Analyser](https://www.tpgi.com/color-contrast-checker/) (free desktop app)
+- [Who Can Use](https://www.whocanuse.com/) — shows how many people are affected at each ratio
+- `axe-core` — catches AA failures automatically
+
+**Common trap:** Placeholder text in inputs often fails contrast because browsers render it at ~40% opacity. Always check placeholder contrast separately from label contrast.
+
+## Automated testing integration
+
+Automated tools catch approximately 30–40% of WCAG issues. They are necessary but not sufficient.
+
+**Recommended stack:**
+
+```bash
+# Install axe-core for Vitest/Jest
+npm install --save-dev @axe-core/react axe-core vitest-axe
+
+# eslint-plugin-jsx-a11y for lint-time checks
+npm install --save-dev eslint-plugin-jsx-a11y
+
+# Pa11y for CLI/CI scanning
+npm install --save-dev pa11y
+
+# Lighthouse CI for automated score tracking
+npm install --save-dev @lhci/cli
+```
+
+**axe-core test example (Vitest + React Testing Library):**
+
+```js
+import { render } from "@testing-library/react";
+import { axe, toHaveNoViolations } from "vitest-axe";
+import { expect } from "vitest";
+import { LoginForm } from "./LoginForm";
+
+expect.extend(toHaveNoViolations);
+
+it("LoginForm has no axe violations", async () => {
+  const { container } = render(<LoginForm />);
+  const results = await axe(container);
+  expect(results).toHaveNoViolations();
+});
+```
+
+**eslint config (eslint.config.js flat config):**
+
+```js
+import jsxA11y from "eslint-plugin-jsx-a11y";
+
+export default [
+  jsxA11y.flatConfigs.recommended,
+  {
+    rules: {
+      "jsx-a11y/no-autofocus": "warn",
+      "jsx-a11y/anchor-is-valid": "error",
+    },
+  },
+];
+```
+
+## Screen reader testing matrix
+
+| Screen reader | Browser | Platform   | Priority                      |
+| ------------- | ------- | ---------- | ----------------------------- |
+| VoiceOver     | Safari  | macOS, iOS | High — Apple devices dominant |
+| NVDA (free)   | Firefox | Windows    | High — most common Windows SR |
+| JAWS          | Chrome  | Windows    | High — enterprise standard    |
+| TalkBack      | Chrome  | Android    | Medium — mobile               |
+| Narrator      | Edge    | Windows    | Low — rarely primary          |
+
+**Quick VoiceOver commands (macOS):**
+
+- Turn on/off: `Cmd + F5`
+- Navigate by headings: `VO + Cmd + H`
+- Navigate by form controls: `VO + Cmd + J`
+- Read from cursor: `VO + A`
+- Navigate landmarks: `VO + U` (rotor)
+
+**Quick NVDA commands (Windows):**
+
+- Turn on: `Ctrl + Alt + N`
+- Navigate by headings: `H`
+- Navigate by landmarks: `D`
+- Navigate by form fields: `F`
+- List all headings: `Insert + F7`
+
+## Quality checklist
+
+Before delivering any accessible component or audit fix:
+
+- [ ] All interactive elements reachable and operable via keyboard alone
+- [ ] Focus indicator visible on every interactive element (`outline: none` removed or replaced)
+- [ ] Focus order follows logical reading order
+- [ ] All images have appropriate alt text (descriptive or `alt=""` for decorative)
+- [ ] All form inputs have a programmatically associated label
+- [ ] Error messages identify the field and suggest correction (not just red border)
+- [ ] Colour contrast meets 4.5:1 for body text, 3:1 for large text and UI components
+- [ ] Information is not conveyed by colour alone
+- [ ] Dynamic content changes announced via `aria-live` or focus management
+- [ ] Modal dialogs trap focus, return focus on close, respond to Escape
+- [ ] Page has a `<title>` and a logical heading hierarchy starting with `<h1>`
+- [ ] `<html lang>` is set correctly
+- [ ] Skip navigation link present and functional
+- [ ] axe-core reports zero violations in automated tests
+- [ ] Tested with at least one screen reader (VoiceOver or NVDA)
+- [ ] Tested with keyboard only (no mouse)
+- [ ] Tested at 200% zoom without horizontal scrolling
+
+## Self-improving learnings
+
+`_learnings/accessibility.yaml` records:
+
+- Component library in use (Radix UI, Headless UI, MUI, custom) and its a11y baseline
+- Screen reader(s) the team tests with
+- axe-core rules the team has intentionally disabled and why
+- Known contrast waivers (branding colours that can't be changed)
+- Whether the project has a Lighthouse CI threshold configured
+- Patterns the team has already implemented (skip links, focus traps, live regions)
+
+Apply on invocation; update on correction.
+
+## References
+
+Load these files when you need deeper context:
+
+| File                              | When to load                                                                  |
+| --------------------------------- | ----------------------------------------------------------------------------- |
+| `references/wcag-guide.md`        | Full WCAG 2.2 success criterion breakdown with implementation examples        |
+| `references/aria-patterns.md`     | Common ARIA patterns: modals, accordions, live regions, navigation menus      |
+| `references/testing-checklist.md` | Automated + manual testing procedures, tool setup, common issues by component |
+
+## Workflows
+
+Follow these step-by-step when the user initiates the matching action:
+
+| File                                          | When to follow                                                             |
+| --------------------------------------------- | -------------------------------------------------------------------------- |
+| `workflows/audit-page.md`                     | User wants to audit an existing page or component for accessibility issues |
+| `workflows/implement-accessible-component.md` | User is building a new UI component and wants it accessible from the start |
+
+## Integration
+
+- **agileflow-test-writer** — add axe-core and keyboard navigation tests alongside unit tests for every new component; accessibility fixes need regression coverage
+- **agileflow-story-writer** — include WCAG-level accessibility acceptance criteria in user stories before implementation begins, not as an afterthought
+- **agileflow-engineering** — delegate the implementation of accessibility fixes (ARIA attributes, focus management, semantic HTML corrections) to engineering
+- **agileflow-audit** — the accessibility dimension of a full audit feeds into this skill for WCAG-specific remediation and severity prioritisation
+- **agileflow-pr-reviewer** — invoke accessibility checks as part of PR review for any story touching UI components or interactive elements; it's a merge gate, not optional
+- **agileflow-delivery** — accessibility review is required before shipping user-facing features; delivery should block on unresolved P0/P1 WCAG violations
+- **agileflow-seo** — semantic HTML, alt text quality, and heading hierarchy improvements benefit both accessibility and search ranking simultaneously
+- **agileflow-research** — use when implementing complex patterns (data tables, multi-step forms, modals with focus traps) to verify correct ARIA patterns before coding