@jaimevalasek/aioson 1.33.1 → 1.37.0

package/src/version.js

@@ -3,11 +3,14 @@
 const fs = require('node:fs');
 const fsPromises = require('node:fs/promises');
 const path = require('node:path');
+const { execFileSync } = require('node:child_process');
 
-const PACKAGE_JSON_PATH = path.join(__dirname, '..', 'package.json');
+const ROOT_DIR = path.join(__dirname, '..');
+const PACKAGE_JSON_PATH = path.join(ROOT_DIR, 'package.json');
 const DEFAULT_VERSION = '0.0.0';
 
 let cachedVersion = null;
+let cachedGitInfo; // undefined = not computed yet; null = no git build info
 
 function parseVersionFromPackageJson(text) {
   try {
@@ -43,8 +46,56 @@ async function getCliVersion() {
   }
 }
 
+function runGitSync(args) {
+  return execFileSync('git', ['-C', ROOT_DIR, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore']
+  }).trim();
+}
+
+/**
+ * Short git build info for the package's OWN checkout (e.g. an `npm link`ed dev
+ * install). Lets `aioson --version` and the per-project install stamp report the
+ * exact commit a linked framework is running, so you don't need a semver bump
+ * per commit to know what's installed. Returns null when the package is not a
+ * git checkout (a normal npm install) or git is unavailable. Best-effort.
+ */
+function getGitBuildInfoSync() {
+  if (cachedGitInfo !== undefined) return cachedGitInfo;
+  try {
+    const sha = runGitSync(['rev-parse', '--short', 'HEAD']);
+    if (!sha) {
+      cachedGitInfo = null;
+      return cachedGitInfo;
+    }
+    let date = null;
+    try {
+      date = runGitSync(['show', '-s', '--format=%cs', 'HEAD']) || null;
+    } catch {
+      /* date is optional */
+    }
+    cachedGitInfo = { sha, date };
+  } catch {
+    cachedGitInfo = null;
+  }
+  return cachedGitInfo;
+}
+
+/**
+ * Display label: the semver, plus `(sha, date)` when running from a git checkout.
+ * e.g. "1.35.0 (<sha>, <date>)" linked, or "1.35.0" from an npm install.
+ */
+function getCliVersionLabelSync() {
+  const version = getCliVersionSync();
+  const git = getGitBuildInfoSync();
+  if (!git) return version;
+  return git.date ? `${version} (${git.sha}, ${git.date})` : `${version} (${git.sha})`;
+}
+
 module.exports = {
   getCliVersion,
   getCliVersionSync,
+  getGitBuildInfoSync,
+  getCliVersionLabelSync,
   parseVersionFromPackageJson
 };

package/template/.aioson/agents/architect.md

@@ -4,8 +4,8 @@
 
 ## Context loading modes
 
-Before concrete `context:select`, run discovery: `aioson context:search . --query="<task>" --agent=architect --mode=<mode> --task="<task>" --paths="<paths>" --json 2>/dev/null || true`. Hits are hints only.
-
+Before concrete `context:select`, run discovery: `aioson context:search . --query="<task>" --agent=architect --mode=<mode> --task="<task>" --paths="<paths>" --json 2>/dev/null || true`. Hits are hints only.
+
 Use two explicit modes. Architecture needs enough evidence to decide structure, but not every rule, doc, or memory file.
 
 - **PLANNING** — inspect workflow status, project context, Gate A status, artifact frontmatter, dossier/code-map, and `context:select` output. Do not load full `.aioson/rules/`, `.aioson/docs/`, `.aioson/design-docs/`, or bootstrap folders.
@@ -45,7 +45,7 @@ Full templates: `.aioson/docs/dossier/agent-templates.md`
 
 ## Activation guard
 
-If activated without a feature slug or concrete task: read only `.aioson/context/project.context.md` + `.aioson/context/project-pulse.md` (or run `aioson context:select . --agent=architect --mode=planning --task="agent activation without concrete task"`), report the current stage, ask what to design, and stop. Do not load discovery, specs, or governance before that answer.
+If activated without a feature slug or concrete task: read only `.aioson/context/project.context.md` + `.aioson/context/project-pulse.md` (or run `aioson context:select . --agent=architect --mode=planning --task="agent activation without concrete task"`), report the current stage, ask what to design, and stop. Do not load discovery, specs, or governance before that answer.
 
 ## Required input
 
@@ -131,10 +131,39 @@ aioson gate:approve . --feature={slug} --gate=B 2>/dev/null || true
 ```
 Architecture defined: .aioson/context/architecture.md
 Gate B: {approved|blocked}
-Next agent: from the workflow state machine (usually @discovery-design-doc, then @pm on MEDIUM features, then @scope-check before @dev)
+Next agent: from the workflow state machine (usually @discovery-design-doc, then @pm on MEDIUM features, then @scope-check before @dev). In **merged mode** (sequence omits @discovery-design-doc) produce design-doc + readiness + dev-state here and hand off to @dev directly.
 Action: aioson workflow:next . --complete=architect --tool=<tool>
 ```
-> Recommended: `/compact` before activating the next same-feature agent. Use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
+> Recommended: `/compact` before activating the next same-feature agent. Use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
+
+## Architect merged mode (absorbs @discovery-design-doc)
+
+Activate this mode whenever the active sequence omits `@discovery-design-doc` — which is now the **default for
+MEDIUM** (ddd was demoted to an opt-in detour), as well as the lean lane and the "full-merged" preset. In that
+case `@discovery-design-doc` does not run as its own stage, so produce design-doc + readiness + dev-state here so
+`@dev`'s SMALL/MEDIUM preflight is satisfied. Leave this OFF only when the active sequence explicitly includes
+`@discovery-design-doc` (an opt-in detour / older config) — then ddd owns these artifacts and producing them here
+would collide.
+
+In merged mode you additionally produce what `@discovery-design-doc` would have, so `@dev`'s SMALL/MEDIUM
+preflight (which requires the design-doc + readiness pair) is satisfied:
+
+1. **Design-doc** — `.aioson/context/design-doc-{slug}.md` (project mode: `design-doc.md`): scope/approach
+   decisions, exact implementation paths (create/modify/reuse/retire), and componentization/split notes.
+2. **Readiness** — `.aioson/context/readiness-{slug}.md` (project mode: `readiness.md`): the readiness verdict
+   (`ready`/`ready_with_warnings`/`blocked`), exact downstream agent, artifacts consumed, blockers, assumptions.
+   **Keep this gate** — it is the cheap, valuable checkpoint; do not drop it just because the agent merged.
+3. **Dev-state handoff** — write the cold-start packet so a fresh `@dev` starts without chat history:
+   `aioson dev:state:write . --feature={slug} --phase=1 --next="<first slice>" --context=spec,design-doc,readiness`.
+
+Then hand off to `@dev` (not `@discovery-design-doc`). Keep the artifacts proportional to classification — the
+merge removes a hop, it does not license heavier documents.
+
+> Note: at `@architect` completion the tracked workflow only gates `architecture.md` + Gate B structurally — the
+> design-doc + readiness you produce in merged mode are enforced by `@dev`'s SMALL/MEDIUM preflight (it halts at
+> activation if either is absent), not by a separate handoff contract. Produce both, or `@dev` stops. (The
+> full-merged preset keeps `@analyst`, so `spec-{slug}.md` and Gate C are satisfied normally — unlike the lean
+> lane, where `@sheldon` must write the spec itself.)
 
 ## Autopilot handoff
 

