@cratis/pi 7.1.5 → 7.2.1

package/README.md

@@ -9,8 +9,8 @@ pi install -l npm:@cratis/pi
 
 The package reads the repository's `.cratis/ai.json`, resolves its profiles and
 languages through the packaged profile catalog, and contributes only the matching
-skills. It also loads packaged rules, prompts, agents, the subagent tool, and
-Cratis quality hooks. When no `.cratis/ai.json` exists, it exposes the complete
+skills. It also loads packaged rules, path guidance, prompts, agents, the
+subagent tool, and Cratis quality hooks. When no `.cratis/ai.json` exists, it exposes the complete
 packaged skill set. It therefore gives Pi the complete single-harness Cratis
 experience without requiring the Cratis CLI.
 
@@ -24,7 +24,48 @@ The managed CLI path remains the choice when one repository must configure and
 synchronize several harnesses. It writes the resolved corpus to `.cratis/ai`,
 creates every harness integration, and records hashes for safe update and
 uninstall. That managed setup loads rules through its own `.pi/extensions/cratis-rules`
-extension and does not require this package. If both paths are present, the package
+and `.pi/extensions/cratis-path-guidance` extensions and does not require this package. If both paths are present, the package
 yields to the managed installation to avoid duplicate resources and hooks. The Pi
 package manages only Pi; it neither configures other harnesses nor owns a local
 managed corpus.
+
+## Path guidance and subagents
+
+The packaged `cratis-path-guidance` extension attaches a path-scoped rule to the
+tool result the first time a matching file is touched, and after a successful
+`write` or `edit` adds one advisory line naming every skill whose `SKILL.md`
+`cratis-hint-paths` frontmatter matches the file. (The key is Cratis-specific
+because Claude Code gives a plain `paths` key its own meaning.) A skill is hinted at
+most once per session and not when it is already in context: read (a shell command
+counts only when `cat`, `sed`, `head`, `tail`, `less`, `bat`, `rg` or `grep` opens
+its `SKILL.md` or a file under `references/`), preloaded by pi-subagents, or
+expanded by `/skill:name`. A pi-subagents header without the skill's text (its
+loader cannot read a symlinked `.pi/skills`) does not count as preloaded. The
+skills considered are the ones Pi loaded plus the skills the repository selected
+(`.cratis/ai.json`), so a session whose Pi skill list holds only personal skills,
+or none (for example `skills: false`), still gets hints; an unselected skill is
+never hinted, and none is added if the selection cannot be resolved. Rules follow
+the same language and documentation selection as the system prompt. Nothing is
+blocked and the system prompt is untouched. The system prompt carries only the
+universal rules, so path-scoped rules are not delivered twice. The extension works
+in sessions without a UI. It stands down when a managed installation
+(`.cratis/ai.manifest.json`) already delivers path guidance: through its own
+`.pi/extensions/cratis-path-guidance`, or through any `.pi/extensions/cratis-rules`
+that is not the current universal-only version, since every earlier version
+delivers path-scoped rules itself. A `cratis-rules` that cannot be recognised
+counts as one that delivers them. In such an older managed installation, a subagent
+that loads only the allowlisted extensions below gets no path guidance until
+`cratis ai update` installs the managed `cratis-path-guidance`.
+
+The universal rules add about 26k tokens to every session. A pi-subagents agent
+(`@tintinweb/pi-subagents`) with an `extensions:` allowlist loads only the
+extensions it names, so it gets none of this package by default. Name the two
+cheap extensions to give it path guidance and the write and store guards without
+the universal rules:
+
+```yaml
+extensions: cratis-path-guidance, cratis-hooks
+```
+
+The `subagent` tool of this package starts a full `pi` process and loads every
+extension.

package/package/corpus/agents/coordinator.md

@@ -128,7 +128,7 @@ For implementation, the applicable changed-lane gates must pass. Mark unrelated
 - [ ] `Documentation/verify-markdown.sh` passes when documentation is added or changed
 - [ ] `code-reviewer` finds no blocking issues
 - [ ] `security-reviewer` finds no vulnerabilities
