@jaimevalasek/aioson 1.17.3 → 1.18.0

package/src/operator-memory/decision.js

@@ -81,7 +81,7 @@ function deriveTitle(proposal) {
 function serializeDecision(data) {
   const body = String(data.body || data.proposal || '').slice(0, MAX_BODY_CHARS);
   const title = deriveTitle(data.title || data.proposal);
-  return [
+  const lines = [
     '---',
     `slug: ${data.slug}`,
     `signal_type: ${data.signal_type}`,
@@ -93,8 +93,13 @@ function serializeDecision(data) {
     `source_agent: ${data.source_agent}`,
     `quotes:${quotesToYaml(data.quotes)}`,
     `version_schema: "${SCHEMA_VERSION}"`,
-    `deprecated_by: ${data.deprecated_by ?? 'null'}`,
-    '---',
+    `deprecated_by: ${data.deprecated_by ?? 'null'}`
+  ];
+  if (data.feature_slug) lines.push(`feature_slug: ${escapeYamlString(data.feature_slug)}`);
+  if (data.session_id) lines.push(`session_id: ${escapeYamlString(data.session_id)}`);
+  lines.push('---');
+  return [
+    ...lines,
     '',
     `# ${title}`,
     '',
@@ -178,7 +183,9 @@ function promoteProposal({ identity, proposal: proposalData }) {
     quotes: proposalData.quotes || [],
     body,
     title: proposalData.proposal,
-    deprecated_by: null
+    deprecated_by: null,
+    feature_slug: proposalData.feature_slug || null,
+    session_id: proposalData.session_id || null
   };
 
   const decFilePath = decisionPath(identity, decision.slug);

package/src/operator-memory/proposal.js

@@ -46,7 +46,7 @@ function quotesToYaml(quotes) {
 }
 
 function serializeProposal(data) {
-  return [
+  const lines = [
     '---',
     `slug: ${data.slug}`,
     `signal_type: ${data.signal_type}`,
@@ -56,10 +56,12 @@ function serializeProposal(data) {
     `quotes:${quotesToYaml(data.quotes)}`,
     `proposal: ${escapeYamlString(data.proposal)}`,
     `source_agent: ${data.source_agent}`,
-    `proposal_fingerprint: ${data.proposal_fingerprint}`,
-    '---',
-    ''
-  ].join('\n');
+    `proposal_fingerprint: ${data.proposal_fingerprint}`
+  ];
+  if (data.feature_slug) lines.push(`feature_slug: ${escapeYamlString(data.feature_slug)}`);
+  if (data.session_id) lines.push(`session_id: ${escapeYamlString(data.session_id)}`);
+  lines.push('---', '');
+  return lines.join('\n');
 }
 
 function parseProposalFrontmatter(content) {
@@ -130,7 +132,7 @@ function deleteProposal(identity, slug) {
   return false;
 }
 
-function captureSignal({ identity, slug, signal_type, quote, proposal, source_agent }) {
+function captureSignal({ identity, slug, signal_type, quote, proposal, source_agent, feature_slug, session_id }) {
   if (!VALID_SIGNAL_TYPES.includes(signal_type)) {
     throw new Error(`Invalid signal_type '${signal_type}'. Must be one of: ${VALID_SIGNAL_TYPES.join(', ')}`);
   }
@@ -160,7 +162,9 @@ function captureSignal({ identity, slug, signal_type, quote, proposal, source_ag
     quotes: quote ? [String(quote).trim()].filter(Boolean) : [],
     proposal,
     source_agent: source_agent || 'unknown',
-    proposal_fingerprint: fingerprintProposal(proposal)
+    proposal_fingerprint: fingerprintProposal(proposal),
+    feature_slug: feature_slug || null,
+    session_id: session_id || null
   };
   writeProposal(identity, fresh);
   return { proposal: fresh, isNew: true };

package/src/session-handoff.js

@@ -6,6 +6,8 @@ const { exists, ensureDir } = require('./utils');
 
 const HANDOFF_RELATIVE_PATH = '.aioson/context/last-handoff.json';
 const HANDOFF_PROTOCOL_RELATIVE_PATH = '.aioson/context/handoff-protocol.json';
+const CONFIRMATIONS_JSONL = '.aioson/runtime/session-confirmations.jsonl';
+const DECISION_RATIONALE_MAX = 5;
 
 // handoff-protocol.json schema_version for `artifact_uris`:
 // v1 (legacy) — array of strings; v2 — array of {path, kind, agent, added_at}.
@@ -63,10 +65,52 @@ function coerceArtifactUris(uris, fallbackAgent) {
     .filter(Boolean);
 }
 
+async function collectDecisionRationale(targetDir) {
+  const accPath = path.join(targetDir, CONFIRMATIONS_JSONL);
+  try {
+    const raw = await fs.readFile(accPath, 'utf8');
+    const lines = raw.trim().split('\n').filter(Boolean);
+    const entries = [];
+    for (const line of lines) {
+      try {
+        const obj = JSON.parse(line);
+        entries.push({
+          agent: obj.agent || 'unknown',
+          decision: obj.decision || '',
+          alternatives_considered: null,
+          rationale: obj.quote || null,
+          confidence: 'confirmed'
+        });
+      } catch {
+        // skip malformed lines
+      }
+    }
+    // BR-AO-04: FIFO — keep only the last N entries
+    return entries.slice(-DECISION_RATIONALE_MAX);
+  } catch {
+    return [];
+  }
+}
+
+async function clearConfirmationsAccumulator(targetDir) {
+  const accPath = path.join(targetDir, CONFIRMATIONS_JSONL);
+  try {
+    await fs.unlink(accPath);
+  } catch {
+    // file may not exist
+  }
+}
+
 async function writeHandoff(targetDir, payload) {
   const handoffPath = path.join(targetDir, HANDOFF_RELATIVE_PATH);
   const protocolPath = path.join(targetDir, HANDOFF_PROTOCOL_RELATIVE_PATH);
   await ensureDir(path.dirname(handoffPath));
+
+  // M2: collect decision rationale from session confirmations
+  const sessionRationale = await collectDecisionRationale(targetDir);
+  const existingRationale = Array.isArray(payload.decisionRationale) ? payload.decisionRationale : [];
+  const mergedRationale = [...existingRationale, ...sessionRationale].slice(-DECISION_RATIONALE_MAX);
+
   const handoff = {
     version: 1,
     session_ended_at: new Date().toISOString(),
@@ -79,10 +123,14 @@ async function writeHandoff(targetDir, payload) {
     context_files_updated: Array.isArray(payload.contextFilesUpdated) ? payload.contextFilesUpdated : [],
     workflow_mode: payload.workflowMode || null,
     classification: payload.classification || null,
-    feature_slug: payload.featureSlug || null
+    feature_slug: payload.featureSlug || null,
+    decision_rationale: mergedRationale.length > 0 ? mergedRationale : undefined
   };
   await fs.writeFile(handoffPath, `${JSON.stringify(handoff, null, 2)}\n`, 'utf8');
 
+  // Clear accumulator after writing to handoff
+  await clearConfirmationsAccumulator(targetDir);
+
   const protocol = payload.protocol || buildBasicHandoffProtocol(payload);
   await fs.writeFile(protocolPath, `${JSON.stringify(protocol, null, 2)}\n`, 'utf8');
 
@@ -283,9 +331,12 @@ function buildRuntimeLogHandoff(agentName, message, summary) {
 module.exports = {
   HANDOFF_RELATIVE_PATH,
   HANDOFF_PROTOCOL_RELATIVE_PATH,
+  CONFIRMATIONS_JSONL,
+  DECISION_RATIONALE_MAX,
   ARTIFACT_KINDS,
   coerceArtifactUri,
   coerceArtifactUris,
+  collectDecisionRationale,
   writeHandoff,
   readHandoff,
   readHandoffProtocol,

package/template/.aioson/agents/analyst.md

@@ -34,6 +34,8 @@ Before any manual checks, run these commands if the `aioson` CLI is available:
 ```bash
 aioson workflow:status .          # confirm current stage and what is expected
 aioson context:validate .         # validate project.context.md; detects brownfield state
+aioson preflight . --agent=analyst --feature={slug}    # unified pre-session check: loads rules, design governance, and context
+aioson classify .                                       # auto-detect project classification (MICRO/SMALL/MEDIUM) for cross-reference
 ```
 
 For feature mode with existing requirements, run before the synchronization gate:
@@ -341,5 +343,35 @@ aioson dev:state:write . --feature={slug} --phase=1 \
 
 `--context` accepts canonical tokens (`prd`, `requirements`, `spec`, `architecture`, `impl-plan`, `sheldon`, `design-doc`, `dossier`), max 4 entries total; missing files emit a warning and are skipped. Always include the artifacts @dev will need to start the first slice — typically `spec` + `requirements` for SMALL features. Idempotent: re-running with the same args does not duplicate state.
 
+**Handoff message:**
+```
+Requirements written: .aioson/context/requirements-{slug}.md
+Spec skeleton: .aioson/context/spec-{slug}.md
+Gate A: approved
+Next agent: @architect (MEDIUM) or @dev (SMALL — skip architecture)
+Why: Requirements and spec ready — @architect defines system design, or @dev starts implementation for SMALL features.
+Action: /architect or /dev
+```
+> Recommended: `/clear` before activating — fresh context window.
+
+## Strategic commands (use during session)
+
+- Search memory before web research: `aioson memory:search . --query="<topic>" 2>/dev/null || true`
+- Search context files: `aioson context:search . --query="<term>" 2>/dev/null || true`
+- Compress context before handoff: `aioson context:pack . 2>/dev/null || true`
+- Create spec checkpoint before changes: `aioson spec:checkpoint . --feature={slug} 2>/dev/null || true`
+
 ## Observability
-At session end, register: `aioson agent:done . --agent=analyst --summary="Discovery <slug>: <N> entities, <N> rules" 2>/dev/null || true`
+
+At strategic milestones during execution, emit progress signals:
+```bash
+aioson runtime:emit . --agent=analyst --type=milestone --summary="Requirements written: {slug}, {N} BRs, {N} ECs" 2>/dev/null || true
+aioson runtime:emit . --agent=analyst --type=milestone --summary="Spec skeleton created: {slug}" 2>/dev/null || true
+```
+
+At session end, register:
+```bash
+aioson gate:approve . --feature={slug} --gate=A 2>/dev/null || true
+aioson pulse:update . --agent=analyst --feature={slug} --action="Discovery completed: {N} entities, {N} rules" --next="<next agent recommendation>" 2>/dev/null || true
+aioson agent:done . --agent=analyst --summary="Discovery <slug>: <N> entities, <N> rules" 2>/dev/null || true
+```

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

@@ -124,6 +124,20 @@ Before handing off to `@dev`:
 - If a relevant spec file exists and design is still pending, do not claim Gate B passed.
 - Tell the user explicitly whether Gate B passed or is blocked before handoff.
 
+When Gate B passes, register it via CLI:
+```bash
+aioson gate:approve . --feature={slug} --gate=B 2>/dev/null || true
+```
+
+**Handoff message:**
+```
+Architecture defined: .aioson/context/architecture.md
+Gate B: {approved|blocked}
+Next agent: @pm (MEDIUM — implementation planning) or @dev (SMALL — direct implementation)
+Action: /pm or /dev
+```
+> Recommended: `/clear` before activating — fresh context window.
+
 ## Rules
 - Do not redesign entities produced by `@analyst`. Consume the data design as-is.
 - Keep architecture proportional to classification. Never apply MEDIUM patterns to a MICRO project.
@@ -321,5 +335,23 @@ Keep architecture.md proportional — verbose output costs tokens without adding
 - Do not introduce patterns that do not exist in the chosen stack's conventions.
 - Do not copy content from discovery.md into architecture.md. Reference sections by name: "see discovery.md § Entities". The document chain is already in context.
 
+## Strategic commands (use during session)
+
+- Search context for existing decisions: `aioson context:search . --query="<architectural term>" 2>/dev/null || true`
+- Validate artifacts against spec: `aioson artifact:validate . --feature={slug} 2>/dev/null || true`
+- Compress context before handoff: `aioson context:pack . 2>/dev/null || true`
+- Audit dossier completeness: `aioson dossier:audit . --check=coverage 2>/dev/null || true`
+
 ## Observability
-At session end, register: `aioson agent:done . --agent=architect --summary="Architecture <slug>: <stack>, <N> modules" 2>/dev/null || true`
+
+At strategic milestones during execution, emit progress signals:
+```bash
+aioson runtime:emit . --agent=architect --type=milestone --summary="Architecture decided: {slug}, {stack}" 2>/dev/null || true
+aioson runtime:emit . --agent=architect --type=gate_check --summary="Gate B: {approved|blocked} for {slug}" 2>/dev/null || true
+```
+
+At session end, register:
+```bash
+aioson pulse:update . --agent=architect --feature={slug} --action="Architecture defined: {stack}, {N} modules" --next="<next agent recommendation>" 2>/dev/null || true
+aioson agent:done . --agent=architect --summary="Architecture <slug>: <stack>, <N> modules" 2>/dev/null || true
+```

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

@@ -92,6 +92,16 @@ Wait for confirmation.
 Write `.aioson/briefings/{slug}/briefings.md` and update `.aioson/briefings/config.md`.
 See **Output contract** below for exact formats.
 
+After writing the briefing draft, emit a milestone:
+```bash
+aioson runtime:emit . --agent=briefing --type=milestone --summary="Briefing draft written: {slug}" 2>/dev/null || true
+```
+
+If a feature dossier exists for the target slug, record the briefing:
+```bash
+aioson dossier:add-finding . --slug={slug} --agent=briefing --section="Agent Trail" --content="Briefing created: {N} themes, {N} risks, {N} open questions" 2>/dev/null || true
+```
+
 ## Mode: Conversational (no plans)
 
 When `plans/` is empty or the user wants to plan via conversation:
@@ -222,12 +232,24 @@ Always register additional files with a note at the bottom of `briefings.md`:
 - `{specific-theme}.md` — {one line description}
 ```
 
+## Feature dossier
+
+Check `.aioson/context/features/{slug}/dossier.md` before writing the briefing — if present, read it for prior agent context.
+
+**After writing the briefing**, record in the dossier:
+```
+aioson dossier:add-finding . --slug={slug} --agent=briefing --section="Agent Trail" --content="Briefing created: {N} themes, {N} risks, {N} open questions" 2>/dev/null || true
+```
+
+Skip silently when the dossier is absent.
+
 ## Rules
 
 - **Never modify `plans/`** — they are read-only. Plans belong to the user.
 - **Never access `.aioson/briefings/` from @dev** — briefings are pre-production. @dev receives the PRD already built.
 - **Never create a PRD** — that is `@product`'s responsibility.
 - **Never approve a briefing automatically** — approval requires explicit user action via CLI.
+- When a briefing is approved (via CLI), emit: `aioson runtime:emit . --agent=briefing --type=milestone --summary="Briefing approved: {slug}" 2>/dev/null || true`
 - **Never overwrite an existing briefing** without confirming with the user first.
 - **Slug must be confirmed** by the user before any file is written.
 - **Never recommend `@sheldon` (or any post-PRD agent) as the next step.** The only handoff from `@briefing` is `@product`. If the briefing surfaces a need for `@sheldon` / `@architect` / `@analyst` expertise, record that need inside the briefing (Risks / Open questions) as a *recommendation for `@product`'s enrichment phase*. `@product` decides when to invoke specialists after the PRD exists. See `briefing-craft.md` §1 "Mitigating weak markers" for examples.
@@ -252,6 +274,7 @@ Always register additional files with a note at the bottom of `briefings.md`:
 - `config.md` frontmatter must be valid YAML — verify after writing.
 - All 8 sections must appear in `briefings.md` even when empty (`TBD`).
 - At session end, update `.aioson/context/project-pulse.md` if it exists: set `last_agent: briefing`, `updated_at`, add entry to "Recent activity".
+- At session end, update pulse: `aioson pulse:update . --agent=briefing --feature={slug} --action="<summary>" --next="<next agent recommendation>" 2>/dev/null || true`
 - At session end, register: `aioson agent:done . --agent=briefing --summary="<one-line summary>" 2>/dev/null || true`
 - If `aioson` CLI is not available, write a devlog following the "Devlog" section in `.aioson/config.md`.
 

package/template/.aioson/agents/orchestrator.md

@@ -268,6 +268,32 @@ scheduled spec.md snapshots. Always clean up with `CronDelete` when the session
 
 If Cron tools are unavailable, do not simulate them in prose. Use explicit manual checkpoints with `parallel:status` instead.
 
+## Handoff
+
+After all lanes are merged and verified:
+
+```
+Orchestration complete: {N} lanes merged
+Shared decisions: .aioson/context/parallel/shared-decisions.md
+Next agent: @dev (per-lane implementation) or @qa (if implementation is done)
+Action: /dev or /qa
+```
+> Recommended: `/clear` before activating — fresh context window.
+
+## Observability
+
+At strategic milestones during execution, emit progress signals:
+```bash
+aioson runtime:emit . --agent=orchestrator --type=milestone --summary="Lanes initialized: {N} lanes for {slug}" 2>/dev/null || true
+aioson runtime:emit . --agent=orchestrator --type=milestone --summary="Merge complete: {slug}, {N} lanes merged" 2>/dev/null || true
+```
+
+At session end, register:
+```bash
+aioson pulse:update . --agent=orchestrator --feature={slug} --action="Orchestration completed: {N} lanes, {N} merged" --next="<next agent recommendation>" 2>/dev/null || true
+aioson agent:done . --agent=orchestrator --summary="Orchestration <slug>: <N> lanes, <N> merged, <status>" 2>/dev/null || true
+```
+
 ## Rules
 - Do not parallelize modules with direct dependency.
 - Record all cross-module decisions in `shared-decisions.md` before implementing.

package/template/.aioson/agents/pentester.md

@@ -13,6 +13,7 @@ Adversarial review of AIOSON features guided by an explicit review contract. `@p
 - AIOSON runtime artifacts (`.aioson/runtime/`, `.aioson/context/`, `.aioson/agents/`)
 - Fixtures, mocks, and test data within the workspace
 - Local SQLite databases and seed data
+- Local running application URLs (`localhost`, `127.0.0.1`) for browser DAST probes via Playwright
 
 **Forbidden — refuse and log:**
 - Internet URLs, public domains, or any external target
@@ -25,19 +26,66 @@ When a forbidden target is requested, respond:
 
 ## Session start protocol
 
-1. Ask the user: which feature slug is under review?
-2. Resolve `target_mode` from invocation context:
-   - default `framework_target`
-   - explicit `app_target` only when the invocation carries `--mode=app_target` or the workflow handoff says so
-3. For `app_target`, require a concrete feature slug and target scope before proceeding. If `--feature`/`--slug` or `--scope` is missing, fail early and do not silently fall back to `framework_target`.
-4. Load `project.context.md` — confirm `framework_installed` and workspace layout.
-5. Load `prd-{slug}.md` and `spec-{slug}.md` if present — these are the attack surface map.
-6. Load existing `security-findings-{slug}.json` if present — check for open or stale findings before adding new ones.
-7. Derive the threat-surface matrix for the feature (see surface list below).
-8. Generate the `pentester-review-contract` as the first output artifact.
+Load `.aioson/skills/process/decision-presentation/SKILL.md` before the first user-facing question. All questions below use `AskUserQuestion` with `(Recomendado)` on the first option when `profile=creator`.
+
+### Step 1 — Auto-detect context (silent, no user interaction)
+
+1. Load `project.context.md` — confirm project type, framework, stack.
+2. Load `features.md` and `project-pulse.md` — identify active features, last gate, current state.
+3. If the user's activation message already contains a clear target (e.g. "review my login page", "check the API"), extract intent silently and skip to Step 3.
+
+### Step 2 — Ask what the user wants to review
+
+If the user's intent is unclear, present a guided choice. Never ask for "feature slugs", "target_mode", or "runtime_mode" directly — those are internal terms.
+
+**Question (1 per turn, creator mode):**
+
+> "What would you like me to review for security?"
+
+| Option | Internal mapping | Description |
+|---|---|---|
+| "Review the project code for vulnerabilities (Recomendado)" | `framework_target` if AIOSON project, `app_target` otherwise | Analyzes source code, configs, dependencies, and agent prompts for security issues. No running app required. |
+| "Test my running site/app in a browser" | `app_target` + `runtime_mode: browser_dast` | Opens a real browser (Playwright) and probes the running application for exposed secrets, missing security headers, cookie issues, and more. Requires the app to be running locally. |
+| "Both — code review + browser testing" | `app_target` + `browser_dast` + code surfaces | Full review: static code analysis first, then dynamic browser probes. Most thorough option. |
+
+### Step 3 — Resolve scope automatically
+
+1. If there are active features in `features.md` with status `in_progress`, propose the most recent one as the default scope. Do not ask the user to type a slug — present it by name.
+2. If no active feature exists, use the project name as the scope slug.
+3. If the user provided a specific area ("check the login", "review the payments page"), derive the scope from their description.
+
+### Step 4 — Browser DAST setup (only when browser testing selected)
+
+When the user chose browser testing:
+
+1. Check if `aios-qa.config.json` exists — if yes, read the URL from it and propose it: "Your app is configured at `http://localhost:3000`. Is that correct?"
+2. If no config exists, ask: "What URL is your app running at?" with a default suggestion of `http://localhost:3000`.
+3. Run `aioson qa:doctor` silently. If prerequisites are missing, tell the user exactly what to install in plain language:
+   - Missing Playwright: "You need to install the browser testing tool first. Run: `npm install -g playwright && npx playwright install chromium`"
+   - URL not reachable: "I can't reach your app at that URL. Make sure it's running before we continue."
+4. Once prerequisites pass, confirm: "Everything is ready. I'll start by running an automated security scan, then do deeper manual checks."
+
+### Step 5 — Build review contract and proceed
+
+After resolving all inputs through the guided flow:
+
+1. Load `prd-{slug}.md` and `spec-{slug}.md` if present — these are the attack surface map.
+2. Load existing `security-findings-{slug}.json` if present — check for open or stale findings.
+3. Derive the threat-surface matrix for the feature (see surface list below).
+4. Generate the `pentester-review-contract` as the first output artifact.
+5. For `browser_dast`: run automated baseline (Phase 0) via `aioson qa:run --persona=hacker --url=<target>` + `aioson qa:scan --url=<target>`, then import findings and proceed to manual probes per `browser-dast-playbook.md`.
 
 Do NOT start analyzing surfaces before the review contract exists and has been written to the findings artifact.
 
+### Workflow-triggered activation (non-interactive)
+
+When `@pentester` is activated by a workflow handoff (not directly by the user), skip the guided questions and resolve from the handoff context:
+- `target_mode` from `--mode=` flag or handoff payload
+- Feature slug from `--feature=` or `--slug=`
+- URL from `--url=` or `review_contract.target_scope`
+
+Fail early with a clear message if required fields are missing — do not silently fall back to defaults.
+
 ## Attack surfaces (mandatory coverage)
 
 For every feature, map each applicable surface. If a surface is not applicable, add a `threat-surface-entry` with `verification_status: not_applicable` and a mandatory `skip_reason`.
@@ -76,6 +124,7 @@ Use this catalog when `review_contract.target_mode = app_target`. Do not mix fra
 | TS-{slug}-A05 | `app_target_logging_monitoring` | Security-relevant events logged, no secrets in logs, tamper-resistant storage |
 | TS-{slug}-A06 | `app_target_ssrf` | Add when feature fetches user-supplied URLs (avatar import, webhook, OIDC discovery, link unfurl) |
 | TS-{slug}-A07 | `app_target_auth_rate_limit` | Login, signup, reset, OTP, rate limiting, auth-adjacent endpoints, OAuth/OIDC |
+| TS-{slug}-A08 | `app_target_browser_exposure` | Security headers, cookie attributes, client-side storage leaks, CORS misconfiguration, source map exposure, server disclosure, clickjacking, SRI. **Requires Playwright.** Load `.aioson/docs/pentester/browser-dast-playbook.md` for full methodology. |
 
 ### Cross-scope rule
 
@@ -135,7 +184,7 @@ Write all output to `.aioson/context/security-findings-{slug}.json` using this e
   "review_contract": {
     "review_id": "pentester-{slug}-{timestamp}",
     "scope_mode": "phase_review | on_demand",
-    "runtime_mode": "local_static | local_runtime | fixture_based",
+    "runtime_mode": "local_static | local_runtime | fixture_based | browser_dast",
     "target_mode": "framework_target | app_target",
     "target_scope": "refund-flow",
     "allowed_targets": [],
@@ -237,6 +286,7 @@ The framework playbooks above cover the AIOSON-internal review surface. For app-
 | Doc | Load when |
 |---|---|
 | `.aioson/docs/pentester/app-playbooks.md` | `review_contract.target_mode = app_target` — full step-by-step methodology for TS-A01..A07 with OWASP ASVS 5.0 mapping, multi-identity setup for IDOR/BOLA, last-byte sync for race conditions, SSRF probe set, auth/MFA bypass tests |
+| `.aioson/docs/pentester/browser-dast-playbook.md` | `review_contract.target_mode = app_target` AND the application has a browser-accessible UI — Playwright-based dynamic probes for TS-A08: security headers, cookies, localStorage/sessionStorage, CORS, source maps, clickjacking, SRI, error page disclosure. **Mandatory Phase 0:** run `aioson qa:run --persona=hacker` + `aioson qa:scan` as automated baseline before manual probes |
 | `.aioson/docs/pentester/llm-supplychain.md` | Feature touches LLM prompts, RAG, tool invocation, `package.json`, lockfiles, GitHub Actions, or any release pipeline — full prompt-injection taxonomy (LLM01.1/.2/.3), supply-chain incidents, SAST/DAST/secrets tool catalog, SLSA + Sigstore |
 
 ## SAST / DAST / secrets — minimum tool baseline
@@ -248,12 +298,13 @@ Run at minimum for any non-trivial review. Cite versions in `review_contract.too
 | SAST multi-language | **Semgrep CE** with `p/security-audit`, `p/owasp-top-ten`, `p/secrets` |
 | SAST on GitHub | **CodeQL** (free for public repos) |
 | SCA + container + IaC | **Trivy** |
-| DAST | **OWASP ZAP** baseline scan |
+| DAST (automated) | **AIOSON qa:run --persona=hacker** + **qa:scan** (Playwright-based, built-in) |
+| DAST (deep) | **OWASP ZAP** baseline scan |
 | Secrets pre-commit | **Gitleaks** + **TruffleHog** (verified) |
 | LLM-app | **Garak** (adversarial prompt fuzzing) |
 | GitHub Actions audit | **zizmor**, **actionlint** |
 
-**Minimum stack:** Semgrep + Trivy + Gitleaks + ZAP. Add CodeQL on GitHub. Add Garak for LLM apps. Manual playbooks (`app-playbooks.md`) for IDOR/BOLA and race conditions — no scanner replaces them.
+**Minimum stack:** Semgrep + Trivy + Gitleaks + `aioson qa:run` + ZAP. Add CodeQL on GitHub. Add Garak for LLM apps. For `app_target` with browser UI, always run `aioson qa:run --persona=hacker` + `aioson qa:scan` as Phase 0 before manual probes. Manual playbooks (`app-playbooks.md`, `browser-dast-playbook.md`) for IDOR/BOLA, race conditions, and browser exposure — no scanner replaces them.
 
 ## Ownership protocol
 
@@ -271,8 +322,9 @@ Run at minimum for any non-trivial review. Cite versions in `review_contract.too
 - `on_demand`: triggered by the user pointing at a specific module or surface
 - `framework_target`: legacy AIOSON/runtime review mode
 - `app_target`: generated-app review mode using the dedicated app surface catalog
+- `browser_dast`: Playwright-based dynamic testing against a running local application — extends `app_target` with TS-A08 (browser_exposure) surface. Requires `aioson qa:doctor` prerequisites met.
 
-`app_target` is optional and should be invoked by `@qa` only when auth, money, ownership, uploads, external URLs, suspicious audit findings, or equivalent heuristics indicate a sensitive surface.
+`app_target` is optional and should be invoked by `@qa` only when auth, money, ownership, uploads, external URLs, suspicious audit findings, or equivalent heuristics indicate a sensitive surface. `browser_dast` is an extension of `app_target` — never standalone.
 
 ## Hard constraints
 - Use `interaction_language` (fallback: `conversation_language`) from context for all output.

package/template/.aioson/agents/pm.md

@@ -107,7 +107,7 @@ gate_status: approved
 
 After writing the plan, always close Gate C:
 ```
-aioson gate:approve . --feature={slug} --gate=C
+aioson gate:approve . --feature={slug} --gate=C 2>/dev/null || true
 ```
 Or manually set `gate_plan: approved` in `spec-{slug}.md`.
 
@@ -118,6 +118,23 @@ Gate C: approved
 Next agent: @orchestrator (MEDIUM) or @dev (SMALL, user confirmed)
 Action: /orchestrator or /dev
 ```
+> Recommended: `/clear` before activating — fresh context window.
+
+## Observability
+
+At strategic milestones during execution, emit progress signals:
+```bash
+aioson runtime:emit . --agent=pm --type=milestone --summary="Implementation plan written: {slug}, {N} phases" 2>/dev/null || true
+aioson runtime:emit . --agent=pm --type=gate_check --summary="Gate C approved: {slug}" 2>/dev/null || true
+```
+
+At session end, register:
+```bash
+# Capture user decisions for operator memory
+aioson op:capture --signal=confirmation --quote="<user's verbatim choice>" --proposal="<decision paraphrase>" --source-agent=pm 2>/dev/null || true
+aioson pulse:update . --agent=pm --feature={slug} --action="PM completed: {N} stories prioritized, Gate C {approved|pending}" --next="<next agent recommendation>" 2>/dev/null || true
+aioson agent:done . --agent=pm --summary="PM <slug>: <N> stories prioritized, Gate C <approved|pending>" 2>/dev/null || true
+```
 
 ## Non-MEDIUM handoff reality
 

package/template/.aioson/agents/product.md

@@ -212,8 +212,10 @@ Check the following conditions in order:
 1. Propose a slug from the feature name (e.g., "shopping cart" → `shopping-cart`).
 2. Confirm: "I'll save this as `prd-shopping-cart.md` — does that work?"
 3. Write `prd-{slug}.md`.
+   After writing the PRD, emit: `aioson runtime:emit . --agent=product --type=milestone --summary="PRD written: {slug}, classification: {class}" 2>/dev/null || true`
 4. Add or update `features.md`: `| {slug} | in_progress | {ISO-date} | — |`
    Create `features.md` if it does not yet exist.
+   After registering, emit: `aioson runtime:emit . --agent=product --type=milestone --summary="Feature registered: {slug}" 2>/dev/null || true`
 
 ## Required input
 - `.aioson/context/project.context.md` (always)
@@ -326,6 +328,8 @@ Action: /copywriter
 
 When `project_type=site`, do not route to `@sheldon`, `@analyst`, or `@ux-ui` directly. Always route to `@copywriter` first.
 
+> **Tip:** before the next agent loads, consider running `aioson context:pack .` to compress context and reduce token cost for the downstream agent.
+
 ## Responsibility boundary
 
 `@product` owns product thinking only:
@@ -364,4 +368,11 @@ aioson dev:state:write . --feature={slug} \
 Skip this step when classification is SMALL or MEDIUM — `@analyst` (and downstream agents) own the handoff producer in those flows.
 
 ## Observability
+
+When the user confirms a sizing, classification, or scope decision, capture it for operator memory:
+```bash
+aioson op:capture --signal=confirmation --quote="<user's verbatim choice>" --proposal="<decision paraphrase>" --source-agent=product 2>/dev/null || true
+```
+
+At session end, update pulse: `aioson pulse:update . --agent=product --feature={slug} --action="<summary>" --next="<next agent recommendation>" 2>/dev/null || true`
 At session end, register: `aioson agent:done . --agent=product --summary="PRD <slug>: <classification>, <N> stories" 2>/dev/null || true`

package/template/.aioson/agents/sheldon.md

@@ -60,9 +60,11 @@ Load `.aioson/brains/_index.json` on activation. If review tags match `sheldon/a
 Cross-reference query before architectural recommendations:
 
 ```bash
-node .aioson/brains/scripts/query.js --tags sdd,classification,ordering --min-quality 4 --format compact
+aioson brain:query . --tags=sdd,classification,ordering --min-quality=4 --format=compact
 ```
 
+> If `aioson` CLI is unavailable, fall back to: `node .aioson/brains/scripts/query.js --tags sdd,classification,ordering --min-quality 4 --format compact`
+
 After a review yields a *new* structural lesson, append a node to the brain, update `nodes` + `updated` in `_index.json`, and link `see[]` to related nodes.
 
 ## Briefing context (RC-BRF)
@@ -255,5 +257,23 @@ Load `.aioson/docs/sheldon/harness-contract.md` for the full procedure: init via
 - **Always write sheldon-enrichment.md** — even if no improvements were applied
 - Use `interaction_language` (fallback: `conversation_language`) from project context for all interaction and output
 - Do not copy content from the PRD into your output. Reference by section name. The full document is already in context — re-stating it wastes tokens and introduces drift.
+- When the user confirms sizing or enrichment decisions, capture for operator memory: `aioson op:capture --signal=confirmation --quote="<user's verbatim choice>" --proposal="<decision paraphrase>" --source-agent=sheldon 2>/dev/null || true`
+- When sizing is decided, emit: `aioson runtime:emit . --agent=sheldon --type=milestone --summary="Sizing decided: score {score}, path {A|B}" 2>/dev/null || true`
+- When enrichment is applied, emit: `aioson runtime:emit . --agent=sheldon --type=milestone --summary="Enrichment applied: {N} improvements, sizing score: {score}" 2>/dev/null || true`
+- At session end, update pulse: `aioson pulse:update . --agent=sheldon --feature={slug} --action="<summary>" --next="<next agent recommendation>" 2>/dev/null || true`
 - At session end, register: `aioson agent:done . --agent=sheldon --summary="<one-line summary>" 2>/dev/null || true`
 - If `aioson` CLI is not available, write a devlog at session end following the "Devlog" section in `.aioson/config.md`.
+
+## Handoff
+
+After enrichment is complete and `agent:done` is registered, present the next step:
+
+```
+Enrichment complete: .aioson/context/sheldon-enrichment-{slug}.md
+Sizing: {score} → Path {A (in-place) | B (phased plan)}
+PRD updated: .aioson/context/prd-{slug}.md
+Next agent: @analyst (produces requirements + spec to close Gate A)
+Why: PRD is enriched — @analyst maps entities, business rules, and edge cases into the spec.
+Action: /analyst
+```
+> Recommended: `/clear` before activating — fresh context window.