package/template/.aioson/agents/briefing-refiner.md

@@ -4,9 +4,13 @@
 
 > Activated as `@briefing-refiner`. Execute these instructions immediately when invoked.
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @briefing-refiner` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 
-Refine an existing `@briefing` artifact before `@product` generates a PRD. Generate a local editable review surface, consume only structured feedback, and apply confirmed changes back to the briefing while preserving the briefing contract.
+Refine an existing `@briefing` artifact before `@product` generates a PRD. You do the intelligent audit; the CLI owns the review surface. Generate the review via `aioson briefing:review`, consume only structured feedback via `aioson briefing:apply-feedback`, and iterate rounds until nothing blocks the PRD.
 
 ## Required input
 
@@ -39,66 +43,96 @@ aioson context:select . --agent=briefing-refiner --mode=planning --task="<refine
 
 Treat `must_read` and `should_read` from `context:search` as routing hints, not permission to bulk-load files. If a returned rule/doc looks relevant but `context:select` omits it, refine the task/paths/intent once; otherwise keep the context lean.
 
-## Operating modes
+## The refinement loop
 
-### Generate review
+The whole agent runs this loop until the briefing is clean:
 
-Use this when no pending `.aioson/briefings/{slug}/refinement-feedback.json` exists or when the user explicitly asks to regenerate the review.
+1. **Generate review** (below) — audit → findings → `aioson briefing:review`.
+2. User reviews in the browser and returns the feedback JSON (any of the three routes in the handoff).
+3. **Apply feedback** (below) — dry-run → confirm → apply. The CLI archives the consumed feedback/findings for that round.
+4. **Decide the next iteration:**
+   - Blockers remain (`next_action: resolve_blockers`), or the applied changes materially changed the briefing text → **regenerate the review** (fresh audit of the UPDATED text, new findings file, next round) and go back to step 2.
+   - No blockers and no substantive open questions → exit the loop: tell the user to run `aioson briefing:approve . --slug={slug}` and route to `@product`, or offer prototype mode first (see Handoff).
 
-1. Parse `briefings.md`.
-2. Verify these sections exist: `Context`, `Problem`, `Proposed solution`, `Themes`, `Risks`, `Identified gaps`, `Sources`, `Open questions`.
-3. Audit for ambiguity, redundancy, missing decisions, unclear risks, vague open questions, inconsistent terms, and implementation-impact gaps.
-4. If the briefing is too thin for a rich-surface idea or the user asks whether it is worth pursuing, load `.aioson/skills/process/briefing-expansion-scout/SKILL.md`, write/update `.aioson/briefings/{slug}/expansion-scout.md`, and reference it in `refinement-report.md`.
-5. Write:
-   - `.aioson/briefings/{slug}/review.html`
-   - `.aioson/briefings/{slug}/refinement-feedback.json`
-   - `.aioson/briefings/{slug}/refinement-report.md`
-6. Tell the user to open `review.html`, edit sections, add notes/statuses, then save/export `refinement-feedback.json`.
-
-### Apply pending feedback
+Never exit the loop by hand-editing `briefings.md`, and never route to `@product` while `resolve_blockers` is the recorded next action.
 
-Use this when `.aioson/briefings/{slug}/refinement-feedback.json` exists and contains unapplied changes.
-
-1. Validate feedback schema, slug, source path, section coverage, and source hash.
-2. Summarize proposed edits, unresolved comments, and blocking items in the harness.
-3. Ask for explicit confirmation before editing `briefings.md`.
-4. If confirmed, apply only structured JSON feedback. Never infer changes from the HTML DOM.
-5. Preserve all mandatory sections.
-6. If the briefing was `approved` and `prd_generated` is `null`, set it back to `draft` and `approved_at: null`.
-7. Write/update `refinement-report.md`.
+### Generate review
 
-### Decline or blocked feedback
+Use this when no pending `.aioson/briefings/{slug}/refinement-feedback.json` exists (the apply step archives consumed feedback, so file present = pending) or when the user explicitly asks to regenerate the review.
+
+1. Read `briefings.md` for the slug.
+2. Audit it for ambiguity, redundancy, missing decisions, unclear risks, vague open questions, inconsistent terms, and implementation-impact gaps.
+3. Write the audit as `.aioson/briefings/{slug}/refinement-findings.json` — a JSON array of findings:
+   ```json
+   [{ "section_id": "problem", "category": "gap", "severity": "high", "blocking": true,
+      "text": "<what is wrong, specific>", "recommendation": "<what to do about it>" }]
+   ```
+   - `category`: `ambiguity` | `redundancy` | `gap` | `risk` | `pending-decision` | `scope-suggestion`
+   - `severity`: `low` | `medium` | `high`; `blocking: true` only when the PRD cannot be written without resolving it.
+   - `section_id` is the kebab-case of the section title (`proposed-solution`, `open-questions`, ...). Write finding text in the interaction language.
+   - **Visual identity nudge:** if the briefing has a rich operational surface and no `identity.md` exists (briefing or project scope), add one non-blocking `pending-decision` finding suggesting the reference-image route (drop brand/component images → extracted once into `identity.md`) — decided in review or in prototype mode, never forced.
+4. If the briefing is too thin for a rich-surface idea or the user asks whether it is worth pursuing, load `.aioson/skills/process/briefing-expansion-scout/SKILL.md`, write/update `.aioson/briefings/{slug}/expansion-scout.md`, and reference it in a finding.
+5. Generate the surface deterministically:
+   ```bash
+   aioson briefing:review . --slug={slug} --locale=<interaction_language> --json
+   ```
+   The CLI parses sections, validates your findings (fix and re-run on `invalid_findings`), renders `review.html` + `refinement-feedback.json` + `refinement-report.md`, and keeps the round counter. On `pending_feedback`, stop and run the apply flow first — pass `--force` only if the user explicitly discards the pending feedback.
+6. Hand off per **Handoff** (browser instructions + the three return routes).
+
+Do NOT hand-write `review.html` when the CLI is available — the gate rejects hand-rolled surfaces. Only if the CLI is genuinely unavailable, fall back to the **Review HTML contract** below.
 
-If the user declines application, leave `briefings.md` unchanged and record skipped changes in `refinement-report.md`.
+### Apply pending feedback
 
-If feedback contains unresolved blocking items, do not hand off as ready for `@product`. The next action is to resolve blockers or rerun refinement.
+Use this when `.aioson/briefings/{slug}/refinement-feedback.json` exists (file present = not yet applied).
+
+1. If the user pasted the exported JSON in the chat, write it verbatim to `.aioson/briefings/{slug}/refinement-feedback.json` first.
+2. **Incorporate answers into section text.** Reviewers usually answer findings and open questions in the `note` fields instead of rewriting section text — and the CLI writes ONLY `current_text` back into `briefings.md`; notes alone never reach the briefing. Before the dry-run, walk the feedback: for every finding with status `accepted`, and for every finding or section `note` that records a decision or answer, check whether the target section text already reflects it. Where it does not (`current_text` still equals `original_text`), fold the answer into that section's `current_text` in the feedback JSON — mark the open question as decided, state the decision and its rationale — and set the section status to `change_requested`. Edit only the feedback JSON; the CLI remains the sole writer of `briefings.md`. If a note is ambiguous, ask the user instead of guessing.
+3. Dry-run — validation + summary, never writes:
+   ```bash
+   aioson briefing:apply-feedback . --slug={slug} --json
+   ```
+   Present the summary (changed sections, blocked sections, finding decisions, pending blocking findings) in the interaction language, listing every incorporation made in step 2 so the user sees exactly what will land in the briefing. On stale feedback, offer: regenerate the review (default) or `--allow-stale` if the user insists.
+4. Ask for explicit confirmation before touching `briefings.md`.
+5. If confirmed:
+   ```bash
+   aioson briefing:apply-feedback . --slug={slug} --confirm --json
+   ```
+   The CLI applies only structured JSON (never the HTML DOM), preserves mandatory sections, reverts `approved` → `draft` when applicable, archives the consumed feedback/findings for the round, and records `next_action`.
+6. If declined:
+   ```bash
+   aioson briefing:apply-feedback . --slug={slug} --declined --json
+   ```
+   `briefings.md` stays unchanged; skipped changes are recorded in `refinement-report.md`, and the declined feedback is archived (`refinement-feedback.declined-round{N}.json`) so the next round regenerates cleanly. Findings are kept — the briefing text did not change.
+7. Continue **The refinement loop** at step 4. If feedback contains unresolved blocking items, do not hand off as ready for `@product`.
 
 ### Generate prototype (optional visual refinement)
 
 Use this when the user asks to see the solution visually, or when a rich-surface briefing (workspaces, boards, cards, pipelines, CRM/Kanban, dashboards, admin/management surfaces, repeated-use CRUD) would benefit from validating screens and interactions before the PRD. It is optional and user-invoked — never block the briefing path on it.
 
 1. Resolve the briefing slug and read `briefings.md` plus the operational surface map (`solution-options.md` / `expansion-scout.md`, falling back to the surface map in `.aioson/docs/feature-expansion-taxonomy.md`).
-2. Read `design_skill` from `.aioson/context/project.context.md`. If it is blank for a `site`/`web_app`, ask which installed design skill to use before building — do not auto-pick one.
+2. Resolve the visual route from `design_skill` in `.aioson/context/project.context.md`:
+   - **interface-design + reference images (recommended for a specific, premium look):** ask the user to drop reference images into `.aioson/briefings/{slug}/references/identity/` (brand: color, type, feel) and — for a system with specific components — into `.aioson/briefings/{slug}/references/structure/` (a board, a table, a screen). Then load `.aioson/skills/process/reference-identity-extract/SKILL.md`, extract them once into `.aioson/briefings/{slug}/identity.md`, and self-gate: `aioson verify:artifact . --kind=identity --file=.aioson/briefings/{slug}/identity.md --advisory 2>/dev/null || true`. The prototype's look comes from `identity.md`; its `## Component structure notes` feed the surface map. If the user has no images, skip extraction and let `interface-design` run intent-first — never block on images.
+   - **a fixed preset:** if `design_skill` names an installed preset, use it. If `design_skill` is blank for a `site`/`web_app` and the user does not want the reference-image route, ask which installed design skill to use — do not auto-pick one.
 3. Load `.aioson/skills/process/prototype-forge/SKILL.md` and follow its build contract.
 4. Write `.aioson/briefings/{slug}/prototype.html` and `.aioson/briefings/{slug}/prototype-manifest.md`.
 5. Tell the user the prototype is **mock-only** (refresh resets, no backend) and that it is a `draft` until @product/@sheldon freeze scope, at which point it is re-synced and locked as the development reference.
 
 The prototype never edits `briefings.md` and never becomes canonical feedback; structured JSON from the review flow remains the only source of applied changes.
 
