acstack 0.0.0-stage → 0.47.0

package/skills/new-worktree/herdr.md

@@ -0,0 +1,84 @@
+# New worktree: herdr
+
+The `Orchestrator: herdr` branch of `SKILL.md`, for when `active` is `herdr`.
+
+When `active` is `herdr`, the session is running in a [herdr](https://herdr.dev) pane. Create the worktree through herdr, then move this pane into the workspace herdr made for it. The session ends up in the sidebar row for the worktree it is actually working in, indented under its parent repo.
+
+All four steps are one operation. Stopping after step 2 is the old broken behaviour. The session keeps running in the parent repo's workspace, and the worktree row holds nothing but an idle shell.
+
+Check herdr's own markers before issuing any of the commands below. The detector reports `herdr` when either marker holds a value, but these steps need both: if `$HERDR_WORKSPACE_ID` or `$HERDR_PANE_ID` is empty, herdr's markers are incomplete. Say so and stop there, rather than issuing herdr commands against a blank target – `herdr workspace get ""` does not fail usefully, it just acts on nothing.
+
+## 1. Keep the source workspace alive
+
+Moving the last pane out of a workspace closes that workspace. If this session is the only pane in a repo-root workspace, the repo row vanishes and the new worktree has no parent to nest under.
+
+Read the source workspace first:
+
+```bash
+herdr workspace get "$HERDR_WORKSPACE_ID"
+```
+
+If `pane_count` is 1 and `worktree.is_linked_worktree` is `false`, leave a shell behind before moving:
+
+```bash
+herdr tab create --workspace "$HERDR_WORKSPACE_ID" --cwd <main-root> --no-focus
+```
+
+Skip this when the workspace has other tabs, or when it is already a linked worktree. A spent worktree workspace should close when the session leaves it.
+
+## 2. Create the worktree
+
+`<base>` per the base rule in `SKILL.md`.
+
+```bash
+cd <main-root> \
+  && git fetch origin --quiet \
+  && herdr worktree create \
+       --cwd "$(pwd)" \
+       --branch <branch> \
+       --base <base> \
+       --label <slug> \
+       --no-focus
+```
+
+`--cwd` must be the MAIN repo root. herdr records it as the workspace's `repo_root`, and the sidebar groups worktree workspaces as indented children under that repo. Pass a nested worktree path and the new workspace groups under the wrong parent.
+
+Do not pass `--path`. herdr places the checkout under its configured root (`worktrees.directory`, default `~/.herdr/worktrees`, giving `<root>/<repo>/<branch-slug>`). Letting the config decide keeps worktrees agent-neutral – the same layout whether Claude, Codex, or another CLI agent works in them.
+
+Use `--no-focus` here, so herdr does not drop the user into the spare shell. Focus comes in step 3, with this pane.
+
+Read three values from the JSON rather than assuming any of them:
+
+- `.result.worktree.path` – the checkout, for `git -C <path> log -1 --oneline` to confirm the base commit
+- `.result.workspace.workspace_id` – where this pane is going
+- `.result.root_pane.pane_id` – the spare shell to close in step 4
+
+Never hardcode the path. A relative `worktrees.directory` resolves against the herdr session's base directory, not the repo you pass to `--cwd`. Only the output tells you where the checkout landed.
+
+## 3. Move this pane in
+
+```bash
+herdr pane move "$HERDR_PANE_ID" --new-tab --workspace <workspace-id> --focus
+```
+
+Use `--focus` so the user's view follows the session they were watching, instead of staying on whatever remains behind.
+
+The pane gets a new workspace-qualified ID. Read it from `.result.move_result.pane.pane_id`. `$HERDR_PANE_ID` still resolves for this process, so it keeps working as a target here. Do not hand the old ID to anything else.
+
+## 4. Close the spare shell
+
+herdr's create step always spawns a shell in the new workspace. Close it once the move has landed:
+
+```bash
+herdr pane close <root-pane-id>
+```
+
+Order matters. Close it first and the workspace has no panes left. herdr then closes the workspace, so the move in step 3 has nothing to target.
+
+## If the checkout already exists
+
+Attach it instead of recreating, then carry on from step 3:
+
+```bash
+herdr worktree open --path <path-to-existing-checkout>
+```

package/skills/new-worktree/orca.md

@@ -0,0 +1,101 @@
+# New worktree: Orca
+
+The `Orchestrator: orca` branch of `SKILL.md`, for when `active` is `orca`.
+
+When `active` is `orca`, the session runs in an Orca terminal. Create the worktree through Orca, then change this session's working directory into the checkout Orca reports.
+
+There is no pane move here. Orca has no command that moves a running terminal into another worktree, so step 3 is a plain cwd change. That is the one place this branch differs from herdr.
+
+Run every step below. Stopping after step 3 leaves an idle Orca shell in the checkout, and `teardown-worktree` then refuses to remove it.
+
+There is no marker check either. Orca injects `ORCA_PANE_KEY` and `ORCA_WORKTREE_ID` into the terminals it opens, and the detector already reads them. The commands below target the repo by path, so they need neither marker.
+
+Resolve Orca's executable before you call it. The Linux binary is `orca-ide`, and some installs put it on PATH as plain `orca`. Never hard-code either name:
+
+```bash
+ORCA_BIN="$(command -v orca-ide || command -v orca)"
+```
+
+Every Orca command takes `--json` and answers with one object: `{id, ok, result, error, _meta}`. Read `.ok` before you read anything else.
+
+## 1. Create the worktree
+
+`<base>` per the base rule in `SKILL.md`.
+
+```bash
+cd <main-root> \
+  && git fetch origin --quiet \
+  && "$ORCA_BIN" worktree create \
+       --repo path:"$(pwd)" \
+       --name <slug> \
+       --base-branch <base> \
+       --no-parent \
+       --json
+```
+
+`--repo` must name the MAIN repo root, the same rule herdr's `--cwd` follows. Pass `--no-parent` so Orca records the checkout as independent work. Without it, Orca makes the new worktree a child of whatever this terminal sits in.
+
+Read three values from the JSON rather than assuming any of them:
+
+- `.result.worktree.path` – the checkout, for `git -C <path> log -1 --oneline` to confirm the base commit
+- `.result.worktree.branch` – the branch Orca made, as a full ref such as `refs/heads/<github-user>/<name>`
+- `.result.worktree.baseRef` – the ref Orca branched from
+
+Never compute the path or the branch.
+
+Orca places the checkout under `~/orca/workspaces/<repo>/<name>`, and it names the branch `<github-user>/<name>`. So the `<type>/<slug>` branch rule in `SKILL.md` does not survive here. Pass the slug as `--name`, then report the branch Orca actually returned.
+
+Strip the `refs/heads/` prefix before you report that branch. `git branch --show-current` in the checkout prints the same short name, so the two agree.
+
+## 2. When Orca refuses
+
+`repo_not_found` in `.error` means Orca does not know this repo. Register it once, then retry the create:
+
+```bash
+"$ORCA_BIN" repo add --path <main-root> --json
+```
+
+On any other failure, show the user the exact command and Orca's `error`, then stop. Never fall through to plain git.
+
+Orca cannot see a checkout made behind its back, cannot track it, and cannot later remove it. That leaves the user holding a worktree their orchestrator will never account for.
+
+## 3. Move this session in
+
+Change cwd into the path Orca returned, the way `Orchestrator: none` does. `Then move into it` in `SKILL.md` covers it.
+
+Offer the fresh-session variant too. It opens a new Orca terminal in the checkout, running its own agent. Stop the spare shell first, or the new terminal joins it:
+
+```bash
+"$ORCA_BIN" terminal stop --worktree path:<path> --json
+"$ORCA_BIN" terminal create --worktree path:<path> --title <slug> --command "claude" --json
+```
+
+Take that route only when the user asks for it.
+
+This session then stays where it is. Otherwise two agents share one checkout. That ordering also settles step 4, so skip it.
+
+## 4. Stop the spare shell
+
+`orca worktree create` always spawns a shell terminal in the new checkout. Stop it once this session has moved in:
+
+```bash
+"$ORCA_BIN" terminal stop --worktree path:<path> --json
+```
+
+The result counts what it stopped, as `{"stopped": N}`. `terminal stop` stops every terminal Orca holds for that worktree, not the spare one alone. So run it before you open anything in the checkout that you want to keep.
+
+Leaving that shell running costs the user a worktree later. `teardown-worktree` refuses to remove a checkout whose `liveTerminalCount` is above zero. The idle shell alone holds that count at one. So the worktree never becomes a teardown candidate.
+
+## If the checkout already exists
+
+Attach to it instead of creating a second one:
+
+```bash
+"$ORCA_BIN" worktree list --repo path:<main-root> --json
+```
+
+Match `.result.worktrees[].branch`, which holds a full ref such as `refs/heads/<github-user>/roadmap-gantt`, or match `.displayName`. Then take that entry's `.path` and carry on from step 3.
+
+Match only a path under `~/orca/workspaces/`. Orca's listing also reports herdr and plain git checkouts when the user turns external visibility on, and those are not Orca's to hand out.
+
+`"$ORCA_BIN" worktree current --json` answers the other question: which Orca worktree holds the current directory.

package/skills/pre-commit-review/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: pre-commit-review
+description: "Deep code quality review of all changes since last commit. Checks for hardcodes, single-source-of-truth violations, scalability issues, edge cases, and project convention drift using dynamic project awareness (living specs, codebase search, surrounding code). Also flags adjacent code rot worth cleaning up. Auto-invocable in two contexts – (1) when working autonomously through a task list and about to commit (e.g., user said \"implement all tasks and commit\"), use --auto-fix mode; (2) when the user manually invokes /commit and this skill has not already run on the current changes, use INTERACTIVE mode (default). Manual invocation via /pre-commit-review also uses interactive mode by default."
+argument-hint: "[--auto-fix] [scope description]"
+---
+
+# Pre-commit review
+
+This skill runs a deep review of code quality in uncommitted changes, using dynamic
+project awareness. It finds issues that linters miss: hardcodes, duplicated logic, missing
+edge cases, convention drift, and adjacent rot.
+
+## User input
+
+```text
+$ARGUMENTS
+```
+
+## Mode detection
+
+Parse `$ARGUMENTS` and invocation context to determine mode:
+
+- **Auto-fix mode**: Use when ANY of these are true:
+    - Arguments contain `--auto-fix`, `fix everything`, `auto fix`, or `fix automatically`
+    - The LLM works autonomously. The user asked it to implement, commit, and push, or work
+    through a task list, or said "handle everything". The LLM itself decided to commit.
+
+      The user is likely not present, so don't block on questions.
+
+- **Interactive mode** (default): Use when ANY of these are true:
+    - No `--auto-fix` argument, and the user invoked the skill manually via `/pre-commit-review`
+    - The user typed `/commit`, which auto-invokes the skill. The user is clearly present,
+    so consult them in question-tool waves (AskUserQuestion on Claude Code).
+    - When in doubt, use interactive – it's always safe to ask.
+
+**Rule of thumb**: Who initiated the commit? User typed `/commit` -> interactive.
+LLM decided to commit during autonomous work -> auto-fix.
+
+## Workflow overview
+
+```
+1. SNAPSHOT  – collect the diff and understand what changed
+2. DISCOVER  – learn project conventions dynamically (parallel subagents)
+3. REVIEW    – analyze changes against conventions + best practices (parallel subagents)
+4. ADJACENT  – check surrounding code for related rot (parallel subagents)
+5. REPORT    – synthesize findings
+6. FIX       – auto-fix or interactive proposal waves
+```
+
+## Step 1: SNAPSHOT
+
+Collect the raw material:
+
+```bash
+# All changes (staged + unstaged + untracked) since last commit
+git diff HEAD
+git diff --cached
+git status --short
+git log --oneline -3  # recent context
+```
+
+Read `acstack/project.yaml` to understand the project's directory layout, commands, and conventions.
+
+Categorize changed files into scopes using the project configuration:
+
+- **source**: files under `directories.source` from project.yaml
+- **frontend**: files under `frontend.directory` from project.yaml (if configured)
+- **config**: `*.yaml`, `*.toml`, `*.json`, config files, etc.
+- **tests**: files under `directories.tests` from project.yaml
+- **other**: everything else
+
+If no meaningful code changes exist (only docs, config, assets), report "No code changes to review" and exit. Run the prose lint from Step 3 before you exit, when Markdown files changed.
+
+## Step 2: DISCOVER – Learn project conventions (parallel)
+
+Launch **3 parallel Explore subagents** to build a dynamic understanding of the project's current conventions.
+Do NOT hardcode conventions – discover them fresh each time.
+
+**Subagent A – Living Specs & Architecture:**
+
+```
+Read the living specs relevant to this change:
+- Check acstack/specs/ directory listing
+- Read spec.md files for domains touched by the changed files
+  (use acstack/domain-map.yaml to map files -> domains)
+- Extract documented conventions, patterns, and requirements (FR-NNN entries)
+Report: list of project conventions and patterns relevant to these changes.
+```
+
+**Subagent B – Codebase Patterns via Search:**
+
+```
+Search the codebase for established patterns related to the changes.
+For each changed function/component, search for similar implementations:
+  Search for function signatures, class names, and patterns from the diff
+  Find files with similar naming conventions
+Identify: how does the rest of the codebase handle similar things?
+Report: established patterns, common approaches, naming conventions observed.
+```
+
+**Subagent C – Local Context & Config:**
+
+```
+For each changed file, read:
+- The full file (to see surrounding code context)
+- Import targets (what does this file import? read those files' signatures)
+- Config that governs this area (linter rules, compiler config, etc.)
+Report: local conventions, related code patterns, existing abstractions nearby.
+```
+
+Synthesize the three reports into a **convention profile** – the set of expectations
+review subagents measure changes against.
+
+## Step 3: REVIEW – Analyze changes (parallel)
+
+Launch **3 parallel review subagents**, each examining a different quality dimension.
+Every subagent receives the diff AND the convention profile from Step 2.
+
+**Subagent 1 – Hardcodes & SSOT:**
+
+```
+Examine the diff for:
+- Hardcoded values: URLs, ports, credentials, API keys, magic numbers, string literals
+  that should be constants or config
+- Single Source of Truth violations: same logic/value defined in 2+ places,
+  copy-pasted code that should be a shared function, config scattered across files
+- Constants that belong in a central config but are inline
+- Duplicated type definitions or interfaces
+
+For each finding, report:
+  FILE:LINE | SEVERITY (MUST/SHOULD/CONSIDER) | WHAT | WHY | SUGGESTED FIX
+```
+
+**Subagent 2 – Scalability & Readability:**
+
+```
+Examine the diff for:
+- Functions > 40 lines or > 3 levels of nesting
+- God functions doing too many things
+- Unclear variable/function names
+- Missing or premature abstractions
+- Complex conditionals that could be simplified
+- Code that would be hard for a new developer to understand
+- Performance concerns (N+1 queries, unnecessary re-renders, blocking I/O)
+
+For each finding, report:
+  FILE:LINE | SEVERITY (MUST/SHOULD/CONSIDER) | WHAT | WHY | SUGGESTED FIX
+```
+
+**Subagent 3 – Edge Cases & Robustness:**
+
+```
+Examine the diff for:
+- Unhandled null/undefined/None cases
+- Empty array/object assumptions
+- Missing error handling on I/O, network calls, or DB queries
+- Race conditions in async code
+- Missing input validation at system boundaries
+- Unhappy paths not tested or handled
+- Type narrowing gaps (any casts, missing type hints on public APIs)
+
+For each finding, report:
+  FILE:LINE | SEVERITY (MUST/SHOULD/CONSIDER) | WHAT | WHY | SUGGESTED FIX
+```
+
+**Prose lint on changed Markdown:**
+
+```bash
+~/.claude/acstack/bin/acstack lint-prose <changed .md files>
+```
+
+Run the lint on the changed Markdown files, and on nothing else. Skip the command when no Markdown file changed, because it exits 1 with no paths.
+
+The lint exits 0 even when it reports findings. It groups findings by file with line numbers, then prints a summary per file. It skips `skills/writing/vocabulary.md` on purpose.
+
+Add each finding to the review as `SHOULD | PROSE`, at the `file:line` it names. The writing standard is a project convention, so it sits at the same severity as other convention drift.
+
+## Step 4: ADJACENT – Check surrounding code for rot
+
+For each file with findings from Step 3, launch an **Explore subagent** (up to 3 in parallel).
+Each subagent examines the rest of that file and its immediate imports for the same categories of issue.
+
+```
+File [path] has these issues in the changed code: [summary].
+Read the FULL file and its direct imports.
+Find any OTHER instances of the same categories of problem in this file
+or closely related files – even if they weren't part of this commit's changes.
+These are "while we're here" cleanup opportunities.
+
+Report as: ADJACENT | FILE:LINE | WHAT | WHY | SUGGESTED FIX
+```
+
+Only flag adjacent issues that are **closely related** to the current changes (same file,
+same module, or same pattern). Stay narrowly scoped.
+
+## Step 5: REPORT – Synthesize findings
+
+Merge all subagent findings. Deduplicate. Sort by:
+
+1. MUST FIX (correctness, security, will-break-in-prod)
+2. SHOULD FIX (convention violations, readability, maintainability)
+3. CONSIDER (style preferences, minor improvements, adjacent rot)
+
+For each finding, make sure it has:
+
+- `file:line` reference
+- Category tag (HARDCODE, SSOT, SCALABILITY, READABILITY, EDGE-CASE, PROSE, ADJACENT)
+- Severity (MUST / SHOULD / CONSIDER)
+- Clear 1-sentence description of the problem
+- Why it matters (1 sentence)
+- Suggested fix (concrete, actionable – code snippet or approach)
+
+If any finding needs deeper analysis to determine the right fix, launch a **planning subagent**:
+
+```
+This code has [problem]. The file is [path]. Here's the surrounding context: [context].
+Think through 2-3 possible fixes, evaluate trade-offs, and recommend the best approach.
+Consider: does a fix here require changes in other files? What's the minimal change?
+```
+
+## Step 6: FIX – Auto-fix or interactive waves
+
+- **Auto-fix mode**: read `auto-fix.md` and follow it.
+- **Interactive mode** (default): read `interactive.md` and follow it.
+
+## Severity guide
+
+| Severity | Meaning                                                | Examples                                                           |
+| -------- | ------------------------------------------------------ | ------------------------------------------------------------------ |
+| MUST     | Will cause bugs, security issues, or prod failures     | Hardcoded secrets, unhandled null on critical path, race condition |
+| SHOULD   | Violates conventions, hurts maintainability, tech debt | SSOT violations, unclear naming, missing error handling on I/O     |
+| CONSIDER | Improvement opportunity, not urgent                    | Adjacent rot, minor style, could-be-cleaner patterns               |
+
+## What this skill does not check
+
+- **Formatting/style** – linters and formatters handle this
+- **Type errors** – typecheckers handle this
+- **Test coverage** – task-checker handles this
+- **UI rendering** – frontend-verify handles this
+- **Security scanning** – dedicated security tools handle credentials in committed code
+
+Focus exclusively on the semantic/architectural issues that automated tools miss.

package/skills/pre-commit-review/auto-fix.md

@@ -0,0 +1,19 @@
+# Pre-commit review: auto-fix mode
+
+Step 6 of `SKILL.md` in auto-fix mode.
+
+For each finding (MUST first, then SHOULD, then CONSIDER):
+
+1. Launch a **task-executor subagent** with the finding + suggested fix
+2. Verify the fix doesn't break anything (run lint, typecheck, and test commands from project.yaml)
+3. If fix breaks something, revert and try alternate approach
+4. Move to next finding
+
+After all fixes, run full verification using commands from `acstack/project.yaml`:
+
+```bash
+# Run the project's configured test, lint, and typecheck commands
+# Read these from project.yaml – do not hardcode
+```
+
+Report a summary of the fixes.

package/skills/pre-commit-review/interactive.md

@@ -0,0 +1,35 @@
+# Pre-commit review: interactive mode
+
+Step 6 of `SKILL.md` in interactive mode, the default.
+
+Present findings in **waves of up to 4** using the question tool (AskUserQuestion on Claude Code). On a host without one, use a numbered list in chat. Group related findings together.
+
+Format each wave like:
+
+```
+I found these issues in your changes. For each, choose: FIX / SKIP / DISCUSS
+
+1. [MUST | HARDCODE] `path/to/file.py:42`
+   Hardcoded timeout value `30` – should use config constant.
+   Suggested fix: Move to config, reference from there.
+
+2. [SHOULD | SSOT] `path/to/api/client.ts:15`
+   Duplicated error handling pattern – same try/catch in 3 functions.
+   Suggested fix: Extract shared wrapper function.
+
+3. [CONSIDER | ADJACENT] `path/to/component.tsx:88`
+   Existing code (not your change) has a magic string – should use constant.
+   Suggested fix: Add constant, use in both places.
+
+4. [SHOULD | EDGE-CASE] `path/to/manager.py:120`
+   No null check on response before accessing `.status`.
+   Suggested fix: Add guard clause with appropriate error.
+
+Reply with numbers to fix (e.g., "1,2,4") or "all" or "skip all", and any notes on approach.
+```
+
+After user responds:
+
+- Fix selected items via task-executor subagents (parallelize independent fixes)
+- Present next wave if more findings remain
+- Continue until all findings addressed or user says "done" / "skip the rest"

package/skills/quick-fix/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: quick-fix
+description: "Structured workflow for fixing bugs, issues, and broken behavior. Enforces codebase exploration before touching code, root cause analysis, minimal change principle, and full verification. Use when (1) something is broken and needs fixing, (2) behavior is wrong and needs correcting, or (3) user reports a bug. Lighter than a full debug investigation but more disciplined than ad-hoc fixes. Not for new features – use the Implementation Discipline directly."
+argument-hint: "<description of what's broken>"
+---
+
+# Quick fix
+
+Structured fix workflow: understand -> locate -> root-cause -> fix -> verify.
+
+## Input
+
+```
+$ARGUMENTS
+```
+
+If `$ARGUMENTS` is empty, ask the user to describe what's broken.
+
+## Before you start
+
+Copy the seven step headings below into your todo list word for word. They go ahead of any task-specific items. A step you skip stays in the list, marked `skip: <reason>`.
+
+When Step 5 runs, copy its four numbered steps the same way.
+
+## Step 1: Understand the problem
+
+Before touching any code:
+
+1. Restate the problem in one sentence. What is the expected behavior vs actual behavior?
+2. Classify the problem type:
+    - **Crash/error**: Stack trace or error message available
+    - **Wrong behavior**: Code runs but produces incorrect results
+    - **Regression**: Something that used to work stopped working
+    - **Performance**: Too slow, too many resources
+
+If the user provided an error message or stack trace, note the key details (file, line, error type).
+
+## Step 2: Explore the codebase
+
+**Do NOT skip this step.** Delegate exploration to subagents:
+
+1. **Locate the code**: Launch an Explore subagent to find the files involved. Read only a file you can already name.
+
+2. **Read the integration points**: Have the subagent read the broken function's callers and callees, not just the function. Understand:
+    - What calls this code? (upstream)
+    - What does this code call? (downstream)
+    - What data flows through it? (inputs/outputs)
+    - Are there tests covering this behavior?
+
+3. **Check recent changes**: If this is a regression, run:
+   ```bash
+   git log --oneline -20 -- <file>
+   ```
+   to see if a recent commit introduced the problem.
+
+Produce a brief exploration summary:
+
+```
+Files involved: <list>
+Integration points: <upstream -> target -> downstream>
+Existing tests: <list or "none">
+Recent changes: <relevant commits or "none suspicious">
+```
+
+## Step 3: Root cause analysis
+
+Based on the exploration, identify the root cause – not just the symptom.
+
+Bad: "The function returns null" (symptom).
+Good: "The function returns null because the query filter uses `org_id`, but the test user's org isn't in the result set" (root cause).
+
+If the root cause isn't clear after exploration, escalate to deeper investigation with parallel debug subagents. Don't guess.
+
+## Step 4: Plan the fix
+
+Before coding, state:
+
+1. **What** will change (which file(s), which function(s))
+2. **Why** this fixes the root cause (not just the symptom)
+3. **What won't change** (confirm the fix is minimal – no drive-by refactors)
+
+If the fix touches more than 3 files, pause. Confirm the scope with the user – the fix may be bigger than a quick fix.
+
+## Step 5: Implement via the Implementation discipline
+
+Follow the standard pipeline:
+
+1. **test-writer** – Write a failing test that reproduces the problem (if testable behavior exists). Skip for pure config/infra fixes.
+2. **task-executor** – Implement the minimal fix to make the test pass. Executor CANNOT modify test files.
+3. **task-checker** – Verify: task tests pass, full suite passes, test count >= baseline, no regressions.
+4. **frontend-verify** – Only if the fix touches frontend files (check `frontend.directory` in project.yaml).
+
+## Step 6: Verify
+
+Run build verification using commands from `acstack/project.yaml`:
+
+```bash
+# Run the project's configured test, lint, and typecheck commands
+# Read these from project.yaml – do not hardcode
+```
+
+**STOP – if the fix touches frontend files, you MUST visually verify before proceeding to Step 7.**
+
+If the project has a frontend verification agent or browser verification configured, use them. Otherwise, take a browser screenshot and think through:
+
+1. **Expected vs actual** – What should the change look like? Does the screenshot match?
+2. **Gaps** – Is anything missing, wrong, or showing the wrong data/labels/formatting?
+3. **General UX** – Anything weird? Overlapping elements, bad spacing, truncation, unprofessional appearance?
+
+If verification finds a problem, fix it. Verify again. Do NOT proceed to Step 7 with unverified frontend changes.
+
+## Step 7: Report
+
+```
+=== Quick Fix Complete ===
+
+Problem: <one-line description>
+Root cause: <what was actually wrong>
+Fix: <what changed and why>
+Files modified: <list>
+Tests: <added/modified/passing>
+Regressions: none
+```
+
+Remind the user to `/commit` when they're satisfied.