session-orchestrator 3.16.0

package/commands/templates-ack.md

@@ -0,0 +1,96 @@
+---
+description: Acknowledge templates-first policy for the current session — bypasses the pre-bash-templates-first hook for the remainder of the session
+argument-hint: "[optional-reason]"
+---
+
+# Templates Acknowledgement
+
+Write a session-scoped acknowledgement entry to `.orchestrator/runtime/templates-acknowledged.json`. Once written, the `pre-bash-templates-first` hook (G6) will allow `gh`/`glab` create operations for the rest of the current session without requiring a prior template Read.
+
+**Use this only when:**
+- You have already reviewed the relevant template externally (e.g. copy-paste workflow), OR
+- You are running an automated or retro merge that does not benefit from template enforcement.
+
+## Implementation
+
+Run the following node snippet to write the acknowledgement:
+
+```bash
+node --input-type=module -e "
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+const cwd = process.cwd();
+const sessionFile = join(cwd, '.orchestrator', 'current-session.json');
+const ackFile = join(cwd, '.orchestrator', 'runtime', 'templates-acknowledged.json');
+const reason = process.argv[1] ?? '';
+const userId = process.env.USER ?? process.env.USERNAME ?? '';
+
+// Resolve session_id
+let sessionId = null;
+if (existsSync(sessionFile)) {
+  try {
+    const raw = JSON.parse(readFileSync(sessionFile, 'utf8'));
+    sessionId = raw.session_id ?? raw.sessionId ?? null;
+  } catch { /* ignore */ }
+}
+if (!sessionId) {
+  process.stderr.write('⚠ templates-ack: could not read session_id from .orchestrator/current-session.json — ack not written\n');
+  process.exit(1);
+}
+
+// Read existing ack file (or start fresh)
+let existing = {};
+if (existsSync(ackFile)) {
+  try { existing = JSON.parse(readFileSync(ackFile, 'utf8')); } catch { existing = {}; }
+}
+
+// Build new entry
+const entry = { acknowledgedAt: new Date().toISOString() };
+if (userId) entry.userId = userId;
+if (reason) entry.reason = reason;
+existing[sessionId] = entry;
+
+// Atomic write via tmp + rename
+const dir = dirname(ackFile);
+if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+const tmp = ackFile + '.tmp.' + randomBytes(4).toString('hex');
+writeFileSync(tmp, JSON.stringify(existing, null, 2) + '\n', 'utf8');
+renameSync(tmp, ackFile);
+
+process.stdout.write('✓ templates-ack: session ' + sessionId + ' acknowledged at ' + entry.acknowledgedAt + '\n');
+process.stdout.write('  Written: ' + ackFile + '\n');
+if (reason) process.stdout.write('  Reason: ' + reason + '\n');
+" -- "\$ARGUMENTS"
+```
+
+## Verification
+
+After writing, confirm the entry exists:
+
+```bash
+node -e "
+const f = require('fs');
+const p = '.orchestrator/runtime/templates-acknowledged.json';
+if (!f.existsSync(p)) { console.log('NOT FOUND'); process.exit(1); }
+const d = JSON.parse(f.readFileSync(p, 'utf8'));
+console.log(JSON.stringify(d, null, 2));
+"
+```
+
+## Schema
+
+The acknowledgement file stores one entry per session:
+
+```json
+{
+  "<sessionId>": {
+    "acknowledgedAt": "2026-05-22T14:30:45.123Z",
+    "userId": "user@example.com",
+    "reason": "Bypass for retro merge"
+  }
+}
+```
+
+The hook reads `entry.acknowledgedAt` to confirm a valid session-scoped bypass.

package/commands/test.md