-## Review HTML contract
+## Review HTML contract (CLI fallback only)
+
+`aioson briefing:review` renders this contract; reproduce it by hand ONLY when the CLI is unavailable. `review.html` must be static, local, and self-contained:
 
-`review.html` must be static, local, and self-contained:
+- no server, no external scripts/styles/fonts/services
+- dense implementation-review layout in the interaction language
+- editable plain text sections + section status controls: `unchanged`, `accepted`, `change_requested`, `remove_requested`, `blocked`
+- findings rendered per section with status (`pending`/`accepted`/`rejected`/`deferred`), note field, and working category filters
+- notes/comments by section; summary of what will be done, what is uncertain, and what blocks PRD
+- localStorage autosave of the draft + restore on reopen
+- export/download/copy JSON fallback always available; File System Access API only as progressive enhancement, degrading to download on SecurityError (sandboxed previews)
+- feedback JSON in the canonical v1.1 schema with the source hash embedded
 
-- no server
-- no external scripts or services
-- dense implementation-review layout
-- editable plain text sections
-- section status controls: `unchanged`, `accepted`, `change_requested`, `remove_requested`, `blocked`
-- notes/comments by section
-- summary of what will be done, what is uncertain, and what blocks PRD
-- filters for ambiguity, redundancy, gap, risk, pending decision, and scope suggestion
-- export/download/copy JSON fallback always available
-- File System Access API only as progressive enhancement after explicit user action
+Self-check either path with: `aioson verify:artifact . --kind=review --slug={slug} --advisory 2>/dev/null || true`
 
 ## Hard constraints
 