-- [ ] PR description follows the pull request template
+- [ ] PR description follows the pull request template and the release-note contract in `pull-requests.md`; test and review notes are in a PR comment
 
 ---
 

package/package/corpus/agents/orchestrator.md

@@ -152,7 +152,7 @@ For implementation, the applicable changed-lane gates must pass. Mark unrelated
 - [ ] `code-reviewer` finds no blocking issues
 - [ ] `security-reviewer` finds no vulnerabilities
 - [ ] All documentation is complete and accurate (if required)
-- [ ] PR description follows the pull request template
+- [ ] PR description follows the pull request template and the release-note contract in `pull-requests.md`; test and review notes are in a PR comment
 
 ---
 

package/package/corpus/agents/planner.md

@@ -115,7 +115,7 @@ For an implemented application slice, require the applicable changed-lane gates
 - [ ] `Documentation/verify-markdown.sh` passes when documentation is added or changed
 - [ ] Code review by `code-reviewer` finds no blocking issues
 - [ ] Security review by `security-reviewer` finds no vulnerabilities
-- [ ] PR description follows the pull request template
+- [ ] PR description follows the pull request template and the release-note contract in `pull-requests.md`; test and review notes are in a PR comment
 
 ---
 

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/LoadedSkill.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The part of a Pi skill (`event.systemPromptOptions.skills`) this extension reads. */
+export interface LoadedSkill {
+    name: string;
+    filePath: string;
+    baseDir?: string;
+}

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/SkillMatch.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { SkillTrigger } from './SkillTrigger.ts';
+
+/** A skill whose trigger matched a path, with the glob that matched. */
+export interface SkillMatch {
+    skill: SkillTrigger;
+    glob: string;
+}

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/SkillTrigger.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** A skill available to the session together with the path globs its `SKILL.md` declares as triggers. */
+export interface SkillTrigger {
+    name: string;
+    /** Absolute path of the skill's `SKILL.md`. */
+    filePath: string;
+    /** Directory holding `SKILL.md` and the skill's references. */
+    baseDir: string;
+    /** The `cratis-hint-paths` frontmatter of the skill. Empty when the skill declares no trigger. */
+    globs: string[];
+}

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/ToolName.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The Pi tools whose results carry a file path this extension reacts to. */
+export enum ToolName {
+    Read = 'read',
+    Write = 'write',
+    Edit = 'edit',
+    Bash = 'bash',
+    PowerShell = 'powershell',
+}

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/index.ts