@@ -0,0 +1,97 @@
+---
+description: Agentic end-to-end test orchestrator — drive web/macOS flows, evaluate UX rubric, reconcile issues
+argument-hint: "[scope|profile-name] [--since <git-ref>] [--full]"
+---
+
+# Test
+
+Run agentic end-to-end tests against the current project or a named target. The user invoked `/test` with arguments: **$ARGUMENTS**
+
+This command resolves a test target and profile, dispatches the appropriate driver (Playwright for web, Peekaboo for macOS), invokes the `ux-evaluator` agent against the captured artifacts, and reconciles findings with the open issue tracker. All logic lives in `skills/test-runner/SKILL.md` — this file is the user-facing entry point only.
+
+## Argument Validation
+
+Parse `$ARGUMENTS` before doing anything else.
+
+Recognized flags and positional arguments:
+
+- `--target <name>` — explicit target name (e.g. `your-target-app`, `your-mobile-app`). Sets `explicit_target = true`.
+- `--profile <name>` — explicit profile name (e.g. `smoke`, `full`, `a11y`, `onboarding`). Sets `explicit_profile = true`.
+- `--dry-run` — resolve target and profile, print the dispatch plan, but do NOT invoke any driver or create any issues. Sets `dry_run = true`.
+- `--since <git-ref>` — restrict test execution to files changed since the given git ref. Sets `since_ref = <git-ref>`.
+- `--full` — explicit full-repo scan. Sets `full_scan = true`.
+- `[scope]` — any unrecognized positional token is treated as a profile name (same as `--profile <scope>`).
+
+**Conflict check:** If BOTH `--since` and `--full` are present, stop immediately and report:
+
+```
+Error: Cannot use --since with --full. Provide one, not both.
+```
+
+Do NOT proceed with test execution when this conflict is present.
+
+If `$ARGUMENTS` contains an unrecognized flag (i.e. starts with `--` but is not one of the above), inform the user:
+
+```
+Unknown flag '<flag>'. Recognized flags: --target <name>, --profile <name>, --dry-run, --since <git-ref>, --full.
+```
+
+Then continue with the remaining valid arguments.
+
+## Argument Precedence Resolution
+
+Resolve `target` and `profile` using the following precedence (highest → lowest). Stop at the first rule that produces a value for each variable.
+
+1. **Explicit flags** — `--target <name>` sets `target`; `--profile <name>` sets `profile`. Highest priority. Both may be provided together.
+2. **Profile from policy, target explicit** — if only `--target <name>` is provided (no `--profile`), pass `target` to the test-runner skill; the skill resolves the profile from `.orchestrator/policy/test-profiles.json` or its default.
+3. **Target from policy, profile explicit** — if only `--profile <name>` is provided (no `--target`), pass `profile` to the test-runner skill; the skill resolves the target via convention-based detection.
+4. **Positional token as profile** — if a bare positional argument (no `--` prefix) is present in `$ARGUMENTS`, treat it as `profile`. The test-runner skill resolves the target via convention.
+5. **Session Config default** — if the Session Config block contains `test-runner.default-profile`, use that value for `profile`. Target is still resolved by the skill via convention.
+6. **Interactive AUQ** — if no target or profile could be resolved from steps 1–5, proceed to the Profile Selection section below before invoking the skill.
+
+## Profile Selection
+
+**Only execute this section when steps 1–5 above produced neither `target` nor `profile`.**
+
+Present the user with a structured choice via `AskUserQuestion`:
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "Which test profile should be run?",
+    header: "Test Command: profile selection",
+    options: [
+      { label: "smoke (Recommended)", description: "Quick sanity pass — key flows, axe critical/serious, console errors." },
+      { label: "full", description: "All checks at full depth — slower, used before release." },
+      { label: "a11y", description: "Accessibility-focused pass — axe-core exhaustive scan." },
+      { label: "onboarding", description: "Onboarding step-count + Liquid Glass conformance checks." }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+Set the user's selection as `profile`. The test-runner skill will resolve the target from convention.
+
+## Invoke Test-Runner Skill
+
+**Invoke the test-runner skill.** Follow its instructions precisely.
+
+Read `skills/test-runner/SKILL.md` and execute all phases in order. Do NOT skip Phase 0 (bootstrap gate). Do NOT inline driver artifact content into the coordinator context — all artifacts go to disk under the run directory.
+
+Pass the following handoff contract to the skill entry point.
+
+## Handoff Contract
+
+The five named arguments below are the canonical contract between this command and `skills/test-runner/SKILL.md`. The skill reads them from context; do NOT reconstruct them inside the skill.
+
+| Argument | Type | Value |
+|---|---|---|
+| `target` | `string \| undefined` | Resolved target name, or `undefined` if not yet known (skill resolves via convention) |
+| `profile` | `string \| undefined` | Resolved profile name, or `undefined` if not yet known (skill applies `test-runner.default-profile` or `smoke`) |
+| `dry_run` | `boolean` | `true` if `--dry-run` was passed; `false` otherwise |
+| `explicit_target` | `boolean` | `true` if `--target` was present in `$ARGUMENTS`; `false` otherwise |
+| `explicit_profile` | `boolean` | `true` if `--profile` was present in `$ARGUMENTS`; `false` otherwise |
+| `since_ref` | `string \| undefined` | Git ref from `--since <git-ref>`, or `undefined` if not provided |
+
+The skill is the single source of truth for all further resolution, driver dispatch, evaluation, and issue reconciliation. Do NOT re-implement profile logic, driver selection, or issue triage in this command file.

package/docs/README.md

@@ -0,0 +1,105 @@
+# docs/ — Router
+
+This directory holds three distinct classes of document. Knowing which class a
+file belongs to tells you whether to trust it as current, read it as history,
+or look for it in the (private) Meta-Vault instead. See `docs/prd/2026-07-08-docs-public-split.md`
+(Epic #774) for the sanitation project that established this split.
+
+## The three classes
+
+### 1. Living reference
+
+Root-level `docs/*.md` files plus `docs/examples/*.md` and `docs/recipes/*.md`.
+These describe the **current** behaviour of the plugin — setup guides,
+schemas, architecture, config reference. They are corrected when found stale
+and mechanically monitored by two guards so drift does not silently
+re-accumulate:
+
+- **`claude-md-drift-check` Check 10 (`docs-parity`)** — session-end opt-in
+  gate; compares `docs/components.md` count-claims against on-disk counts and
+  diffs Session Config keys between `docs/session-config-template.md` and
+  `docs/session-config-reference.md`. See
+  [`docs/session-config-reference.md § CLAUDE.md Drift Check`](./session-config-reference.md#claudemd-drift-check).
+- **`/discovery` docs-staleness probe** — opt-in filesystem-mtime probe over
+  the same living-doc surface. See
+  [`docs/session-config-reference.md § Docs Staleness (#781)`](./session-config-reference.md#docs-staleness-781).
+
+`docs/templates/` (copy-paste config snippets, e.g. the `AGENTS.md` Session
+Config block) is treated as living reference too — it is read directly by
+setup instructions in the root docs above.
+
+`docs/pm-skills-marketplace.md` is a root-level living-reference doc: when to
+install the `phuryn/pm-skills` marketplace alongside this plugin (product-heavy
+repos with standalone PM artifacts), when not to (the techniques are already
+cribbed into `/grill`, `/brainstorm`, `/plan`, and `/discovery`'s `feature`
+scope), and the overlap table between the two.
+
+### 2. Public decision history
+
+`docs/adr/` — Architecture Decision Records. These stay public permanently:
+ADRs are an industry-standard artifact, and the plugin's own ADRs are cited
+externally. Unlike living reference docs, ADRs are not "corrected" for
+staleness — a decision recorded on the date it was made is not wrong later,
+even if a subsequent ADR supersedes it. Where an ADR cites a since-archived
+research record or spike (see class 3 below), the citation names the record's
+**title + issue number** rather than a `docs/research/…` path that no longer
+resolves in this repository — e.g. `"Instruction-Budget Mechanism —
+Coordinator-Injection Verdict" (#687; archived in the private Meta-Vault)`.
+
+### 3. Active work documents
+
+`docs/prd/` (PRDs of currently **open** epics) and `docs/plans/`
+(`/write-executable-plan` artifacts for in-progress work — the directory may
+be absent when nothing is currently mid-plan). Both are live working
+directories, not permanent archives. When an epic closes, the
+`archive-closed-prds` custom phase (`scripts/archive-closed-prds.mjs`, wired
+as a session-end/housekeeping custom phase) moves that epic's PRD out of
+`docs/prd/` into the private Meta-Vault automatically — no manual sweep
+required.
+
+## What is NOT here: archived in the Meta-Vault
+
+Everything that used to live under `docs/{research,spikes,spike-probes,
+test-runs,submissions,marketplace,baseline-diffs,experiments,migrations,
+audit}/`, plus PRDs of closed epics and the retired `docs/validation-checklist.md`,
+has moved to `<vault>/01-projects/session-orchestrator/<type>/` in the private
+Meta-Vault (type-folder convention, minimal generated frontmatter). These are
+process records — research notes, spike write-ups, test-run proofs, PR/issue
+submission drafts, baseline diffs, experiment reports, closed-epic PRDs — not
+reference material a consumer of the plugin needs.
+
+Two things worth knowing about this split:
+
+- **Removal is not un-publishing.** The records remain findable in this
+  repository's public git history even after removal from `HEAD` — deleting a
+  file from the working tree does not rewrite history. A sensitivity scan
+  (`check-owner-leakage`-based, plus manual sampling) ran over every moved
+  file before the move and confirmed zero critical findings; if that had
+  turned up real findings, a history rewrite would have been a separate,
+  explicit decision — not an automatic consequence of this move.
+- **The move is a `git rm`, not a copy.** Once a record is archived, it no
+  longer exists in this repository's working tree at all. Cross-references
+  from a still-public file (an ADR, this router, a living-reference doc) use
+  the title + issue-number convention above so the citation stays meaningful
+  even without a resolvable path.
+
+## Directory table
+
+| Directory | Class | Description |
+|---|---|---|
+| `docs/*.md` (root) | Living reference | Setup guides, config reference/template, architecture, schemas — corrected on drift, monitored by Check 10 + the docs-staleness probe. |
+| `docs/examples/` | Living reference | Example Session Config blocks per project shape (Express API, integration test, Next.js, Swift/iOS). |
+| `docs/recipes/` | Living reference | Narrow how-to write-ups for a specific recurring pattern (e.g. the quality-gate container test-runner pattern). |
+| `docs/templates/` | Living reference | Copy-paste config snippets referenced directly by the setup guides (e.g. the `AGENTS.md` Session Config template). |
+| `docs/telemetry/` | Living reference | `telemetry-claims.md` — provenance/methodology notes for cross-repo telemetry numbers cited elsewhere in the docs. |
+| `docs/adr/` | Public decision history | Architecture Decision Records — permanent, never archived, cited externally. |
+| `docs/prd/` | Active work document | PRDs of currently open epics only. Auto-archived to the Meta-Vault on epic close. |
+| `docs/plans/` | Active work document | `/write-executable-plan` artifacts for in-progress work. May not exist when nothing is mid-plan. |
+| `docs/_private/`, `docs/specs/` | Local-only (gitignored) | Operator scratch space; never tracked, out of scope for this classification. |
+
+## See Also
+
+- `docs/prd/2026-07-08-docs-public-split.md` — the epic that established this split (S1–S8, issues #775–#782).
+- `docs/session-config-reference.md` — full Session Config field reference, including the two guards named above.
+- `docs/pm-skills-marketplace.md` — when to install `phuryn/pm-skills` alongside this plugin, and the overlap table against `/grill`, `/brainstorm`, `/plan`, `/discovery`.
+- `README.md` — top-level project overview; links into this router for anything docs-specific.