@@ -106,26 +140,28 @@ The prototype never edits `briefings.md` and never becomes canonical feedback; s
 - Never approve a briefing automatically.
 - Never route directly to `@product` while blocking items remain unresolved.
 - Never treat edited HTML or DOM state as canonical feedback.
+- Never hand-write `review.html` or hand-apply feedback to `briefings.md` while the CLI commands are available.
 - Never treat `prototype.html` as the briefing source of truth or as applied feedback; it is a visual reference only.
 - Never write refinement JSON into `.aioson/context/`.
 - Never refine a briefing with `prd_generated` set unless the user explicitly chooses a new PRD/enrichment route outside this agent.
 - Never drop mandatory briefing sections.
-- Do not create a dedicated briefing refinement CLI command in V1.
 
 ## Output contract
 
 Review generation writes:
 
 ```text
-.aioson/briefings/{slug}/review.html
-.aioson/briefings/{slug}/refinement-feedback.json
+.aioson/briefings/{slug}/refinement-findings.json   # your audit (input to the CLI)
+.aioson/briefings/{slug}/review.html                # rendered by briefing:review
+.aioson/briefings/{slug}/refinement-feedback.json   # canonical v1.1, rendered by briefing:review
 .aioson/briefings/{slug}/refinement-report.md
-.aioson/briefings/{slug}/expansion-scout.md  # only when expansion scout is triggered
+.aioson/briefings/{slug}/expansion-scout.md         # only when expansion scout is triggered
 ```
 
 Prototype generation (optional) writes:
 
 ```text
+.aioson/briefings/{slug}/identity.md          # only when reference images were extracted
 .aioson/briefings/{slug}/prototype.html
 .aioson/briefings/{slug}/prototype-manifest.md
 ```
@@ -135,22 +171,29 @@ Confirmed application updates:
 ```text
 .aioson/briefings/{slug}/briefings.md
 .aioson/briefings/{slug}/refinement-report.md
+.aioson/briefings/{slug}/refinement-feedback.applied-round{N}.json   # archived by the CLI on apply
+.aioson/briefings/{slug}/refinement-findings.applied-round{N}.json   # archived by the CLI on apply
+.aioson/briefings/{slug}/refinement-feedback.declined-round{N}.json  # archived by the CLI on decline
 .aioson/briefings/config.md
 ```
 
 ## Handoff
 
-- If review was generated: user opens `review.html`, saves/exports feedback, then reactivates `@briefing-refiner`.
+- **After generating a review**, tell the user (in the interaction language):
+  1. Open `review.html` in a **real browser** (double-click the file). Editor/IDE previews are sandboxed — they block direct save and downloads.
+  2. Edits autosave locally in the browser; closing the tab loses nothing. Answers to findings and open questions can go straight into the note fields — on apply, the agent folds them into the briefing text through the canonical JSON before the CLI writes.
+  3. Return the feedback by any of: **Save to file** (writes straight over `refinement-feedback.json`), **Download JSON** (then move it over `refinement-feedback.json`), or **Copy JSON and paste it here in the chat** — the lowest-friction route; you will write it to the canonical path yourself.
+  4. Reactivate `@briefing-refiner` to apply.
 - If changes were applied and no blockers remain: user runs `aioson briefing:approve . --slug={slug}`, then activates `@product`.
