@event4u/agent-config 14.12.0 → 14.13.0

package/dist/install/claudeRuleRewrite.js

@@ -0,0 +1,254 @@
+/**
+ * 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 = ['package', 'source_path'];
+/**
+ * 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, original) {
+    const keep = [];
+    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, quiet, info, warn, wrappers) {
+    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) {
+    return s.replace(/\s+$/u, '');
+}
+/** Mirrors `condense.ts::_yaml_scalar`. */
+function yamlScalar(value) {
+    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) {
+    const [meta, body] = parseFrontmatter(sourceText);
+    const plan = _claude_paths_plan(meta);
+    const lines = [];
+    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) {
+    const result = { rewritten: 0, scoped: [], dropped: [], failed: [] };
+    let entries;
+    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;
+        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;
+        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;
+}
+//# sourceMappingURL=claudeRuleRewrite.js.map

package/dist/install/detect.js

@@ -30,10 +30,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 = [
     'package.json',
@@ -106,20 +112,27 @@ export function scopeToTarget(scope) {
  * 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',
+};
 export function detectProjectShape(root) {
-    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',
-    }[manifest] ?? 'unknown';
-    return { kind, root, manifest };
+    const kinds = manifests.map((m) => MANIFEST_KIND[m] ?? 'unknown');
+    return {
+        kind: kinds[0],
+        root,
+        manifest: manifests[0],
+        kinds,
+        manifests,
+    };
 }
 /** Read AI-tool presence flags from `root`. Pure — no writes. */
 export function detectToolPresence(root) {

package/dist/install/detect_php_shape.js

@@ -0,0 +1,159 @@
+/**
+ * Which PHP application shape is in play — decided from the entry point and the
+ * router, never from the dependency list.
+ *
+ * `road-to-consumer-repo-reality` Phase 3. A dependency proves a library is
+ * AVAILABLE. Only the entry point and the routing mechanism prove which
+ * application shape is actually running.
+ *
+ * THE THIRD STATE IS THE POINT. Component-based distribution is a published
+ * model: a framework family ships its ORM, container, collections and HTTP
+ * layer as independently installable packages, usable with no framework
+ * present. PHP has at least two families distributed exactly this way, so the
+ * shape is a property of the DISTRIBUTION MODEL and not of any one consumer.
+ *
+ * Dependency-presence routing sends such an application to the framework's
+ * skill, which then offers a CLI that does not exist, a request-validation
+ * primitive that is not wired, and a routes file that was never there. Every
+ * suggestion is confidently wrong, and the reason is visible only from the
+ * entry point.
+ *
+ * COST IS THE OTHER HALF OF THE DESIGN. Risk-register rank 7: "the third
+ * framework state is added but never fires, because the discriminator is
+ * expensive to evaluate". So the discriminator is a FIXED SET of at most
+ * `PROBE_COUNT` filesystem existence checks plus one manifest read — no
+ * directory walk, no content scan, no per-session re-derivation. The probe set
+ * is exported so a caller can state the cost rather than estimate it.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Skeleton markers — the files a framework's own installer writes and a
+ * component consumer never has. Presence of ANY marker for a family is what
+ * makes the framework real rather than merely available.
+ *
+ * These are the framework's console entry point and its bootstrap config, both
+ * generated by the official skeleton and both absent when a developer wires the
+ * components by hand.
+ */
+export const SKELETON_MARKERS = {
+    laravel: ['artisan', path.join('config', 'app.php'), path.join('bootstrap', 'app.php')],
+    symfony: [path.join('bin', 'console'), path.join('config', 'bundles.php'), path.join('config', 'services.yaml')],
+};
+/**
+ * Composer package prefixes that prove a family's COMPONENTS are available.
+ * Availability only — this is deliberately never sufficient for a verdict.
+ */
+export const COMPONENT_PREFIXES = {
+    laravel: ['illuminate/'],
+    symfony: ['symfony/'],
+};
+/** The whole framework, as opposed to its parts. */
+const FRAMEWORK_PACKAGES = {
+    laravel: ['laravel/framework'],
+    symfony: ['symfony/framework-bundle'],
+};
+/** Every path this module may stat. The cost, stated rather than estimated. */
+export const PROBE_PATHS = [
+    'composer.json',
+    ...SKELETON_MARKERS.laravel,
+    ...SKELETON_MARKERS.symfony,
+];
+/** Upper bound on filesystem probes for one verdict. */
+export const PROBE_COUNT = PROBE_PATHS.length;
+function _requireKeys(root) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(root, 'composer.json'), 'utf8'));
+        return [...Object.keys(raw.require ?? {}), ...Object.keys(raw['require-dev'] ?? {})];
+    }
+    catch {
+        return [];
+    }
+}
+function _markers(root, family) {
+    return SKELETON_MARKERS[family].filter((rel) => fs.existsSync(path.join(root, rel)));
+}
+/**
+ * The verdict, in one pass.
+ *
+ * Order matters and is the whole discriminator: a family is only `laravel` or
+ * `symfony` when a **skeleton marker exists**. Components present with no
+ * marker is the third state, and it is checked before falling through to
+ * `plain-php` so a component consumer is never described as a project with no
+ * framework libraries at all.
+ */
+export function detectPhpShape(root) {
+    let probes = 1;
+    const requires = _requireKeys(root);
+    if (requires.length === 0 && !fs.existsSync(path.join(root, 'composer.json'))) {
+        return {
+            shape: 'unknown',
+            componentsOf: null,
+            markersFound: [],
+            reason: 'no composer.json — no PHP application shape to decide',
+            probes: probes + 1,
+        };
+    }
+    // TWO PASSES, and the order between them is the fix for a real defect.
+    //
+    // A single pass that returned on the first family with ANY component present
+    // reported a genuine Symfony application as components-without-framework the
+    // moment its composer.json also required `illuminate/collections` — because
+    // `laravel` is examined first, has a component, has no Laravel skeleton, and
+    // returned before Symfony's three markers were ever looked at. Both
+    // `illuminate/collections` and `illuminate/support` are widely used
+    // standalone, so a mixed manifest is ordinary rather than exotic.
+    //
+    // PASS 1 — a real skeleton anywhere wins. A framework whose own installer
+    // wrote its console entry point and bootstrap config is running, whatever
+    // else the manifest happens to carry.
+    const present = [];
+    for (const family of ['laravel', 'symfony']) {
+        const hasFramework = FRAMEWORK_PACKAGES[family].some((p) => requires.includes(p));
+        const hasComponents = requires.some((r) => COMPONENT_PREFIXES[family].some((p) => r.startsWith(p)));
+        if (!hasFramework && !hasComponents)
+            continue;
+        present.push(family);
+        const markersFound = _markers(root, family);
+        probes += SKELETON_MARKERS[family].length;
+        if (markersFound.length > 0) {
+            return {
+                shape: family,
+                componentsOf: family,
+                markersFound,
+                reason: `${family} skeleton present (${markersFound.join(', ')}) — the framework is real, not merely available`,
+                probes,
+            };
+        }
+    }
+    // PASS 2 — components present, no skeleton for ANY of them. Only now is the
+    // third state the right answer, and it names every family whose components
+    // are available rather than only the first one examined.
+    const first = present[0];
+    if (first !== undefined) {
+        const missing = present.flatMap((f) => SKELETON_MARKERS[f]);
+        const families = present.join(' and ');
+        return {
+            shape: 'components-without-framework',
+            componentsOf: first,
+            markersFound: [],
+            reason: `${families} component(s) are required in composer.json but NO skeleton marker exists ` +
+                `(none of ${missing.join(', ')}). The entry point and router are the ` +
+                `application's own, so the framework CLI, its request-validation primitive and its routes ` +
+                'file are not there. Routing to a framework skill would offer all three.',
+            probes,
+        };
+    }
+    return {
+        shape: 'plain-php',
+        componentsOf: null,
+        markersFound: [],
+        reason: 'composer.json requires no component of either framework family',
+        probes,
+    };
+}
+/** True when a framework-routing rule must NOT claim this tree. */
+export function frameworkRoutingIsWrong(v) {
+    return v.shape === 'components-without-framework';
+}
+//# sourceMappingURL=detect_php_shape.js.map