@@ -0,0 +1,166 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { ManagedRule } from '../shared/ManagedRule.ts';
+import { rulesForPath } from '../shared/rules.ts';
+import type { LoadedSkill } from './LoadedSkill.ts';
+import type { SkillMatch } from './SkillMatch.ts';
+import type { SkillTrigger } from './SkillTrigger.ts';
+import { skillsRead } from './skillReads.ts';
+import { skillsForPath, skillTriggers } from './skills.ts';
+import { standsDown } from './standDown.ts';
+import { ToolName } from './ToolName.ts';
+import { touchedPaths } from './touchedPaths.ts';
+
+const extensionDirectory = dirname(fileURLToPath(import.meta.url));
+const isPackagedExtension = extensionDirectory.includes(`${sep}package${sep}corpus${sep}`);
+
+function repositoryRelative(cwd: string, path: string): string | undefined {
+    const relativePath = relative(cwd, resolve(cwd, path));
+    return !relativePath || relativePath.startsWith('..') || isAbsolute(relativePath) ? undefined : relativePath.split(sep).join('/');
+}
+
+function displayPath(cwd: string, path: string): string {
+    return repositoryRelative(cwd, path) ?? path;
+}
+
+/** One line for everything a write matched, however many skills, so overlapping triggers cost one line and not several. */
+function hintLine(cwd: string, files: string[], matches: SkillMatch[]): string {
+    const skills = matches.map(match => `\`${match.skill.name}\` (matched \`${match.glob}\`)`);
+    const named = skills.length === 1 ? `Skill ${skills[0]} covers` : `Skills ${skills.slice(0, -1).join(', ')} and ${skills[skills.length - 1]} cover`;
+    const documents = matches.map(match => displayPath(cwd, match.skill.filePath));
+    const read = documents.length === 1 ? documents[0] : `${documents.slice(0, -1).join(', ')} and ${documents[documents.length - 1]}`;
+    return `[cratis-path-guidance] ${named} ${files.join(', ')}; read ${read} before continuing.`;
+}
+
+/**
+ * pi-subagents writes `# Preloaded Skill: <name>` for every name in `skills:` and then the skill's text, or a
+ * placeholder when it could not load it: `(Skill "<name>" not found in ...)` or `(Skill "<name>" skipped: ...)`.
+ * It cannot load a skill from a symlinked skills root, which is how a managed installation exposes
+ * `.pi/skills` and `.agents/skills`. Only a header followed by real content puts the skill in context.
+ */
+const placeholderBody = /^\(Skill "[^"]*" (?:not found|skipped)\b/;
+
+/** The skills pi-subagents preloaded into the system prompt (`skills: a, b`) whose full text is already in context. */
+function preloadedSkillNames(systemPrompt: unknown): Set<string> {
+    const names = new Set<string>();
+    if (typeof systemPrompt !== 'string') return names;
+    for (const match of systemPrompt.matchAll(/^# Preloaded Skill: (\S+)[ \t]*\r?\n/gm)) {
+        const body = systemPrompt.slice(match.index + match[0].length).split(/^# Preloaded Skill: /m)[0].trim();
+        if (body.length > 0 && !placeholderBody.test(body)) names.add(match[1]);
+    }
+    return names;
+}
+
+/** The skills a `/skill:name` command expanded into the user message, which arrive without a `read` call. */
+function expandedSkillNames(prompt: unknown): string[] {
+    return typeof prompt === 'string' ? [...prompt.matchAll(/<skill name="([^"]+)"/g)].map(match => match[1]) : [];
+}
+
+/**
+ * Delivers the corpus guidance that belongs to a file at the moment the file is touched, so it works in every
+ * Pi process, including a subagent, without the universal rules `cratis-rules` puts in every system prompt.
+ *
+ * Path-scoped rules are attached to the tool result the first time a matching file is touched in the session,
+ * exactly as they were when `cratis-rules` delivered them. On a successful `write` or `edit`, one advisory line
+ * names every skill whose `cratis-hint-paths` frontmatter matches the file and where its `SKILL.md` is. A skill
+ * is not hinted when it is already in context: read in the session, preloaded by pi-subagents
+ * (`# Preloaded Skill: <name>` followed by its text in the system prompt), or expanded by `/skill:<name>`. Hints are advisory only:
+ * nothing is blocked and the system prompt is never touched.
+ *
+ * Delivery happens on `tool_result`, so guidance arrives after the call that first touched the file.
+ * `ToolCallEventResult` carries only `block`/`reason`/`terminate`, so there is no supported way to add
+ * context before a tool runs. In practice a file is read before it is edited, and reads through both the read
+ * tool and bash are covered; a file created blind by `write` is the residual case, and it receives the
+ * guidance with that result.
+ *
+ * Delivered guidance lives in the conversation rather than the system prompt, so anything that rewrites or
+ * replaces the conversation can remove it. The delivery record is therefore reset whenever that happens, and the
+ * guidance is delivered again the next time one of its files is touched.
+ */
+export default function (pi: ExtensionAPI): void {
+    if (standsDown(isPackagedExtension, process.cwd())) return;
+
+    const deliveredRules = new Set<string>();
+    const hintedSkills = new Set<string>();
+    const readSkills = new Set<string>();
+    // Preloaded skills live in the system prompt, which compaction leaves alone, so this is replaced at each
+    // agent start rather than reset with the conversation.
+    let preloadedSkills = new Set<string>();
+    let loadedSkills: LoadedSkill[] | undefined;
+    let loadedKey: string | undefined;
+    let triggers: SkillTrigger[] | undefined;
+
+    const availableTriggers = (cwd: string): SkillTrigger[] => triggers ??= skillTriggers(loadedSkills, cwd);
+
+    // Compaction summarizes the conversation, which can drop an injected rule or hint while leaving the
+    // delivery record claiming it is present; a switch replaces the conversation outright.
+    const reset = () => {
+        deliveredRules.clear();
+        hintedSkills.clear();
+        readSkills.clear();
+        triggers = undefined;
+    };
+    pi.on('session_start', reset);
+    pi.on('session_compact', reset);
+    pi.on('session_before_switch', reset);
+
+    // Only observes which skills are in context for this session; the system prompt is never changed.
+    pi.on('before_agent_start', event => {
+        const observed = event as { systemPrompt?: unknown; prompt?: unknown; systemPromptOptions?: { skills?: LoadedSkill[] } };
+        preloadedSkills = preloadedSkillNames(observed.systemPrompt);
+        expandedSkillNames(observed.prompt).forEach(name => readSkills.add(name));
+        const skills = observed.systemPromptOptions?.skills;
+        const key = skills?.map(skill => `${skill.name}\t${skill.filePath}`).join('\n');
+        if (key !== loadedKey) triggers = undefined;
+        loadedSkills = skills;
+        loadedKey = key;
+        return undefined;
+    });
+
+    pi.on('tool_result', (event, context) => {
+        if (event.isError) return;
+        const cwd = context.cwd;
+        const toolName: string = event.toolName;
+        const input = event.input;
+
+        const reads = skillsRead(toolName, input, availableTriggers(cwd));
+        reads.forEach(skill => readSkills.add(skill.name));
+
+        const pendingRules: ManagedRule[] = [];
+        const matchedFiles: string[] = [];
+        const hintedFiles: string[] = [];
+        const pendingMatches: SkillMatch[] = [];
+        for (const path of touchedPaths(toolName, input, cwd)) {
+            const relativePath = repositoryRelative(cwd, path);
+            if (!relativePath) continue;
+            for (const rule of rulesForPath(cwd, relativePath)) {
+                if (deliveredRules.has(rule.name) || pendingRules.some(candidate => candidate.name === rule.name)) continue;
+                pendingRules.push(rule);
+                if (!matchedFiles.includes(relativePath)) matchedFiles.push(relativePath);
+            }
+            if (toolName !== ToolName.Write && toolName !== ToolName.Edit) continue;
+            for (const match of skillsForPath(availableTriggers(cwd), relativePath)) {
+                const name = match.skill.name;
+                if (hintedSkills.has(name) || readSkills.has(name) || preloadedSkills.has(name)) continue;
+                hintedSkills.add(name);
+                pendingMatches.push(match);
+                if (!hintedFiles.includes(relativePath)) hintedFiles.push(relativePath);
+            }
+        }
+        if (pendingRules.length === 0 && pendingMatches.length === 0) return;
+        pendingRules.forEach(rule => deliveredRules.add(rule.name));
+
+        const existing = Array.isArray(event.content) ? event.content : [];
+        const text = [
+            pendingRules.length === 0
+                ? undefined
+                : `\n\n[cratis-rules] Rules that apply to ${matchedFiles.join(', ')}:\n\n${pendingRules.map(rule => rule.content).join('\n\n')}`,
+            pendingMatches.length === 0 ? undefined : `\n\n${hintLine(cwd, hintedFiles, pendingMatches)}`,
+        ].filter(part => part !== undefined).join('');
+        return { content: [...existing, { type: 'text', text }] };
+    });
+}

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/skillReads.ts

@@ -0,0 +1,62 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { SkillTrigger } from './SkillTrigger.ts';
+import { ToolName } from './ToolName.ts';
+import { commandOf, isShellTool } from './touchedPaths.ts';
+
+/** Shell commands that put a file's content in front of the model. `ls`, `git diff` or `git add` do not. */
+const readers = new Set(['cat', 'sed', 'head', 'tail', 'less', 'bat', 'rg', 'grep']);
+
+/** `rtk` verbs that read: `rtk read`, `rtk cat`, and `rtk grep`/`rtk rg` on a file. */
+const rtkReaders = new Set(['read', ...readers]);
+
+function escapeRegExp(text: string): string {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Whether a path names a file inside the skill's directory. */
+function isInsideSkill(path: string, skill: SkillTrigger): boolean {
+    if (path.includes(`${skill.baseDir}/`)) return true;
+    return new RegExp(`(?:^|[/\\s'"=])skills/${escapeRegExp(skill.name)}/`).test(path.replaceAll('\\', '/'));
+}
+
+/** Whether text names the skill's `SKILL.md`, or a file under its `references/`. */
+function namesSkillDocument(text: string, skill: SkillTrigger): boolean {
+    const normalized = text.replaceAll('\\', '/');
+    if (normalized.includes(`${skill.baseDir}/SKILL.md`) || normalized.includes(`${skill.baseDir}/references/`)) return true;
+    return new RegExp(`(?:^|[/\\s'"=])skills/${escapeRegExp(skill.name)}/(?:SKILL\\.md|references/)`).test(normalized);
+}
+
+/**
+ * The commands of a shell line that read a file. The line is split at `&&`, `||`, `|`, `;` and newlines, and a
+ * command counts when its verb (after an optional `rtk` or `rtk proxy`) is a reader. An `echo`, a commit message
+ * or `git diff` that merely mentions a path is not a read.
+ */
+function readerCommands(command: string): string[] {
+    return command.split(/\s*(?:&&|\|\||\||;(?=\s|$)|\n)\s*/).filter(segment => {
+        const words = segment.trim().split(/\s+/);
+        if (words[0] !== 'rtk') return readers.has(words[0]);
+        const verb = words[1] === 'proxy' ? words[2] : words[1];
+        return words[1] === 'proxy' ? readers.has(verb) : rtkReaders.has(verb);
+    });
+}
+
+/**
+ * The skills a successful tool call read: the `read` tool on any file under `skills/<name>/`, or a shell reader
+ * (`cat`, `sed`, `head`, `tail`, `less`, `bat`, `rg`, `grep`, `rtk read`) on that skill's `SKILL.md` or a file
+ * under its `references/`. A model that opened either already has the skill's guidance. Listing the directory,
+ * or a `git` command that names the path, gives it nothing and is not a read.
+ */
+export function skillsRead(toolName: string, input: unknown, skills: SkillTrigger[]): SkillTrigger[] {
+    if (toolName === ToolName.Read) {
+        const candidate = input as { path?: unknown; file_path?: unknown } | undefined;
+        const value = candidate?.path ?? candidate?.file_path;
+        return typeof value === 'string' ? skills.filter(skill => isInsideSkill(value, skill)) : [];
+    }
+    if (!isShellTool(toolName)) return [];
+    const command = commandOf(input);
+    if (command === undefined) return [];
+    const commands = readerCommands(command);
+    return skills.filter(skill => commands.some(segment => namesSkillDocument(segment, skill)));
+}

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/skills.ts

@@ -0,0 +1,72 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { corpusRoot } from '../shared/corpusRoot.ts';
+import { frontmatter } from '../shared/frontmatter.ts';
+import { globToRegExp } from '../shared/globs.ts';
+import { skillTriggerKey } from '../shared/skillFrontmatter.ts';
+import { selectedSkillNames } from '../shared/skillSelection.ts';
+import type { LoadedSkill } from './LoadedSkill.ts';
+import type { SkillMatch } from './SkillMatch.ts';
+import type { SkillTrigger } from './SkillTrigger.ts';
+
+function skillAt(root: string, name: string): LoadedSkill[] {
+    const filePath = join(root, name, 'SKILL.md');
+    return existsSync(filePath) ? [{ name, filePath, baseDir: join(root, name) }] : [];
+}
+
+/**
+ * The skills the repository selected, whether or not Pi loaded them into the session. A managed installation resolves
+ * them into `.cratis/ai/skills`. Without one, the packaged corpus holds every catalog skill, so the selection
+ * comes from `.cratis/ai.json` and the profile catalog; when that cannot be resolved nothing is hinted.
+ */
+function repositorySkills(cwd: string): LoadedSkill[] {
+    const managedRoot = join(cwd, '.cratis', 'ai', 'skills');
+    if (existsSync(managedRoot)) {
+        return readdirSync(managedRoot, { withFileTypes: true })
+            .filter(entry => entry.isDirectory())
+            .flatMap(entry => skillAt(managedRoot, entry.name));
+    }
+    const packagedRoot = join(corpusRoot, 'skills');
+    return (selectedSkillNames(cwd) ?? []).flatMap(name => skillAt(packagedRoot, name));
+}
+
+function triggerGlobs(filePath: string): string[] {
+    try {
+        return frontmatter(readFileSync(filePath, 'utf8')).get(skillTriggerKey) ?? [];
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * The skills available to a session with their trigger globs: the skills Pi loaded for the session
+ * (`systemPromptOptions.skills`) together with the repository's selected skills, deduplicated by name with the
+ * loaded one winning. The union matters because Pi's list says nothing about whether the Cratis skills are in it:
+ * it can be empty (a pi-subagents agent with `skills: false`, the usual setup for cheap workers), or non-empty
+ * with only personal skills (an agent with `skills: true` whose `extensions:` allowlist leaves `@cratis/pi`, and
+ * so its skill paths, out). The selected skills' `SKILL.md` can still be read by path, which is what the hint asks
+ * for; a corpus skill the repository did not select is never added. Skills without a `cratis-hint-paths` trigger
+ * are left out.
+ */
+export function skillTriggers(loaded: LoadedSkill[] | undefined, cwd: string): SkillTrigger[] {
+    const loadedNames = new Set((loaded ?? []).map(skill => skill.name));
+    return [...(loaded ?? []), ...repositorySkills(cwd).filter(skill => !loadedNames.has(skill.name))]
+        .map(skill => ({
+            name: skill.name,
+            filePath: skill.filePath,
+            baseDir: skill.baseDir ?? dirname(skill.filePath),
+            globs: triggerGlobs(skill.filePath),
+        }))
+        .filter(skill => skill.globs.length > 0);
+}
+
+/** The skills whose trigger matches a repository-relative path, each with the first glob that matched. */
+export function skillsForPath(triggers: SkillTrigger[], relativePath: string): SkillMatch[] {
+    return triggers.flatMap(skill => {
+        const glob = skill.globs.find(candidate => globToRegExp(candidate).test(relativePath));
+        return glob === undefined ? [] : [{ skill, glob }];
+    });
+}

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/standDown.ts

@@ -0,0 +1,48 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Whether a managed `cratis-rules` delivers path-scoped rules itself, which is every generation but the current one:
+ *
+ * - `6b0bb54`, `5b048c6`: `before_agent_start` concatenates every rule into the system prompt;
+ * - `aca9c6b`, `59362cf`, `1937b06`, `eec744a`: universal rules in the system prompt, path-scoped rules on
+ *   `tool_result`;
+ * - current: universal rules only, taken from `../shared/rules.ts`, with no `tool_result` handler.
+ *
+ * Only a file that is recognisably the current one, importing the shared rules and having no `tool_result`
+ * handler, is trusted not to deliver path rules; anything else, including a file that cannot be read, is assumed
+ * to. Standing down on a guess costs allowlisted subagents their path guidance until `cratis ai update`, which
+ * is cheaper than duplicating every path-scoped rule in every full session.
+ */
+function managedRulesDeliverPaths(cwd: string): boolean {
+    const path = join(cwd, '.pi', 'extensions', 'cratis-rules', 'index.ts');
+    if (!existsSync(path)) return false;
+    try {
+        const content = readFileSync(path, 'utf8');
+        return !content.includes("'../shared/rules.ts'") || content.includes('tool_result');
+    } catch {
+        return true;
+    }
+}
+
+/**
+ * A managed installation (`.cratis/ai.manifest.json`) loads its own extensions from `.pi/extensions`. The copy
+ * shipped in `@cratis/pi` stands down when that installation already delivers path guidance, so a rule or hint
+ * is never delivered twice, whichever versions are mixed:
+ *
+ * - the managed `cratis-path-guidance` exists: it delivers rules and hints;
+ * - an older managed `cratis-rules` exists, which delivers path-scoped rules itself, in the system prompt or on
+ *   `tool_result`: the packaged copy would repeat every rule, so it yields until `cratis ai update` installs the
+ *   managed copy;
+ * - a current managed `cratis-rules` that only injects universal rules, or no managed Pi extensions at all:
+ *   nothing else delivers path guidance, so the packaged copy stays active.
+ *
+ * The managed copy never stands down.
+ */
+export function standsDown(packaged: boolean, cwd: string): boolean {
+    if (!packaged || !existsSync(join(cwd, '.cratis', 'ai.manifest.json'))) return false;
+    return existsSync(join(cwd, '.pi', 'extensions', 'cratis-path-guidance', 'index.ts')) || managedRulesDeliverPaths(cwd);
+}

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/touchedPaths.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { ToolName } from './ToolName.ts';
+
+/** Upper bound on files considered from one bash command, so a wide command cannot deliver the corpus. */
+const maxPathsPerCommand = 10;
+
+export function isShellTool(toolName: string): boolean {
+    return toolName === ToolName.Bash || toolName === ToolName.PowerShell;
+}
+
+export function commandOf(input: unknown): string | undefined {
+    const command = (input as { command?: unknown } | undefined)?.command;
+    return typeof command === 'string' ? command : undefined;
+}
+
+/**
+ * Extracts file paths a bash command refers to. `rtk.md` tells agents to run `rtk read`, `rtk grep`
+ * and `rtk find` from the terminal for bulk reads, so file access frequently arrives as a bash
+ * command rather than the read tool; without this, a session that follows that rule would never
+ * receive a path-scoped rule. A token counts only when it resolves to a file that exists inside the
+ * working directory, which keeps a filename mentioned inside a commit message from matching.
+ */
+function pathsFromCommand(command: string, cwd: string): string[] {
+    const found: string[] = [];
+    for (const raw of command.split(/[\s;|&()<>]+/)) {
+        if (found.length >= maxPathsPerCommand) break;
+        const token = raw.replace(/^['"]+|['"]+$/g, '').replace(/[,:]+$/, '');
+        if (!token || token.startsWith('-') || !/[./]/.test(token)) continue;
+        try {
+            if (statSync(resolve(cwd, token)).isFile()) found.push(token);
+        } catch {
+            /* not a path we can see; ignore */
+        }
+    }
+    return found;
+}
+
+/** The file paths a tool call refers to, as the tool received them. */
+export function touchedPaths(toolName: string, input: unknown, cwd: string): string[] {
+    if (isShellTool(toolName)) {
+        const command = commandOf(input);
+        return command === undefined ? [] : pathsFromCommand(command, cwd);
+    }
+    if (toolName !== ToolName.Read && toolName !== ToolName.Write && toolName !== ToolName.Edit) return [];
+    const candidate = (input as { path?: unknown; file_path?: unknown } | undefined);
+    const value = candidate?.path ?? candidate?.file_path;
+    return typeof value === 'string' && value.length > 0 ? [value] : [];
+}