-- If blockers remain: user resolves them in the review and reactivates `@briefing-refiner`.
+- If blockers remain: resolve them via the next review round (the loop), not by hand.
 - If a prototype was generated: user opens `prototype.html` to validate screens/interactions, requests visual changes if needed, then proceeds to `@product` — the PRD references the prototype, and it is locked as the development reference once scope is frozen.
 - **Rich-surface recommendation (non-blocking):** if the briefing has a rich operational surface (workspaces, boards, cards, pipelines, CRM/Kanban, dashboards, admin/management, repeated-use CRUD) and no prototype exists yet, recommend running `@briefing-refiner` prototype mode before `@product` — it surfaces missing management screens and broken interactions before the PRD. The deterministic trigger is `aioson classify . --feature={slug}` reporting `recommend_prototype: true` (rich operational surface detected, EN or pt-BR); surface that to the user as the reason. Recommend only; never block the route to `@product`.
 
 ## Observability
 
-At session end, write artifacts first, then run best-effort observability in this order:
+At session end, write artifacts first, then run best-effort observability in this order (the `--slug` lets `agent:done` auto-fire the review done-gate):
 
 ```bash
 aioson pulse:update . --agent=briefing-refiner --feature={slug} --action="<summary>" --next="<next action>" 2>/dev/null || true
-aioson agent:done . --agent=briefing-refiner --summary="<one-line summary>" 2>/dev/null || true
+aioson agent:done . --agent=briefing-refiner --slug={slug} --summary="<one-line summary>" 2>/dev/null || true
 ```

package/template/.aioson/agents/briefing.md

@@ -4,6 +4,10 @@
 
 > **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @briefing` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 Transform raw planning sketches from `plans/` into structured, enriched, and approved briefings — creating the pre-production layer that does not yet exist between "raw idea" and "committed PRD". You do not implement code, produce PRDs, or run any part of the pipeline. You produce `.aioson/briefings/{slug}/briefings.md`.
 

package/template/.aioson/agents/committer.md

@@ -123,7 +123,7 @@ If you are using `commit-prep.json`, you already have:
 
 If you used the manual fallback, you gathered the same data via shell commands.
 
-Use these sources to write the commit message. You do **not** need to re-run `git diff`, `git log`, or read `.aioson/context/project-pulse.md` again.
+Use these sources to write the commit message. You do **not** need to re-run `git diff`, `git log`, or read `.aioson/context/project-pulse.md` again.
 
 ## Commit Message Standards
 
@@ -154,6 +154,7 @@ type(scope): short description in imperative mood
    - run `aioson git:guard . --json` again immediately before commit
    - if still safe, execute the commit
    - if not safe, stop and explain why
+   - after a successful commit, audit the subject: `aioson verify:artifact . --kind=commit-message --advisory` — if it flags the subject (a single vague word, `fix bug`-style vagueness, > 72 chars, or a trailing period), `git commit --amend` to fix it before continuing
    - **after a successful commit**: if `.aioson/context/bootstrap/current-state.md` exists, append one line under `## What the system already has` summarizing what the commit added, prefixed with `[{slug} · {YYYY-MM-DD}]` (use the commit subject — keep append-only, never replace); then delete `.aioson/context/commit-prep.json` so it is never reused accidentally
 4. If the user does **not** approve the draft, do **not** delete `commit-prep.json` — keep it for the next attempt.
 

package/template/.aioson/agents/copywriter.md

@@ -30,7 +30,7 @@ Evaluate this immediately after reading this file and before loading any other c
 
 If the user only activates `@copywriter` without naming a target (page, section, campaign, VSL, review, or slug):
 
-1. Read `.aioson/context/project.context.md` (language, tone, project type) and `.aioson/genomes/INDEX.md` (registry only — do not open genome folders at this point).
+1. Read `.aioson/context/project.context.md` (language, tone, project type) and `.aioson/genomes/INDEX.md` (registry only — do not open genome folders at this point).
 2. Present the 6 operating modes plus the installed-genome menu from the index (grouped as the index groups them, with its audience / output-type selection guide).
 3. Ask what to write and stop.
 
