@asrunjs/asrun 0.2.0 → 0.5.3

package/dist/lib/run-filters.js

@@ -1,8 +1,14 @@
 /** `--grep` pattern that matches a tag exactly (`@smoke` must not match `@smoke-extra`). */
 const tagPattern = (name) => `@${name}(?![\\w-])`;
 const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Playwright matches `--grep` against a title that holds the spec file with the separator of this platform
+ * (`conduit/header-navigation.spec.ts` on macOS and Linux, `conduit\header-navigation.spec.ts` on Windows), so a
+ * `/` in a case id or in the user's search has to match either one. `\/` is left alone: it is already a plain `/`.
+ */
+const bothSeparators = (text) => text.replace(/(?<!\\)\//g, '[\\\\/]');
 /** Matches the spec file of one case (`documents/published-flow` must not match `documents/published-flow-2`). */
-export const casePattern = (id) => `(?:^|\\s)${escapeRegExp(id)}\\.spec\\.ts`;
+export const casePattern = (id) => `(?:^|\\s)${bothSeparators(escapeRegExp(id))}\\.spec\\.ts`;
 /**
  * The Playwright arguments that decide WHICH tests run. Shared by `pnpm asrun` and by the web UI's
  * "what would this run do" preview, so both always agree.
@@ -15,7 +21,9 @@ export function filterArgs(filters) {
         grepParts.push(`(?:${filters.suites.map(tagPattern).join('|')})`);
     }
     if (filters.grep) {
-        grepParts.push(`(?:${filters.grep})`);
+        // A case id (`conduit/header-navigation`) and a part of one (`conduit/head`) both have to match the spec file
+        // in Playwright's title, whatever separator this platform puts in it.
+        grepParts.push(`(?:${bothSeparators(filters.grep)})`);
     }
     if (filters.only && filters.only.length > 0) {
         grepParts.push(`(?:${filters.only.map(casePattern).join('|')})`);

package/dist/lib/session.d.ts

@@ -1,5 +1,5 @@
 import type { Browser } from '@playwright/test';
-import type { Profile } from './profiles.js';
+import { type Profile, type SessionCheck } from './profiles.js';
 export type SessionStatus = 'ok' | 'missing' | 'expired';
 /**
  * Set by `pnpm asrun` after its pre-run login check: `profile-id:status,profile-id:status`
@@ -7,7 +7,19 @@ export type SessionStatus = 'ok' | 'missing' | 'expired';
  */
 export declare const NOT_LOGGED_IN_ENV = "ASRUN_NOT_LOGGED_IN";
 export declare const hasSessionFile: (profile: Profile) => boolean;
+/** True when the address is (or starts below) the address a site sends a signed-out visitor to. */
+export declare function isLoggedOutUrl(url: string, check?: SessionCheck): boolean;
+/** Kept for callers that only ask about the conventional `/login` address. */
 export declare const isLoginUrl: (url: string) => boolean;
+/**
+ * Opens `sessionCheckPath` with the saved session and decides whether the profile is still signed in.
+ *
+ * A site can show "signed out" in more than one way, so every signal the profile names is watched at the
+ * same time: a redirect to `sessionCheck.loggedOutUrl` (server side or, in a single-page app, after the app
+ * has started), a 401/403 response, `loggedOutSelector`, or `loggedInSelector` proving the opposite. The
+ * page is read only after a signal arrived, never right after the navigation (which would still show the
+ * page before a client-side redirect happened).
+ */
 export declare function checkSession(browser: Browser, profile: Profile): Promise<SessionStatus>;
 export declare function parseNotLoggedIn(value?: string | undefined): Map<string, SessionStatus>;
 export declare const formatNotLoggedIn: (entries: Map<string, SessionStatus>) => string;

package/dist/lib/session.js

@@ -1,35 +1,101 @@
 import fs from 'node:fs';
+import { DEFAULT_SESSION_CHECK } from './profiles.js';
 import { authFile } from './paths.js';
 /**
  * Set by `pnpm asrun` after its pre-run login check: `profile-id:status,profile-id:status`
  * for every profile that is not logged in. Lets the config and fixtures skip a second check.
  */
 export const NOT_LOGGED_IN_ENV = 'ASRUN_NOT_LOGGED_IN';
+/** A response that means "you are not allowed in", for sites that answer with a status instead of a redirect. */
+const EXPIRED_STATUSES = new Set([401, 403]);
 export const hasSessionFile = (profile) => fs.existsSync(authFile(profile.id));
-export const isLoginUrl = (url) => {
+/** True when the address is (or starts below) the address a site sends a signed-out visitor to. */
+export function isLoggedOutUrl(url, check = DEFAULT_SESSION_CHECK) {
+    let target;
     try {
-        return new URL(url).pathname.startsWith('/login');
+        target = new URL(url);
     }
     catch {
         return false;
     }
-};
+    if (/^https?:\/\//i.test(check.loggedOutUrl)) {
+        try {
+            const expected = new URL(check.loggedOutUrl);
+            return target.origin === expected.origin && underPath(target.pathname, expected.pathname);
+        }
+        catch {
+            return false;
+        }
+    }
+    return underPath(target.pathname, check.loggedOutUrl);
+}
+const underPath = (pathname, expected) => pathname === expected || pathname.startsWith(expected.endsWith('/') ? expected : `${expected}/`);
+/** Kept for callers that only ask about the conventional `/login` address. */
+export const isLoginUrl = (url) => isLoggedOutUrl(url);
+/**
+ * Opens `sessionCheckPath` with the saved session and decides whether the profile is still signed in.
+ *
+ * A site can show "signed out" in more than one way, so every signal the profile names is watched at the
+ * same time: a redirect to `sessionCheck.loggedOutUrl` (server side or, in a single-page app, after the app
+ * has started), a 401/403 response, `loggedOutSelector`, or `loggedInSelector` proving the opposite. The
+ * page is read only after a signal arrived, never right after the navigation (which would still show the
+ * page before a client-side redirect happened).
+ */
 export async function checkSession(browser, profile) {
-    if (!hasSessionFile(profile)) {
+    if (!hasSessionFile(profile))
         return 'missing';
-    }
+    const check = profile.sessionCheck;
     const context = await browser.newContext({ storageState: authFile(profile.id) });
     try {
         const page = await context.newPage();
-        await page.goto(new URL(profile.sessionCheckPath, profile.baseURL).href, {
+        const response = await page.goto(new URL(profile.sessionCheckPath, profile.baseURL).href, {
             waitUntil: 'domcontentloaded',
         });
-        return isLoginUrl(page.url()) ? 'expired' : 'ok';
+        if (response && EXPIRED_STATUSES.has(response.status()))
+            return 'expired';
+        if (isLoggedOutUrl(page.url(), check))
+            return 'expired';
+        const signal = await firstSignal(page, check);
+        if (signal)
+            return signal;
+        // Nothing showed up: fall back to the address, which is all a plain redirect leaves behind. A profile
+        // that named a signed-in marker gets an error instead, so a wrong check path is visible instead of "ok".
+        if (isLoggedOutUrl(page.url(), check))
+            return 'expired';
+        if (check.loggedInSelector) {
+            throw new Error(`${profile.sessionCheckPath} neither showed \`${check.loggedInSelector}\` nor went to ${check.loggedOutUrl} ` +
+                `within ${check.timeoutMs} ms, so the session could not be checked. Fix "sessionCheck" in profiles.yaml.`);
+        }
+        return 'ok';
     }
     finally {
         await context.close();
     }
 }
+/** The first signal that arrives wins; null when every one of them times out. */
+async function firstSignal(page, check) {
+    const timeout = check.timeoutMs;
+    const signals = [
+        page
+            .waitForURL((url) => isLoggedOutUrl(url.href, check), { timeout, waitUntil: 'commit' })
+            .then(() => 'expired'),
+    ];
+    if (check.loggedOutSelector) {
+        signals.push(page
+            .waitForSelector(check.loggedOutSelector, { state: 'visible', timeout })
+            .then(() => 'expired'));
+    }
+    if (check.loggedInSelector) {
+        signals.push(page.waitForSelector(check.loggedInSelector, { state: 'visible', timeout }).then(() => 'ok'));
+    }
+    try {
+        return await Promise.any(signals);
+    }
+    catch {
+        // Every signal timed out: the caller decides what an inconclusive page means.
+        return null;
+    }
+}
 export function parseNotLoggedIn(value = process.env[NOT_LOGGED_IN_ENV]) {
     const result = new Map();
     for (const entry of (value ?? '').split(',').filter(Boolean)) {

package/dist/lib/targets.d.ts

@@ -1,21 +1,13 @@
+import { type CaseTargetCard } from './case-doc.js';
 /**
  * An assertion target card: the exact image, text, file or place that a check looks at, written in the case under
  * `## Targets` as `### T<n> <name>` with `- What:`, `- Where:`, `- Identified by:` and `- Reference <profile-id>:` bullets.
+ * Parsing lives in `lib/case-doc.ts` (pure), so the web panel reads the same cards.
  */
-export interface TargetCard {
-    /** `T1`, `T2`, ... */
-    id: string;
-    name: string;
-    /** Field name (lower case, e.g. `what`, `where`, `identified by`, `not`, `ready when`, `kind`) to its text. */
-    fields: Record<string, string>;
-    /** `- Reference <profile-id>: <path>` bullets, keyed by what is written after `Reference`. */
-    references: Record<string, string>;
-    /** The card still has an open `🚫 TODO [blocking]` block: the target is not settled and no check may be built on it. */
-    blocking: boolean;
-}
+export type TargetCard = CaseTargetCard;
 export declare const TARGET_REF: RegExp;
-export declare const REQUIRED_FIELDS: readonly ['what', 'where', 'identified by'];
-export declare function parseTargets(text: string): TargetCard[];
+export declare const REQUIRED_FIELDS: readonly ["what", "where", "identified by"];
+export declare const parseTargets: (text: string) => TargetCard[];
 export declare const readCaseText: (id: string) => string;
 /** The target ids that a text mentions as `[T1]`. */
 export declare const targetRefsIn: (text: string) => string[];

package/dist/lib/targets.js

@@ -1,35 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { caseSectionText, parseTargetCards, TARGET_REQUIRED_FIELDS } from './case-doc.js';
 import { CASES_DIR } from './paths.js';
 export const TARGET_REF = /\[(T\d+)\]/g;
-export const REQUIRED_FIELDS = ['what', 'where', 'identified by'];
-const section = (text, name) => new RegExp(`^## ${name}\\s*$([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, 'm').exec(text)?.[1] ?? '';
-export function parseTargets(text) {
-    const body = section(text, 'Targets');
-    const cards = [];
-    const parts = body.split(/^### /m).slice(1);
-    for (const part of parts) {
-        const [heading, ...lines] = part.split('\n');
-        const head = /^(T\d+)\b[\s:.-]*(.*)$/.exec(heading.trim());
-        if (!head)
-            continue;
-        const card = { id: head[1], name: head[2], fields: {}, references: {}, blocking: false };
-        for (const line of lines) {
-            if (/^\s*-\s*🚫 TODO \[blocking\]/.test(line))
-                card.blocking = true;
-            const reference = /^-\s+Reference\s+([^:]+):\s*(.*)$/.exec(line);
-            if (reference) {
-                card.references[reference[1].trim()] = reference[2].trim();
-                continue;
-            }
-            const field = /^-\s+([A-Za-z][A-Za-z ]*?):\s*(.*)$/.exec(line);
-            if (field)
-                card.fields[field[1].trim().toLowerCase()] = field[2].trim();
-        }
-        cards.push(card);
-    }
-    return cards;
-}
+export const REQUIRED_FIELDS = TARGET_REQUIRED_FIELDS;
+export const parseTargets = (text) => parseTargetCards(text);
 export const readCaseText = (id) => fs.readFileSync(path.join(CASES_DIR, `${id}.md`), 'utf8');
 /** The target ids that a text mentions as `[T1]`. */
 export const targetRefsIn = (text) => [...new Set([...text.matchAll(TARGET_REF)].map((match) => match[1]))];
@@ -38,7 +13,7 @@ export const NEEDS_TARGET = /\b(logo|image|icon|screenshot|snapshot|pdf|download
 export function checksNeedingTarget(text) {
     const found = [];
     for (const name of ['Expected', 'Visual checks']) {
-        for (const line of section(text, name).split('\n')) {
+        for (const line of caseSectionText(text, name).split('\n')) {
             // A bullet that is only a question or an answer is part of a TODO block, not a check.
             if (!/^\s*-\s/.test(line) || /TODO|Answer:/.test(line))
                 continue;

package/dist/lib/values.js

@@ -1,14 +1,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parse } from 'yaml';
+import { caseSectionText } from './case-doc.js';
 import { CASES_DIR } from './paths.js';
 import { loadProfiles } from './profiles.js';
-const section = (text, name) => new RegExp(`^## ${name}\\s*$([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, 'm').exec(text)?.[1] ?? '';
 const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const caseFile = (caseId) => path.join(CASES_DIR, `${caseId}.md`);
 /** Parses and validates the `## Values` block. Throws an Error that starts with `label` and says what to fix. */
 export function parseCaseValues(text, label = 'case document') {
-    const body = section(text, 'Values').trim();
+    const body = caseSectionText(text, 'Values').trim();
     if (body === '')
         return {};
     const block = /```ya?ml\r?\n([\s\S]*?)```/i.exec(body);

package/dist/scripts/build.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { COPIED_SCRIPTS } from '../lib/build-artifacts.js';
 import { commandScript } from '../lib/node-cli.js';
 import { FRAMEWORK_ROOT } from '../lib/paths.js';
 // Compiles the framework to `dist/`: JavaScript and type declarations that Node and Playwright can load from a
@@ -12,7 +13,7 @@ const result = spawnSync(process.execPath, [tsc, '-p', path.join(FRAMEWORK_ROOT,
 });
 if ((result.status ?? 1) !== 0)
     process.exit(result.status ?? 1);
-for (const file of ['go.mjs', 'heal-evidence.mjs']) {
+for (const file of COPIED_SCRIPTS) {
     const from = path.join(FRAMEWORK_ROOT, 'scripts', file);
     const to = path.join(FRAMEWORK_ROOT, 'dist', 'scripts', file);
     fs.mkdirSync(path.dirname(to), { recursive: true });

package/dist/scripts/check-cases.js

@@ -1,18 +1,82 @@
 import fs from 'node:fs';
 import { CASES_DIR } from '../lib/paths.js';
 import { listCaseFileIds, readCaseMeta } from '../lib/cases.js';
+import { parseCaseDocument } from '../lib/case-doc.js';
 import path from 'node:path';
 import { ROOT } from '../lib/paths.js';
 import { checksNeedingTarget, parseTargets, readCaseText, REQUIRED_FIELDS, targetRefsIn } from '../lib/targets.js';
 import { parseCaseValues } from '../lib/values.js';
-/** Step numbers of the lines marked `[input]` or `[writes]` in "## Steps" (a person does them), and the numbers that "## Inputs" has a bullet for. */
+/** Step numbers of the lines marked `[input]` or `[writes]` in "## Steps" (a person does them), and the numbers that have a `- Recipe:` line under them (or an old "## Inputs" line). */
 function inputSteps(id) {
-    const text = fs.readFileSync(path.join(CASES_DIR, `${id}.md`), 'utf8');
-    const section = (name) => new RegExp(`^## ${name}\\s*$([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, 'm').exec(text)?.[1] ?? '';
-    const marked = [...section('Steps').matchAll(/^(\d+)\.\s.*\[(?:input|writes)\]/gm)].map((match) => Number(match[1]));
-    const recorded = [...section('Inputs').matchAll(/^- Step (\d+)\b/gm)].map((match) => Number(match[1]));
+    const doc = parseCaseDocument(fs.readFileSync(path.join(CASES_DIR, `${id}.md`), 'utf8'));
+    const marked = doc.steps
+        .filter((step) => step.tags.includes('input') || step.tags.includes('writes'))
+        .map((step) => step.number);
+    const recorded = [
+        ...doc.steps.flatMap((step) => step.recipes.map(() => step.number)),
+        ...doc.inputs.map((input) => input.step).filter((step) => step !== null),
+    ];
     return { marked, recorded };
 }
+/**
+ * Warnings about the question blocks and the recipe lines of a case: a block nobody can answer, an answer that is not
+ * the last line (so the agent cannot tell what it belongs to), a question with no text to keep, a nesting that Markdown
+ * will not render inside its step, and a recipe under a step that is not tagged (all `warn`: old cases keep working).
+ */
+function questionProblems(id) {
+    const doc = parseCaseDocument(fs.readFileSync(path.join(CASES_DIR, `${id}.md`), 'utf8'));
+    const warnings = [];
+    for (const question of doc.questions) {
+        if (!question.hasAnswerLine) {
+            warnings.push(`the question on line ${question.line} has no "✍️ Answer:" line; add one so it can be answered in place`);
+        }
+        else if (question.answerLine !== question.lastLine) {
+            warnings.push(`the "✍️ Answer:" line of the question on line ${question.line} is not the last line of its block`);
+        }
+        if (!question.parent) {
+            warnings.push(`the question on line ${question.line} has no text above it: accepting it would delete a claim nobody sees`);
+            continue;
+        }
+        const step = doc.steps.find((candidate) => candidate.line === question.parent?.line);
+        if (step && question.indent < 4) {
+            warnings.push(`the question on line ${question.line} is indented by ${question.indent} space(s) under step ${step.number}; 4 renders it inside the step`);
+        }
+    }
+    for (const step of doc.steps) {
+        if (step.recipes.length === 0)
+            continue;
+        if (!step.tags.includes('input') && !step.tags.includes('writes')) {
+            warnings.push(`step ${step.number} has a "- Recipe:" line but is not tagged [input] or [writes]`);
+        }
+    }
+    for (const input of doc.inputs) {
+        if (input.step === null)
+            continue;
+        const step = doc.steps.find((candidate) => candidate.number === input.step);
+        if (!step) {
+            warnings.push(`"## Inputs" line ${input.line} (old format) belongs to step ${input.step}, which this case does not have`);
+        }
+        else if (!step.tags.includes('input') && !step.tags.includes('writes')) {
+            warnings.push(`"## Inputs" line ${input.line} (old format) belongs to step ${input.step}, which is not tagged [input] or [writes]`);
+        }
+    }
+    return warnings;
+}
+/**
+ * Warnings for the old layout. `## Data` and `## Inputs` are deprecated: the one-sentence summary belongs in
+ * `writes-note`, the cleanup in steps, and a person's recipe under its step. Cases keep working, so this never fails.
+ */
+function formatProblems(id) {
+    const doc = parseCaseDocument(fs.readFileSync(path.join(CASES_DIR, `${id}.md`), 'utf8'));
+    const warnings = [];
+    if (doc.sections.some((section) => section.name === 'Data')) {
+        warnings.push('has a "## Data" section, which is no longer part of the case format: move it into "writes-note", the delete steps or "## Notes"');
+    }
+    if (doc.inputs.length > 0) {
+        warnings.push('uses the old "## Inputs" section: move each line under its step as "- Recipe (phase): ..."');
+    }
+    return warnings;
+}
 /** Problems with the target cards (`## Targets`) of a case: `fail` stops, `warn` is what `/explore-case` still has to settle. */
 function targetProblems(id) {
     const text = readCaseText(id);
@@ -70,8 +134,12 @@ for (const id of ids) {
         const { marked, recorded } = inputSteps(id);
         const missing = marked.filter((step) => !recorded.includes(step));
         if (missing.length > 0) {
-            console.log(`warn ${id}: step ${missing.join(', ')} is marked [input] or [writes] but has no recipe under "## Inputs" (run /explore-case --attended)`);
+            console.log(`warn ${id}: step ${missing.join(', ')} is marked [input] or [writes] but has no "- Recipe:" line under it (run /explore-case --attended)`);
         }
+        for (const message of formatProblems(id))
+            console.log(`warn ${id}: ${message}`);
+        for (const message of questionProblems(id))
+            console.log(`warn ${id}: ${message}`);
     }
     catch (error) {
         problems++;

package/dist/scripts/doctor.js

@@ -2,7 +2,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { loadProfiles, listEnvs, PROFILES_FILE } from '../lib/profiles.js';
 import { FRAMEWORK_ROOT, ROOT, SKILLS_DIR } from '../lib/paths.js';
+import { spawnTarget } from '../lib/command.js';
 import { GENERATED, frameworkPath, frameworkVersion, renderTemplate } from './init.js';
+import { builtFile, COPIED_SCRIPTS } from '../lib/build-artifacts.js';
 /**
  * Checks that a workspace is complete and consistent with the framework it points at. It never writes anything.
  * Errors exit with 1; warnings do not.
@@ -26,6 +28,45 @@ function nonNegotiableRules() {
     }
     return ids;
 }
+/** Every rule id the framework baseline defines (`F1`..`F10`), so a project cannot name one that does not exist. */
+function frameworkRuleIds() {
+    const ids = new Set();
+    for (const line of (read(path.join(FRAMEWORK_ROOT, 'AGENTS.md')) ?? '').split('\n')) {
+        const match = /^- \*\*(F\d+)\b/.exec(line.trim());
+        if (match)
+            ids.add(match[1]);
+    }
+    return ids;
+}
+/**
+ * The framework sources that `pnpm build` compiles into `dist/` and are older than it, or missing from it. Only the
+ * framework repository has those sources; an installed package ships `dist/` alone, so the list is empty there.
+ */
+function staleDistFiles() {
+    const stale = [];
+    const compare = (source) => {
+        const compiled = path.join(FRAMEWORK_ROOT, builtFile(source));
+        if (!fs.existsSync(compiled))
+            stale.push(`${builtFile(source)} is missing`);
+        else if (fs.statSync(path.join(FRAMEWORK_ROOT, source)).mtimeMs > fs.statSync(compiled).mtimeMs)
+            stale.push(source);
+    };
+    const walk = (dir) => {
+        if (!fs.existsSync(path.join(FRAMEWORK_ROOT, dir)))
+            return;
+        for (const entry of fs.readdirSync(path.join(FRAMEWORK_ROOT, dir), { withFileTypes: true })) {
+            const source = `${dir}/${entry.name}`;
+            if (entry.isDirectory())
+                walk(source);
+            // The plain `.mjs` tools are copied as they are; every other file is TypeScript and becomes JavaScript.
+            else if (source.endsWith('.ts') || COPIED_SCRIPTS.includes(entry.name))
+                compare(source);
+        }
+    };
+    walk('lib');
+    walk('scripts');
+    return stale;
+}
 export async function main(args) {
     if (args.includes('--help')) {
         console.log('Usage: pnpm asrun doctor');
@@ -66,6 +107,14 @@ export async function main(args) {
         }
     }
     const framework = recordedPath ?? actualPath;
+    // The framework repository compiles itself into `dist/`, and `templates/playwright.config.ts` makes every workspace
+    // load the config from there. A build older than the sources therefore keeps runs on the previous code.
+    const stale = staleDistFiles();
+    if (stale.length > 0) {
+        const shown = stale.slice(0, 3).join(', ');
+        warnings.push(`dist/ is out of date (${shown}${stale.length > 3 ? `, and ${stale.length - 3} more` : ''}): run "pnpm build". ` +
+            'Workspaces load playwright.config.ts from dist, so they keep the previous configuration until then.');
+    }
     // Profiles: they are the only source of environments, and a broken file stops every command.
     try {
         const profiles = loadProfiles();
@@ -124,7 +173,19 @@ export async function main(args) {
     const skillsDir = path.join(ROOT, '.claude', 'skills');
     const overrides = fs.existsSync(skillsDir) ? fs.readdirSync(skillsDir).filter((name) => name.endsWith('.md')) : [];
     facts.push(`skills:    ${SKILLS.join(', ')}${overrides.length > 0 ? ` (project overrides: ${overrides.map((name) => name.replace(/\.md$/, '')).join(', ')})` : ''}`);
-    // Project rules may only narrow the baseline, never a rule marked [non-negotiable].
+    for (const name of overrides) {
+        const text = read(path.join(skillsDir, name)) ?? '';
+        // An override refines a skill's procedure; redefining a safety rule is never an override.
+        if (/^\s*[-*]?\s*\*{0,2}F[1-6]\b/m.test(text)) {
+            errors.push(`.claude/skills/${name} redefines a safety rule (F1–F6); project rules never change those.`);
+        }
+        const frameworkSkill = read(path.join(SKILLS_DIR, name.replace(/\.md$/, ''), 'SKILL.md'));
+        if (frameworkSkill !== null && text.trim() === frameworkSkill.trim()) {
+            warnings.push(`.claude/skills/${name} is a copy of the framework skill; delete it, or it will never see an update.`);
+        }
+    }
+    // Project rules: a project may narrow or replace a baseline rule, never one of F1–F6. Rows are
+    // `| <id> | <the project's rule> | <narrows|replaces> |`.
     const agents = read(path.join(ROOT, 'AGENTS.md'));
     if (agents === null) {
         warnings.push('AGENTS.md is missing: run "pnpm asrun init" and fill in the project facts.');
@@ -134,11 +195,29 @@ export async function main(args) {
             errors.push(`AGENTS.md does not point at the framework baseline (${framework}/AGENTS.md).`);
         }
         const locked = nonNegotiableRules();
+        const known = frameworkRuleIds();
+        let fenced = false;
         for (const line of agents.split('\n')) {
-            const match = /^\|\s*(F\d+)\s*\|/.exec(line.trim());
-            if (match && locked.has(match[1])) {
-                errors.push(`AGENTS.md narrows ${match[1]}, which the framework marks [non-negotiable].`);
+            // A fenced block is documentation (an example table), not the project's rules.
+            if (line.trim().startsWith('```')) {
+                fenced = !fenced;
+                continue;
             }
+            if (fenced)
+                continue;
+            const cells = line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((cell) => cell.trim());
+            if (!/^F\d+$/.test(cells[0]))
+                continue;
+            const id = cells[0];
+            const effect = (cells[2] ?? '').toLowerCase();
+            if (!known.has(id))
+                errors.push(`AGENTS.md names ${id}, which is not a rule of the framework baseline.`);
+            else if (locked.has(id))
+                errors.push(`AGENTS.md changes ${id}, which the framework marks [non-negotiable].`);
+            else if (effect === '')
+                warnings.push(`AGENTS.md rule ${id} has no Effect column: add "narrows" or "replaces" (a table written before 0.3.0 predates it).`);
+            else if (effect !== 'narrows' && effect !== 'replaces')
+                errors.push(`AGENTS.md rule ${id} has Effect "${cells[2]}"; use "narrows" or "replaces".`);
         }
     }
     // The install and the commands the docs use.
@@ -168,6 +247,38 @@ export async function main(args) {
         if (scripts !== null && !scripts[name])
             warnings.push(`package.json has no "${name}" script: run "pnpm asrun init".`);
     }
+    // The agent CLIs the AI commands start. Only those commands need one, so a missing one is a warning, not an error.
+    // Checked the way the web UI starts them, so a Windows `.cmd` shim is reported instead of failing later.
+    const tools = ['claude', 'opencode']
+        .map((name) => ({ name, target: spawnTarget(name) }))
+        .filter((tool) => tool.target !== null);
+    if (tools.length === 0) {
+        warnings.push('Neither "claude" (Claude Code) nor "opencode" was found on PATH: the AI commands (make cases, explore a case, generate a spec) cannot start.');
+    }
+    else {
+        facts.push(`ai tools:  ${tools
+            .map((tool) => `${tool.name} -> ${tool.target.path}${tool.target.throughShell ? ' (through cmd.exe)' : ''}`)
+            .join(', ')}`);
+    }
+    // The MCP servers the AI commands explore with: OpenCode reads only `opencode.jsonc`, Claude Code only `.mcp.json`.
+    for (const [file, tool] of [
+        ['.mcp.json', 'Claude Code'],
+        ['opencode.jsonc', 'OpenCode'],
+    ]) {
+        const text = read(path.join(ROOT, file));
+        if (text === null) {
+            warnings.push(`${file} is missing: ${tool} has no "playwright-test" MCP server. Run "pnpm asrun init".`);
+            continue;
+        }
+        if (!text.includes('playwright-test')) {
+            warnings.push(`${file} does not define the "playwright-test" MCP server: run "pnpm asrun init --force ${file}".`);
+            continue;
+        }
+        const command = /"command"\s*:\s*(?:\[\s*)?"([^"]*playwright[^"]*)"/.exec(text)?.[1];
+        if (command !== undefined && !fs.existsSync(path.resolve(ROOT, command)) && !fs.existsSync(path.resolve(ROOT, `${command}.cmd`))) {
+            warnings.push(`${file} starts the MCP server with "${command}", which does not exist: run "pnpm asrun init --force ${file}".`);
+        }
+    }
     const settings = read(path.join(ROOT, '.claude', 'settings.json'));
     if (settings === null) {
         warnings.push('.claude/settings.json is missing: run "pnpm asrun init" (Claude Code needs its sandbox exclusions for pnpm asrun).');

package/dist/scripts/explore.js

@@ -51,4 +51,25 @@ context.on('page', watchPage);
 const page = await context.newPage();
 await page.goto(new URL(pathname, profile.baseURL).href);
 console.log(`Opened ${profileLabel(profile)}. Close the browser window to exit.`);
-await new Promise((resolve) => browser.on('disconnected', resolve));
+// Chromium keeps its process alive after the last window is closed, so waiting for `disconnected` alone
+// never finishes. Closing the last window does close its pages, and that is the signal to stop.
+await new Promise((resolve) => {
+    let settled = false;
+    const done = () => {
+        if (settled)
+            return;
+        settled = true;
+        resolve();
+    };
+    browser.on('disconnected', done);
+    context.on('close', done);
+    const watch = (open) => open.on('close', () => {
+        if (context.pages().length === 0)
+            done();
+    });
+    context.pages().forEach(watch);
+    context.on('page', watch);
+});
+// The window is gone, but its browser process can still be running: end it so no orphan process is left.
+await browser.close().catch(() => { });
+console.log('Browser closed.');