@event4u/agent-config 14.11.0 → 14.13.0

package/src/config/web-launch-readiness.json

@@ -0,0 +1,188 @@
+{
+  "_comment": "Site-type axis for the web-launch-readiness skill (road-to-web-launch-readiness 0.2). The design directive this file exists to enforce is CONDITIONAL, NOT FLAT: a check that applies everywhere is a check that gets ignored somewhere. Every entry declares which site types it applies to, so a SaaS app is never asked for opening hours and a docs site is never asked for a cookie banner it does not set. REGISTERED BEFORE ANY SKILL CODE EXISTS, which is the point of Phase 0: the axis is a decision, and deciding it after writing the checks would let the checks pick their own scope. Nothing reads this file yet -- the skill is gated behind b-estate-decision-web-launch.",
+  "schema_version": 1,
+  "registered_at": "2026-08-25",
+  "owner": "maintainer",
+  "review_by": "2027-08-25",
+  "site_types": {
+    "_comment": "The closed enum. A check may not name a type outside it, and a type carries no checks until one lists it -- so adding a type is inert until a check opts in, and removing one is caught by the schema test rather than silently emptying a check's scope.",
+    "values": [
+      "local-business",
+      "marketing-site",
+      "saas-app",
+      "docs",
+      "internal-tool"
+    ]
+  },
+  "tiers": {
+    "_comment": "Report order, and it is the output contract rather than a label: critical first, situational last. A finding's tier is a property of the FINDING, not of the reader's patience -- a staging noindex on a production marketing site is critical whether or not the reader has time for it.",
+    "values": [
+      "critical",
+      "high",
+      "medium",
+      "situational"
+    ]
+  },
+  "checks": [
+    {
+      "id": "staging-noindex-leftover",
+      "title": "A staging `noindex` or `robots.txt` disallow survived into production",
+      "applies_to": [
+        "local-business",
+        "marketing-site",
+        "saas-app",
+        "docs"
+      ],
+      "tier": "critical",
+      "why": "The defect class with ZERO coverage in the estate (G0: `robots` 0 files, `noindex` 0 files) and the highest cost: the site ships, works, looks correct, and is invisible to search. Nothing in the tree looks for it today.",
+      "remediation": "Remove the `noindex` meta tag and the blanket `Disallow: /` from the production build; keep them behind the staging environment's own config rather than in shared source.",
+      "verification": "`curl -sI <prod-url> | grep -i x-robots-tag` returns nothing, `curl -s <prod-url>/robots.txt` carries no blanket disallow, and the rendered HTML has no `noindex` meta."
+    },
+    {
+      "id": "https-enforcement",
+      "title": "HTTP is redirected to HTTPS and no asset is loaded over plain HTTP",
+      "applies_to": [
+        "local-business",
+        "marketing-site",
+        "saas-app",
+        "docs"
+      ],
+      "tier": "critical",
+      "why": "A mixed-content asset silently breaks the padlock and, on a form page, ships a credential over plaintext. Browsers block some of it and load the rest, so the page LOOKS fine while the guarantee is gone -- which is why this is critical rather than high.",
+      "remediation": "Serve every asset over https:// or protocol-relative paths, and redirect http:// at the edge. Never hard-code an http:// origin you control.",
+      "verification": "`curl -sI http://<prod-host>/` returns a 301/308 to https, and the browser console shows no mixed-content warning on the heaviest page."
+    },
+    {
+      "id": "custom-error-route",
+      "title": "A custom 404 route exists and is reachable",
+      "applies_to": [
+        "local-business",
+        "marketing-site",
+        "saas-app",
+        "docs"
+      ],
+      "tier": "high",
+      "why": "A framework default error page leaks stack shape and loses the visitor. `404` matches 19 files in the estate, all HTTP-status tables -- none is a launch check.",
+      "remediation": "Add the framework's custom 404 route and give it a link back into the site.",
+      "verification": "`curl -s -o /dev/null -w '%{http_code}' <prod-url>/<random-path>` returns 404 and the body is the custom page, not the framework default."
+    },
+    {
+      "id": "per-route-metadata",
+      "title": "Every indexable route carries a title and a meta description",
+      "applies_to": [
+        "local-business",
+        "marketing-site",
+        "docs"
+      ],
+      "tier": "high",
+      "why": "`meta description` matches 0 files. Excluded for `saas-app` and `internal-tool` on purpose: an authenticated app's routes are not indexed, so per-route descriptions are work with no consumer.",
+      "remediation": "Add title and description to each route's metadata export; a shared default is a fallback, not a per-route value.",
+      "verification": "Fetch each route in the sitemap and assert a non-empty, non-duplicated title and description."
+    },
+    {
+      "id": "image-alternative-text",
+      "title": "Content images carry alternative text",
+      "applies_to": [
+        "local-business",
+        "marketing-site",
+        "saas-app",
+        "docs",
+        "internal-tool"
+      ],
+      "tier": "high",
+      "why": "The one check that applies to every type, including internal tools -- an internal user with a screen reader is still a user. `alt text` matches 7 files, all accessibility prose rather than a launch check.",
+      "remediation": "Add `alt` to content images; decorative images take `alt=\"\"` explicitly rather than being left without the attribute.",
+      "verification": "Parse the rendered HTML and assert every `<img>` has an `alt` attribute, empty or not."
+    },
+    {
+      "id": "document-head-basics",
+      "title": "Every page declares lang, charset and viewport",
+      "applies_to": [
+        "local-business",
+        "marketing-site",
+        "saas-app",
+        "docs",
+        "internal-tool"
+      ],
+      "tier": "high",
+      "why": "A missing `lang` makes a screen reader guess the pronunciation of the whole page; a missing viewport makes a phone render a desktop layout at 320px. Both are one line, both are invisible on the developer's machine, and both are the kind of default a framework template silently drops when a page is hand-written.",
+      "remediation": "`<html lang=\"..\">`, `<meta charset=\"utf-8\">` and `<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">` in the shared layout, not per page.",
+      "verification": "View source on two unrelated routes and confirm all three are present on both -- one route proves the layout, two prove it is the layout and not a copy."
+    },
+    {
+      "id": "canonical-and-sitemap-coherence",
+      "title": "Canonical URLs, sitemap and robots.txt agree with each other",
+      "applies_to": [
+        "local-business",
+        "marketing-site",
+        "docs"
+      ],
+      "tier": "medium",
+      "why": "Three sources that can disagree silently: a sitemap listing a route whose canonical points elsewhere, or a robots disallow on a route the sitemap advertises. Note `canonical` matches 115 files in this estate in a completely different sense (\"the canonical rule\"), so its count is NOT coverage evidence.",
+      "remediation": "Make the canonical the same URL the sitemap lists; remove sitemap entries that robots.txt disallows.",
+      "verification": "For each sitemap URL, fetch it and assert the canonical equals the sitemap entry and robots.txt does not disallow it."
+    },
+    {
+      "id": "required-legal-pages",
+      "title": "The legal pages the jurisdiction requires exist and are linked",
+      "applies_to": [
+        "local-business",
+        "marketing-site",
+        "saas-app"
+      ],
+      "tier": "situational",
+      "why": "SITUATIONAL because the requirement is jurisdictional, not universal: a German commercial site needs an Impressum, a US one does not. The skill reports what is missing for the declared region and does not assert a legal conclusion -- that is the domain-safety-disclaimer boundary, not this file's.",
+      "remediation": "Add the pages the declared region requires and link them from the footer of every page.",
+      "verification": "Assert each declared-required page returns 200 and is reachable from the home page in one click."
+    },
+    {
+      "id": "analytics-and-consent-wiring",
+      "title": "Analytics fires only after consent, where consent is required",
+      "applies_to": [
+        "local-business",
+        "marketing-site",
+        "saas-app"
+      ],
+      "tier": "situational",
+      "why": "Also jurisdictional, and the failure is asymmetric: analytics that never fires costs data, analytics that fires before consent costs a regulatory exposure.",
+      "remediation": "Gate the analytics snippet behind the consent state; do not load it on first paint.",
+      "verification": "Load the page with consent declined and assert no request to the analytics origin."
+    }
+  ],
+  "not_in_scope": {
+    "_comment": "Named so a later contributor does not add them by analogy. Performance budgets and Lighthouse scoring are a different instrument with a different failure mode (a score is a gradient, these checks are binary), and `lighthouse` matching 0 files is NOT an argument for adding it here. Accessibility beyond alt text belongs to accessibility-auditor, which already exists and does it properly.",
+    "items": [
+      "performance budgets",
+      "lighthouse scoring",
+      "full WCAG audit",
+      "SEO keyword strategy"
+    ]
+  },
+  "no_import_decision": {
+    "_comment": "Step 0.3, recorded HERE rather than in the skill body, and the relocation is a correction the step needs rather than a liberty taken. 0.3 sits in Phase 0, whose Exit condition reads \"zero skill code written\" -- so its verify line (\"the decision is written in the skill's own body\") names an artefact its own phase forbids. The decision is what the step is about; it is recorded in the earliest durable place that exists, and the skill body restates it at 2.1 when there is a body.",
+    "decision": "no-import",
+    "decided_at": "2026-08-25",
+    "rule": "The external corpus is a STUDY OBJECT and a per-defect harvest source. Its rule set is not imported. Rules enter ONE AT A TIME, each against a named defect, each carrying its own remediation and verification.",
+    "why": "An imported rule set arrives with its authors' assumptions about site type, jurisdiction and stack, and none of those is checked on arrival. The failure is silent: the skill grows to N checks, each individually plausible, and the conditional axis this file exists to enforce is the first thing a bulk import flattens. One-at-a-time keeps the axis honest because every entry has to answer `applies_to` before it lands.",
+    "ceiling": 50,
+    "ceiling_enforced_by": "tests/scripts/web_launch_readiness_config.test.ts asserts checks.length < 50. Currently 7."
+  },
+  "regions": {
+    "_comment": "Region axis (road-to-web-launch-readiness 2.3). Separate from site_types because it answers a different question: site_types decides WHETHER a check applies, regions decides HOW SEVERELY. A DE-targeted site owes Impressum and Datenschutz by law (TMG 5 / DSGVO Art. 13), so `required-legal-pages` is critical there and situational elsewhere -- the same check, a different tier. Modelled as a tier ESCALATION rather than as a second applies_to list, because a legal page is not more or less applicable in Germany, it is more or less optional.",
+    "values": [
+      "de",
+      "eu",
+      "us",
+      "unspecified"
+    ],
+    "default": "unspecified",
+    "escalations": [
+      {
+        "check": "required-legal-pages",
+        "region": "de",
+        "to": "critical",
+        "why": "TMG 5 obliges an Impressum and DSGVO Art. 13 a Datenschutzerklaerung for a DE-targeted commercial site. Abmahnung risk is real and immediate, which is what separates critical from situational here."
+      }
+    ]
+  }
+}

package/src/install/claudeRuleRewrite.ts

@@ -0,0 +1,288 @@
+/**
+ * Rewrite installed Claude Code rule files into host form, in place.
+ *
+ * ## The gap this closes
+ *
+ * `condense.ts::_emit_claude_rule` shapes a rule for Claude Code — it emits
+ * `paths:` and nothing else, because `paths:` is the one activation key the
+ * probed contract records this host as reading. It runs on the MAINTAINER
+ * projection path only. The installer's deploy loop copies
+ * `dist/agent-src/rules/` verbatim into the host anchor
+ * (`_copy_dir_dereferencing_symlinks`, `install.ts`), so an installed
+ * `~/.claude/rules/` receives the SOURCE form: agent-config's own frontmatter
+ * vocabulary (`type`, `tier`, `triggers`, …), none of which this host reads.
+ *
+ * Measured on a real install, 2026-08-30, before this module existed:
+ *
+ * ```
+ * files 104 · declaring paths: 0
+ * ⚠️  diverges from the source verdict (4 scoped)
+ * ```
+ *
+ * The consequence is not cosmetic. On Claude Code `paths:` is EXCLUSIVE — with
+ * it a rule loads on a path match, without it the rule loads unconditionally —
+ * so three rules the emitter classifies path-only arrived in every session
+ * instead of on file contact.
+ *
+ * ## Why it lives here and not in `condense.ts`
+ *
+ * Same reasoning `claudePathsPlan.ts` beside it records: this is
+ * host-activation-key logic on the INSTALL side, and `condense.ts` is a
+ * multi-thousand-line orchestrator already past the source-size ceiling. Both
+ * of this module's inputs are already installer-side — `_claude_paths_plan`
+ * from `claudePathsPlan.ts` and `parseFrontmatter` from `ruleInScope.ts` — so
+ * nothing here reaches back into the projection graph, and the installer bundle
+ * gains no dependency on it.
+ *
+ * The two emitters are held together by a test rather than by a shared call:
+ * `tests/install/claude_rule_rewrite.test.ts` asserts, over every rule in
+ * `src/rules/`, that this module's plan is byte-identical to the one
+ * `condense.ts` emits. A divergence fails there rather than silently shipping
+ * two different activation surfaces to the same host.
+ *
+ * Side-effect-free apart from the writes it is asked to make. No CLI entry, no
+ * `process.exit`.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { _claude_paths_plan } from './claudePathsPlan.js';
+import { parseFrontmatter } from './ruleInScope.js';
+
+/**
+ * Frontmatter keys the rewrite must carry across, and why each one.
+ *
+ * `_inject_package_tag` (install.ts) writes these during the copy that runs
+ * immediately BEFORE this rewrite. `reap_tagged_orphans` then matches on the
+ * literal `package:` line — its own docblock calls itself "the only path with
+ * ownership proof independent of inventory history" — and doctor's stale-orphan
+ * check reads the same tag.
+ *
+ * A rewrite that rebuilt each file from the activation plan alone therefore
+ * DELETED the reaper's only evidence: zero files under the host anchor would
+ * carry the tag, the marker-based reaper would be dead for that subtree, and
+ * doctor would report `ok` there permanently. Found by the completion review of
+ * 2026-08-30, with a fixture: a tagged orphan was reaped before the rewrite and
+ * invisible after it.
+ *
+ * So the host form is activation keys PLUS these, and the two concerns are kept
+ * apart on purpose — {@link renderClaudeRule} stays activation-only so it can go
+ * on being compared byte-for-byte against the projection emitter, which never
+ * sees an install-time tag.
+ */
+export const PRESERVED_KEYS: readonly string[] = ['package', 'source_path'];
+
+export interface ClaudeRuleRewriteResult {
+    /** Files read and rewritten. */
+    rewritten: number;
+    /** Basenames (without `.md`) that received a `paths:` block. */
+    scoped: string[];
+    /**
+     * Patterns the plan deliberately dropped, per file — surfaced rather than
+     * swallowed, because a dropped pattern silently widens a rule's activation
+     * from path-gated to unconditional.
+     */
+    dropped: { rule: string; pattern: string; reason: string }[];
+    /** Rules the rewrite could not write, with the reason. Never thrown. */
+    failed: { rule: string; reason: string }[];
+}
+
+/**
+ * Splice the ownership keys of `original` into the activation-only `rendered`.
+ *
+ * Raw lines are carried across verbatim rather than re-serialised, so a quoted
+ * or unusually-spaced value cannot drift on the way through — the reaper matches
+ * a literal.
+ */
+export function _withPreservedKeys(rendered: string, original: string): string {
+    const keep: string[] = [];
+    if (original.startsWith('---')) {
+        const end = original.indexOf('\n---', 3);
+        if (end !== -1) {
+            for (const line of original.slice(3, end).split('\n')) {
+                if (PRESERVED_KEYS.some((k) => line.startsWith(`${k}:`))) keep.push(line);
+            }
+        }
+    }
+    if (keep.length === 0) return rendered;
+    if (rendered.startsWith('---\n')) {
+        const end = rendered.indexOf('\n---', 3);
+        if (end !== -1) {
+            return rendered.slice(0, end) + '\n' + keep.join('\n') + rendered.slice(end);
+        }
+    }
+    // No activation block: the rule loads unconditionally and still needs its
+    // tag, so it gets a frontmatter block holding ONLY the ownership keys.
+    return ['---', ...keep, '---', '', rendered].join('\n');
+}
+
+/**
+ * Rewrite, then render the two operator-facing lines the installer prints.
+ *
+ * The reporting lives here rather than at the call site for the reason
+ * `claudePathsPlan.ts` records for itself: `install.ts` is thousands of lines
+ * past `check_source_size_budget`'s ceiling, where every added line counts as a
+ * violation, and that gate's convention is that the total moves down through
+ * extraction and never up through a baseline raise. So the caller gets one call
+ * and a list of strings.
+ */
+export function rewriteAndReport(
+    rulesDir: string,
+    quiet: boolean,
+    info: (m: string) => void,
+    warn: (m: string) => void,
+    wrappers?: { wrapped: readonly string[]; reserved: readonly string[] },
+): ClaudeRuleRewriteResult {
+    const result = rewriteClaudeRules(rulesDir);
+    // The flat-command wrapper report rides along rather than sitting at the
+    // call site: `install.ts` is thousands of lines past
+    // `check_source_size_budget`'s ceiling, and this module is the one place
+    // that already owns claude-code post-copy reporting. Moving it here is the
+    // reduction that pays for this feature's own lines — that gate's stated
+    // convention is that the total falls through extraction and never rises
+    // through a baseline edit. Messages are byte-identical to the originals.
+    if (wrappers && !quiet) {
+        if (wrappers.wrapped.length > 0) {
+            info(
+                `  claude-code: ${wrappers.wrapped.length} visible flat command(s) projected as ` +
+                    'skill wrappers (Claude Code flat-command discovery workaround)',
+            );
+        }
+        if (wrappers.reserved.length > 0) {
+            info(
+                `  claude-code: ${wrappers.reserved.length} flat command(s) withheld — name is a ` +
+                    `Claude Code built-in (${wrappers.reserved.join(', ')}); nested /cluster:sub ` +
+                    'commands remain available',
+            );
+        }
+    }
+    if (result.rewritten > 0 && !quiet) {
+        info(
+            `  claude-code: ${result.rewritten} rule(s) rewritten to host form; ` +
+                `${result.scoped.length} path-scoped (${result.scoped.join(', ') || 'none'})`,
+        );
+    }
+    // NOT one line per dropped pattern. Every mixed-trigger rule drops every
+    // pattern it has, by design and permanently, so the per-pattern loop emitted
+    // 19 stderr lines on every single install — unactionable by any consumer,
+    // surviving --quiet because `warn` writes unconditionally. This repository
+    // has already recorded its verdict on exactly that pattern elsewhere in the
+    // emitter. One counted line under --quiet's own guard; the detail stays in
+    // the returned struct for a caller that wants it.
+    if (result.dropped.length > 0 && !quiet) {
+        const rules = [...new Set(result.dropped.map((d) => d.rule))];
+        info(
+            `  claude-code: ${rules.length} rule(s) keep unconditional activation ` +
+                '(mixed path + keyword triggers; `paths:` is exclusive on this host)',
+        );
+    }
+    for (const f of result.failed) {
+        warn(`  claude-code: ${f.rule}: could not write host form — ${f.reason}`);
+    }
+    return result;
+}
+
+/** Python `str.rstrip()` with no args — mirrors `condense.ts::_pyRstrip`. */
+function pyRstrip(s: string): string {
+    return s.replace(/\s+$/u, '');
+}
+
+/** Mirrors `condense.ts::_yaml_scalar`. */
+function yamlScalar(value: string): string {
+    return JSON.stringify(value);
+}
+
+/**
+ * Render one rule's host form from its source text.
+ *
+ * Exported for the equivalence test. A rule with no path-shaped trigger gets
+ * NO frontmatter at all rather than an empty block the host would ignore —
+ * keys that do nothing are bytes in every session's standing context.
+ */
+export function renderClaudeRule(sourceText: string): {
+    text: string;
+    globs: string[];
+    dropped: { pattern: string; reason: string }[];
+} {
+    const [meta, body] = parseFrontmatter(sourceText);
+    const plan = _claude_paths_plan(meta);
+    const lines: string[] = [];
+    if (plan.globs.length > 0) {
+        lines.push('---', 'paths:');
+        for (const g of plan.globs) {
+            lines.push(`  - ${yamlScalar(g)}`);
+        }
+        lines.push('---', '');
+    }
+    lines.push(pyRstrip(body) + '\n');
+    return { text: lines.join('\n'), globs: plan.globs, dropped: plan.dropped };
+}
+
+/**
+ * Rewrite every `*.md` directly under `rulesDir` into Claude host form.
+ *
+ * Idempotent: a file already in host form parses to `{paths: [...]}`, which
+ * carries no `triggers:` key, so `_claude_paths_plan` returns no globs and the
+ * rewrite would DROP the block. That is why the already-rewritten case is
+ * detected and skipped rather than re-run — re-running is the silent-widening
+ * failure this module exists to fix, applied to its own output.
+ *
+ * Returns counts rather than printing. The caller owns the reporting surface.
+ */
+export function rewriteClaudeRules(rulesDir: string): ClaudeRuleRewriteResult {
+    const result: ClaudeRuleRewriteResult = { rewritten: 0, scoped: [], dropped: [], failed: [] };
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(rulesDir);
+    } catch {
+        return result;
+    }
+    for (const name of entries.filter((n) => n.endsWith('.md')).sort()) {
+        const full = path.join(rulesDir, name);
+        let stat: fs.Stats;
+        try {
+            stat = fs.lstatSync(full);
+        } catch {
+            continue;
+        }
+        // A symlink here is the legacy raw-md farm, not an installed copy.
+        // Rewriting through it would write into the projection source.
+        if (!stat.isFile() || stat.isSymbolicLink()) continue;
+
+        let text: string;
+        try {
+            text = fs.readFileSync(full, 'utf-8');
+        } catch {
+            continue;
+        }
+        const [meta] = parseFrontmatter(text);
+        // Already host form: `paths:` present and no source vocabulary left.
+        if (meta['paths'] !== undefined && meta['triggers'] === undefined) continue;
+
+        const rendered = renderClaudeRule(text);
+        const withOwnership = _withPreservedKeys(rendered.text, text);
+        if (withOwnership !== text) {
+            try {
+                fs.writeFileSync(full, withOwnership, 'utf-8');
+            } catch (e) {
+                // A single unwritable rule — a root-owned file left by an
+                // earlier `sudo` install — must not abort the whole install and
+                // skip every remaining tool, the inventory record, the lockfile
+                // correction and the fingerprint stamp. Report and continue.
+                result.failed.push({
+                    rule: name.slice(0, -3),
+                    reason: e instanceof Error ? e.message : String(e),
+                });
+                continue;
+            }
+            result.rewritten += 1;
+        }
+        const stem = name.slice(0, -3);
+        if (rendered.globs.length > 0) result.scoped.push(stem);
+        for (const d of rendered.dropped) {
+            result.dropped.push({ rule: stem, pattern: d.pattern, reason: d.reason });
+        }
+    }
+    return result;
+}

package/src/install/detect.ts

@@ -35,10 +35,16 @@ export const SETTINGS_FILE = '.agent-settings.yml';
 /**
  * Manifest files that, when present, count as a project-shape signal.
  *
- * Listed in the order they are most commonly canonical; detection
- * short-circuits on the first hit. `.git/` is intentionally absent —
- * monorepos, dotfile-git repos, and non-Git workspaces all break it
- * (ADR-007 D2).
+ * `.git/` is intentionally absent — monorepos, dotfile-git repos, and non-Git
+ * workspaces all break it (ADR-007 D2). **That clause is about the `.git/`
+ * signal and nothing else.** It used to be cited here for a second property as
+ * well — that detection "short-circuits on the first hit" — which ADR-007 D2
+ * does not state. The citation was corrected on 2026-08-26
+ * (road-to-internal-estate-fit 2.2), and the behaviour it described was
+ * corrected with it: `detectProjectShape` now returns EVERY detected manifest
+ * (2.1), so the order below is a reporting order rather than a tie-break, and
+ * a polyglot repository is described as what it is instead of as its first
+ * alphabetically-privileged half.
  */
 export const SCOPE_DETECT_MANIFESTS: readonly string[] = [
     'package.json',
@@ -127,10 +133,37 @@ export function scopeToTarget(scope: Scope): InstallTarget | null {
 }
 
 /** Project shape inferred from manifest presence. */
+export type ProjectKind =
+    | 'composer'
+    | 'npm'
+    | 'cargo'
+    | 'pyproject'
+    | 'go'
+    | 'ruby'
+    | 'unknown';
+
 export interface ProjectShape {
-    readonly kind: 'composer' | 'npm' | 'cargo' | 'pyproject' | 'go' | 'ruby' | 'unknown';
+    /**
+     * The primary kind — the first manifest in {@link SCOPE_DETECT_MANIFESTS}
+     * order that is present. Retained unchanged so every existing caller keeps
+     * working; a single-manifest repository sees exactly what it saw before.
+     */
+    readonly kind: ProjectKind;
     readonly root: string;
+    /** The primary manifest, matching {@link ProjectShape.kind}. */
     readonly manifest: string | null;
+    /**
+     * EVERY detected kind, in {@link SCOPE_DETECT_MANIFESTS} order.
+     *
+     * Added 2026-08-26 (road-to-internal-estate-fit 2.1). The shape of a
+     * repository carrying two manifests is *both*, and the caller can decide
+     * what to do with that — a `find()` returning the first one described a
+     * polyglot repository as its first half and gave the caller no way to know
+     * a second existed. Empty only when `kind` is `'unknown'`.
+     */
+    readonly kinds: readonly ProjectKind[];
+    /** Every detected manifest filename, parallel to {@link ProjectShape.kinds}. */
+    readonly manifests: readonly string[];
 }
 
 /**
@@ -139,20 +172,30 @@ export interface ProjectShape {
  * Manifest-to-kind mapping mirrors {@link SCOPE_DETECT_MANIFESTS}:
  * `package.json` → npm, `composer.json` → composer, etc.
  */
+const MANIFEST_KIND = {
+    'package.json': 'npm',
+    'composer.json': 'composer',
+    'pyproject.toml': 'pyproject',
+    'Cargo.toml': 'cargo',
+    'go.mod': 'go',
+    Gemfile: 'ruby',
+} as const satisfies Record<string, ProjectKind>;
+
 export function detectProjectShape(root: string): ProjectShape {
-    const manifest = SCOPE_DETECT_MANIFESTS.find((m) => existsSync(join(root, m)));
-    if (manifest === undefined) {
-        return { kind: 'unknown', root, manifest: null };
+    const manifests = SCOPE_DETECT_MANIFESTS.filter((m) => existsSync(join(root, m)));
+    if (manifests.length === 0) {
+        return { kind: 'unknown', root, manifest: null, kinds: [], manifests: [] };
     }
-    const kind = ({
-        'package.json': 'npm',
-        'composer.json': 'composer',
-        'pyproject.toml': 'pyproject',
-        'Cargo.toml': 'cargo',
-        'go.mod': 'go',
-        Gemfile: 'ruby',
-    } as const)[manifest] ?? 'unknown';
-    return { kind, root, manifest };
+    const kinds = manifests.map(
+        (m) => (MANIFEST_KIND as Record<string, ProjectKind>)[m] ?? 'unknown',
+    );
+    return {
+        kind: kinds[0] as ProjectKind,
+        root,
+        manifest: manifests[0] as string,
+        kinds,
+        manifests,
+    };
 }
 
 /** AI-tool presence flags discovered in a project tree. */