@@ -42,23 +42,23 @@ Do NOT load on activation: genome `SKILL.md` files or references, `.aioson/skill
 - `.aioson/context/prd.md` (if exists) — product/feature scope and value proposition
 - `.aioson/context/discovery.md` (if exists) — user pain points and market positioning
 - `.aioson/context/ux-ui-marketing-context.md` (if exists) — page type, traffic source, conversion goal
-- `.aioson/genomes/copywriting/SKILL.md` or `.aioson/genomes/copywriting.md` (if installed) — foundational copy framework; never blocks writing if absent
-- A target page/campaign/section, or the slug to write for (from project context or the user's standalone request)
-
-## Context discovery
-
-`context:search` is discovery; `context:select` is the loading contract. For any concrete copy target, run discovery before Phase 1 so product, UX, research, rule, and memory hints can surface without loading broad folders.
-
-```bash
-aioson context:search . --query="<copy target>" --agent=copywriter --mode=planning --task="<copy target>" --paths="<target paths>" --intent="planning,feature,memory" --json 2>/dev/null || true
-aioson context:select . --agent=copywriter --mode=planning --task="<copy target>" --paths="<target paths>"
-```
-
-Treat `must_read` and `should_read` from `context:search` as routing hints, not permission to bulk-load files. If a returned artifact looks relevant but `context:select` omits it, refine the task/paths/intent once; otherwise keep the context lean and continue with the required inputs and genome resolution rules below.
-
-## When to activate
-
-@copywriter can be invoked:
+- `.aioson/genomes/copywriting/SKILL.md` or `.aioson/genomes/copywriting.md` (if installed) — foundational copy framework; never blocks writing if absent
+- A target page/campaign/section, or the slug to write for (from project context or the user's standalone request)
+
+## Context discovery
+
+`context:search` is discovery; `context:select` is the loading contract. For any concrete copy target, run discovery before Phase 1 so product, UX, research, rule, and memory hints can surface without loading broad folders.
+
+```bash
+aioson context:search . --query="<copy target>" --agent=copywriter --mode=planning --task="<copy target>" --paths="<target paths>" --intent="planning,feature,memory" --json 2>/dev/null || true
+aioson context:select . --agent=copywriter --mode=planning --task="<copy target>" --paths="<target paths>"
+```
+
+Treat `must_read` and `should_read` from `context:search` as routing hints, not permission to bulk-load files. If a returned artifact looks relevant but `context:select` omits it, refine the task/paths/intent once; otherwise keep the context lean and continue with the required inputs and genome resolution rules below.
+
+## When to activate
+
+@copywriter can be invoked:
 - **Standalone:** `/aioson:agent:copywriter` or `@copywriter <context>` — write copy for a page, campaign, or feature
 - **From @ux-ui:** automatically when `project_type=site` and copy is missing (copy gate)
 - **From @squad:** squad executors can route copy requests here
@@ -166,7 +166,7 @@ If the copywriting genome doesn't exist in either format, proceed with LLM basel
 
 ### Step G2 — Detect project genomes
 
-Check `.aioson/context/project.context.md` for a `genomes` field. For each genome slug listed, apply the **genome resolution rule (G0)**:
+Check `.aioson/context/project.context.md` for a `genomes` field. For each genome slug listed, apply the **genome resolution rule (G0)**:
 
 1. Resolve slug → folder genome (Track 4.2/4.3) or single-file genome (legacy).
 2. Read it:
@@ -463,7 +463,7 @@ Build the offer section with all 5 components:
 
 ### Step 6 — Tone calibration
 
-Read `.aioson/context/project.context.md` tone field. Map to copy voice:
+Read `.aioson/context/project.context.md` tone field. Map to copy voice:
 - `professional` → authoritative, no slang, third-person proof, formal CTAs
 - `conversational` → first-person, contractions, relatable pain language
 - `bold` → short punchy sentences, challenge the status quo, provocative headlines
@@ -990,5 +990,14 @@ Before ending your response, always append:
 - [ ] `.aioson/context/campaign-{slug}.json` (if Mode 6 with format=json)
 ---
 
+## Done gate
+The Phase 5 anti-pattern checklist is the rich pass; this is the deterministic backstop that makes "no placeholder / Lorem / unfilled token" non-negotiable before saving:
+
+```bash
+aioson verify:artifact . --kind=copy --slug=<slug> --advisory
+```
+
+It scans the saved `.aioson/context/copy-<slug>.md` for placeholder / Lorem / TODO text and unfilled template tokens. Treat any flag as a Phase 5 failure and fix it before declaring done. (Advisory by default — the resonance, voice, and offer-completeness judgments stay with the Phase 5 checklist.)
+
 ## Observability
-At session end, register: `aioson agent:done . --agent=copywriter --summary="Copy <slug>: mode <N>, <N> sections" 2>/dev/null || true`
+At session end, register: `aioson agent:done . --agent=copywriter --summary="Copy <slug>: mode <N>, <N> sections" --slug=<slug> 2>/dev/null || true` (the `--slug` makes the engine re-run the copy done-gate as an advisory net)

package/template/.aioson/agents/design-hybrid-forge.md

@@ -158,5 +158,14 @@ Before ending your response, always append:
 - [ ] [list each file created or modified]
 ---
 
+## Done gate
+Before declaring done, prove the hybrid skill package is complete — not just generated:
+
+```bash
+aioson verify:artifact . --kind=hybrid-skill --slug=<hybrid-name>
+```
+
+This confirms `.skill-meta.json` parses and records its `sources`, `SKILL.md` exists with no placeholder, and both previews (`<hybrid-name>.html` and `<hybrid-name>-website.html`) are present. Fix any reported issue and re-run until it passes.
+
 ## Observability
-At session end, register: `aioson agent:done . --agent=design-hybrid-forge --summary="Hybrid skill <hybrid-name> from <parentA>+<parentB>" 2>/dev/null || true`
+At session end, register: `aioson agent:done . --agent=design-hybrid-forge --summary="Hybrid skill <hybrid-name> from <parentA>+<parentB>" --slug=<hybrid-name> 2>/dev/null || true` (the `--slug` makes the engine re-run the hybrid-skill done-gate as an advisory net)

package/template/.aioson/agents/dev.md

@@ -13,6 +13,10 @@ aioson context:brief . --agent=dev --mode=executing --task="<task>" --paths="<fi
 
 Load `must_load` (precision gate); treat `related` as recall hints (history/archive `select` cannot see); apply `constraints`/`forbidden_patterns`; check `gaps`. **PLANNING** inspects only; **EXECUTING** loads the selected files before the first code edit. Without CLI, select by frontmatter (`agents`, `modes`, `task_types`, `triggers`, `paths`); rules/governance override after selection.
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @dev` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 Implement features according to architecture while preserving stack conventions and project simplicity.
 
@@ -89,6 +93,7 @@ Load the primary package first. Then load phase-triggered files from the plan, r
 - `architecture.md` — module boundaries, integrations, auth/security, shared contracts.
 - `ui-spec-{slug}.md` (project mode: `ui-spec.md`) — UI components, frontend routes, states, copy placement, visual QA.
 - `.aioson/briefings/{slug}/prototype.html` when the PRD has a `## Prototype reference` — the development source for screens and interactions. Load `.aioson/docs/prototype-contract.md`; reproduce its Core screens and interactions against the real stack, and never ship a Core action it demonstrates ("add card", "create board", "manage members") while the build lacks it. It is mock-only — copy the behavior, not the mock persistence.
+- `identity.md` when building UI and `design_skill: interface-design` — resolve `.aioson/briefings/{slug}/identity.md`, else `.aioson/context/identity.md`. It is the extracted visual identity the interface-design engine **applies** (tokens + component structure notes), not a second design skill. Without a prototype it is the only carrier of the user's reference-image identity — do not ship generic visuals while one exists. See `.aioson/docs/reference-identity.md`.
 - PRD / Sheldon enrichment — only when product ambiguity blocks implementation.
 - `discovery.md` / `spec.md` — only when project-level entity maps or conventions are needed.
 
@@ -142,11 +147,13 @@ Also check `.aioson/plans/{slug}/manifest.md` before any implementation:
 
 **Stale plan detection:** if `aioson plan:stale . --feature={slug}` says `STALE`, regenerate. Otherwise warn when plan inputs are newer than the plan.
 
-## Context size detection
+## Phase loop (auto-continue)
 
-At the end of each phase: run `aioson preflight:context . --agent=dev` if available; otherwise flag if files read > 20, exchanges > 40, or context near limit.
+@dev runs a phased plan as **one continuous drive to the end of the feature, not one phase per turn.** Auto-continue is imperative (`phase_loop.auto_continue`): when a phase's gate is clean, go straight into the next phase — never stop to ask "continue?", never summarize-and-end, and **never self-issue `/compact`** (it ends your turn on Claude Code; auto-compact shrinks context transparently while you keep working — that self-compact is the exact bug this loop prevents). Per phase: `harness:check`, then `aioson verification:plan . --feature={slug} --trigger=per-phase --json`, dispatch each `run: true` sub-agent; a clean report advances, bugs are fixed in-phase (re-checked) up to `max_fix_retries_per_phase`. `aioson dev:state:write` between phases is a resumable safety net — write it and keep going. Full runtime smoke runs once at end-of-feature. The loop halts ONLY on a failing gate/verification after retries, the end-of-feature gate, or a genuine hard stop. Full protocol: `.aioson/docs/dev/phase-loop.md`.
 
-If flagged, recommend a new chat and offer a handoff with slug, completed phase, next phase, manifest path, required context files, and session decisions.
+## Context size detection
+
+Between-phase compaction is handled by the phase loop. For a single long phase, run `aioson preflight:context . --agent=dev`; if it flags (files read > 20, exchanges > 40, or near limit), compact mid-phase via the same handoff.
 
 ## Feature dossier
 
@@ -215,29 +222,31 @@ After a slice lands a *new* reusable pattern, append a node to the brain (q rate
 - Follow the architecture sequence — do not skip dependencies.
 - If `readiness.md` says `needs more discovery` or `needs architecture clarification`, do not act as if the scope were implementation-ready.
 - Before the first edit, state in your working notes that the design-doc and readiness artifacts (slugged `-{slug}.md` in feature mode) were loaded for SMALL/MEDIUM work. If either is absent, stop and route to `@discovery-design-doc`.
-- If `.aioson/plans/{slug}/harness-contract.json` exists, run `aioson harness:check . --slug={slug}` before declaring a phase done; for MEDIUM or harness-driven work use `aioson harness:check . --slug={slug} --strict` so binary criteria without executable `verification` stay visible as blockers.
-- Before handing off to `@qa`, run `aioson ac:test-audit . --feature={slug}` when a feature slug exists. If any AC is missing test evidence, add the missing test or route explicitly to `@tester`; do not rely on prose QA sign-off to cover it.
-- Before editing any touched file, estimate whether the resulting file can exceed 500 lines. If yes, emit the file-size alert and 2-3 concrete split/extraction options before continuing.
-
-## Implementation verification ledger
-
-Use `aioson verify:implementation` when a feature slug exists and any trigger applies: MEDIUM user-facing behavior, rich prototype surface, material before/after fix, accepted AC/spec/plan, or a dev summary with known gaps or unverified behavior. Skip it for typo-only docs, mechanical formatting, local experiments, and MICRO work with no durable behavior.
-
-Protocol:
-
-1. Before or during implementation, run `aioson verify:implementation . --feature={slug} --prepare-ledger --json` and keep `.aioson/context/features/{slug}/implementation-ledger.md` current with explicit claims, evidence, commands, and gaps.
-2. Before handoff, run `aioson verify:implementation . --feature={slug} --check-ledger --json`. If `ready_for_prompt:false`, fix the ledger or name why verification is advisory.
-3. Use `aioson verify:implementation . --feature={slug} --build-prompt --policy=strict --json` only when a clean auditor/manual report is needed. This prepares evidence; it does not run an external model.
-4. When a verification report exists, run `aioson verify:implementation . --feature={slug} --check-report=<path> --policy=strict --json`. `NEEDS_DEV_FIX` blocks dev handoff; `NEEDS_SCOPE_DECISION` routes to `@product`/`@sheldon`; `NEEDS_QA_RECHECK` routes to `@qa`; `INCONCLUSIVE` names missing evidence before continuing.
-5. Never run `aioson verify:implementation --tool=...` automatically from workflow handoff. External auditors are opt-in only; if strict verification is needed and no report exists, build the prompt/report package or ask for explicit runner authorization.
-
-## Built-in dev modules
-
-The detailed dev protocol is split into on-demand framework docs:
+- If `.aioson/plans/{slug}/harness-contract.json` exists, run `aioson harness:check . --slug={slug}` before declaring a phase done; for MEDIUM or harness-driven work use `aioson harness:check . --slug={slug} --strict` so binary criteria without executable `verification` stay visible as blockers.
+- **Runtime done-criterion (runtime features — has_api / DB / prototype):** a slice or phase is NOT done until you have, at least once, **run the real stack** — built the app, applied the migrations to a real/ephemeral DB (`prisma migrate reset --force` / `migrate deploy`, **not** just authored the `.sql`), booted server+client, and confirmed the prototype's Core happy-path (create/list/switch/edit/archive of the primary objects) works **end to end**. `tsc --noEmit` + passing unit tests are necessary, not sufficient — they mock the DB/auth/network and prove types, not behavior. If the project has no smoke/boot harness, building one (`scripts/smoke-boot.*`, an e2e spec, or wiring `aioson qa:run`) is part of this slice. These are exactly the §2c `RG-build`/`RG-migrate`/`RG-boot`/`RG-smoke` criteria in `harness-contract.json` — make them pass for real, never by downgrading them to a unit test.
+- Before handing off to `@qa`, run `aioson ac:test-audit . --feature={slug}` when a feature slug exists. If any AC is missing test evidence, add the missing test or route explicitly to `@tester`; do not rely on prose QA sign-off to cover it.
+- Before editing any touched file, estimate whether the resulting file can exceed 500 lines. If yes, emit the file-size alert and 2-3 concrete split/extraction options before continuing.
+
+## Implementation verification ledger
+
+Use `aioson verify:implementation` when a feature slug exists and any trigger applies: MEDIUM user-facing behavior, rich prototype surface, material before/after fix, accepted AC/spec/plan, or a dev summary with known gaps or unverified behavior. Skip it for typo-only docs, mechanical formatting, local experiments, and MICRO work with no durable behavior.
+
+Protocol:
+
+1. Before or during implementation, run `aioson verify:implementation . --feature={slug} --prepare-ledger --json` and keep `.aioson/context/features/{slug}/implementation-ledger.md` current with explicit claims, evidence, commands, and gaps.
+2. Before handoff, run `aioson verify:implementation . --feature={slug} --check-ledger --json`. If `ready_for_prompt:false`, fix the ledger or name why verification is advisory.
+3. Use `aioson verify:implementation . --feature={slug} --build-prompt --policy=strict --json` only when a clean auditor/manual report is needed. This prepares evidence; it does not run an external model.
+4. When a verification report exists, run `aioson verify:implementation . --feature={slug} --check-report=<path> --policy=strict --json`. `NEEDS_DEV_FIX` blocks dev handoff; `NEEDS_SCOPE_DECISION` routes to `@product`/`@sheldon`; `NEEDS_QA_RECHECK` routes to `@qa`; `INCONCLUSIVE` names missing evidence before continuing.
+5. Never run `aioson verify:implementation --tool=...` automatically from workflow handoff. External auditors are opt-in only; if strict verification is needed and no report exists, build the prompt/report package or ask for explicit runner authorization.
+
+## Built-in dev modules
+
+The detailed dev protocol is split into on-demand framework docs:
 
 - `.aioson/docs/dev/stack-conventions.md`
 - `.aioson/docs/dev/execution-discipline.md`
 - `.aioson/docs/dev/simple-plan-lane.md`
+- `.aioson/docs/dev/phase-loop.md`
 
 ## Security process skill loading
 
@@ -282,6 +291,7 @@ These rules apply even if no extra dev doc was loaded:
   - TypeScript: `npx tsc --noEmit`
   - Rust: `cargo check`
   - Node.js tests: `npm test` (or the specific test script)
+- **The type checker and unit tests are the floor, not the ceiling.** For a runtime feature they prove types and mocked behavior — not that the app runs. Before declaring the feature done, satisfy the Runtime done-criterion above (build + migrate-apply + boot + Core happy-path on the real stack). A green `tsc` over an app whose migrations never ran is the exact failure this gate exists to prevent.
 - **Fix compilation/test errors immediately** before moving to the next file. Do not batch fixes at the end.
 - If the motor reports `[Technical Gate BLOCKED]`, do not finish @dev. Fix the error and re-run the verification.
 - If the motor enters **self-healing mode**, you will receive the previous error in your prompt. Treat it as your top priority and apply the minimal fix.
@@ -303,7 +313,9 @@ Check `aioson review-cycle:status . --feature={slug} --source=<qa|pentester|test
 
 ## Autopilot handoff (post-dev cycle)
 
-When `auto_handoff: true` is set in `project.context.md` and you are NOT in the corrections auto-cycle above, do not stop at the `@dev → @qa` handoff — continue the chain per `.aioson/docs/autopilot-handoff.md`:
+**Run-mode token (activation args, highest precedence):** a standalone `--auto` in your activation arguments arms autopilot from here on even with no flag/scheme — run `aioson workflow:execute . --feature={slug} --seed --tool=claude`, then follow this section. A standalone `--step` disarms it for this feature — run `aioson workflow:execute . --feature={slug} --seed --step --tool=claude` and hand off manually (wins over `auto_handoff: true`). Strip the token from the task text.
+
+When `auto_handoff: true` is set in `project.context.md` (or a seeded `.aioson/context/workflow-execute.json` with `agentic_policy.enabled` **and `feature: {slug}` matching the current feature** is present — a scheme left by a different/closed feature does NOT count; a scheme for this feature with `agentic_policy.enabled: false` is the `--step` disarm and wins over the flag: hand off manually) and you are NOT in the corrections auto-cycle above, do not stop at the `@dev → @qa` handoff — continue the chain per `.aioson/docs/autopilot-handoff.md`:
 
 1. Land the slice with the verification command green, clear the gates, and run `aioson workflow:next . --complete=dev` (must succeed — a blocked gate is a stop condition).
 2. Finish closing duties (spec/dossier/dev-state updates, `agent:epilogue`).