@bevel-software/platform-core-backend 0.25.0 → 0.26.0

package/dist/modules/workspace/startup/steps/template-files.step.js

@@ -1,12 +1,20 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { LEGACY_AGENTS_FILE, agentsFilePointerSentence, gitignoreLiteral, mentionsAgentsFile, retargetAgentsFilePointer, validateKbRootName, } from '@bevel-software/platform-shared';
+import { LEGACY_AGENTS_FILE, validateKbRootName, } from '@bevel-software/platform-shared';
 import { IGNORE_FILENAME, isAbsence } from '../../../../shared/fs.contract.js';
 import { PREAMBLE_FILE } from '../../../agent-instructions/compose.js';
+import { isManagedGuide } from '../../../agent-guide/agent-guide.js';
 import { TemplateSource } from './template-source.js';
 import { hasGitInternalsSegment } from '../../../../shared/git-internals.js';
+export { isManagedGuide };
 /** Root-anchored so a knowledge folder may still contain an ordinary namesake. */
 const PREAMBLE_IGNORE_PATTERN = `/${PREAMBLE_FILE}`;
+/**
+ * The guide's name before it was `AGENTS.md`, back when it was a file. A copy
+ * the platform wrote under it is taken out of the repository like one under
+ * the current name (see {@link TemplateFilesStep.retireGuideCopies}).
+ */
+const PRE_RENAME_AGENTS_FILE = 'CLAUDE.md';
 /**
  * The **required scaffolding** — the minimum an operational KB needs. Any of
  * these missing from a protected branch are added at the startup phase; the
@@ -22,16 +30,14 @@ const PREAMBLE_IGNORE_PATTERN = `/${PREAMBLE_FILE}`;
  *
  * `roles.yaml` is in neither, and is not part of the template at all: it is
  * generated from `ADMIN_EMAIL` (see roles-yaml.step.ts), so a repo can't be
- * seeded with a stale hard-coded Admin list.
+ * seeded with a stale hard-coded Admin list. The agent guide is in neither
+ * either, any more: it is served from code (see modules/agent-guide), and the
+ * copies earlier releases wrote are REMOVED here, not refreshed.
  */
-export function requiredFiles(layout) {
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- the list is a function of the layout to its callers, though no name in it is configurable today
+export function requiredFiles(_layout) {
     return [
         'access.md',
-        // The managed agent guide, under whatever this deployment calls it. The
-        // PACKAGED template still carries it as `AGENTS.md` — one file, one
-        // spelling in the tarball — so the write target and the template source
-        // part company here and nowhere else (see {@link templateNameOf}).
-        layout.agentsFile,
         '.bevelignore',
         '.gitignore',
         // The deployment preamble every connected agent is told at session start
@@ -41,30 +47,6 @@ export function requiredFiles(layout) {
         PREAMBLE_FILE,
     ];
 }
-/**
- * The template's own name for a required file. The guide is the one file whose
- * name on disk is a deployment's choice while its name in the template is
- * fixed; everything else is spelled the same on both sides.
- */
-function templateNameOf(repoRel, agentsFile) {
-    return repoRel === agentsFile ? LEGACY_AGENTS_FILE : repoRel;
-}
-/**
- * The sentence the managed guide carries about itself, and the ONLY thing that
- * makes a root `AGENTS.md` provably the platform's rather than the customer's.
- *
- * Matched on this one phrase rather than on the whole header: the lines around
- * it have changed between releases (they name the configured file now), and a
- * knowledge base seeded by any of those releases is still ours to remove. A
- * customer file would have to quote the platform's own claim about itself
- * verbatim to be mistaken for one, and the consequence of the mistake is a
- * deletion — which is why nothing looser will do.
- */
-const MANAGED_GUIDE_MARKER = '**This file is managed by the platform.**';
-/** Whether `text` is a copy of the platform's managed guide, of any vintage. */
-export function isManagedGuide(text) {
-    return text.includes(MANAGED_GUIDE_MARKER);
-}
 /**
  * Repo-root files the startup phase GENERATES rather than copies — today just
  * `roles.yaml`, rendered from `ADMIN_EMAIL` (see roles-yaml.step.ts and
@@ -139,13 +121,16 @@ export function reservedRootDirs(extraRootDirs, layout) {
 }
 /**
  * The template top-up as an {@link OnServerStart} step: add any missing base
- * scaffolding to every PROTECTED branch, and keep the managed agent guide
- * current — under whatever this deployment calls it, and taking its own
- * stale `AGENTS.md` with it when that name was handed back to the customer. Drafts are deliberately out of scope — whatever the protected
- * branches gain, drafts fork from; a scaffolding addition on a draft would
- * surface as noise in its change request's diff. (Unlike the Groups→Plugins
- * rename, a missing file diffs as one file, not the whole tree — so the
- * uniform-application argument does not bite here.)
+ * scaffolding to every PROTECTED branch, and take the agent guide copies
+ * earlier releases wrote OUT of them — the guide is served from code now, and
+ * a copy left on disk would be read as the organisation's own conventions
+ * file, stale and under a header that says the platform owns it. Drafts are
+ * deliberately out of scope — whatever the protected branches gain, drafts
+ * fork from; a scaffolding addition on a draft would surface as noise in its
+ * change request's diff. (Unlike the Groups→Plugins rename, a missing file
+ * diffs as one file, not the whole tree — so the uniform-application argument
+ * does not bite here. A stale guide copy on a draft is recognised by its
+ * header and never served, see `modules/agent-guide`.)
  *
  * Everything is DECLARED on the branch handle; reads go against the pre-step
  * tree via `repoDir()`. Fail-open behavior from the lazy top-up (best-effort,
@@ -157,7 +142,6 @@ export class TemplateFilesStep {
     disk;
     kb;
     extraRootDirs;
-    agentsFileLink;
     name = 'template-files';
     /**
      * @param extraRootDirs Additional root folders this distribution reserves,
@@ -166,23 +150,16 @@ export class TemplateFilesStep {
      *                      claim a root without also shipping a template entry
      *                      for it.
      */
-    /**
-     * @param agentsFileLink Whether to keep the platform's pointer sentence in a
-     *                       customer-owned root `AGENTS.md` — a GETTER, because
-     *                       the setting behind it may be saved by the very
-     *                       first-run save that then runs this phase.
-     */
     constructor(disk, 
     /**
      * Read per run, never captured: the save that completes first-run setup
      * applies the admin's names after this step was built. A snapshot taken
      * here scaffolded `Skills/` beside the `skills/` they had just chosen.
      */
-    kb, extraRootDirs = [], agentsFileLink = () => true) {
+    kb, extraRootDirs = []) {
         this.disk = disk;
         this.kb = kb;
         this.extraRootDirs = extraRootDirs;
-        this.agentsFileLink = agentsFileLink;
         // Validated NOW, so a bad extra fails at boot beside the rest of the
         // wiring — but the list itself is NOT kept, for the reason `kb` says.
         reservedRootDirs(extraRootDirs, kb.layout);
@@ -203,8 +180,6 @@ export class TemplateFilesStep {
         // Read ONCE per branch: a value re-read between the write and the ignore
         // rule could disagree with itself.
         const layout = this.kb.layout;
-        const agentsFile = layout.agentsFile;
-        const renamed = agentsFile !== LEGACY_AGENTS_FILE;
         for (const rel of requiredFiles(layout)) {
             // `lstat`, not `exists`: a DIRECTORY or SYMLINK squatting a required
             // file's name would read as "present", and a skip-if-present check
@@ -219,48 +194,35 @@ export class TemplateFilesStep {
                     `(${found.isSymbolicLink() ? 'symlink' : found.isDirectory() ? 'directory' : 'special file'}). ` +
                     'Remove or rename it — the platform requires this name to be a readable file.');
             }
-            let content = await templates.read(templateNameOf(rel, agentsFile));
+            let content = await templates.read(rel);
             // The on-disk merge below only runs against an EXISTING ignore file; a
-            // freshly-declared one was merely assumed to carry the guide's rule —
-            // true of the packaged template, not necessarily of a distribution's
-            // custom one. Make it true here, so the managed conventions doc is
-            // hidden from the file tree from the first boot either way. The same is
-            // true of the deployment preamble: it is edited through External agent
-            // access, not as an ordinary knowledge-base document.
-            // …and a template still shipping the skills rule an earlier release
-            // had (a distribution's copy, a stale packaged one) must not declare
-            // it: the on-disk reconciliation below never sees a file that was
-            // absent, so the declared content is reconciled here instead.
+            // freshly-declared one is reconciled here instead, so a distribution's
+            // custom template that predates a rule — or still ships one an earlier
+            // release had — declares the same file the merge would have produced.
+            // The deployment preamble is edited through External agent access, not
+            // as an ordinary knowledge-base document, so its rule is guaranteed;
+            // the rules that hid the skills root, the plugins root and the guide
+            // copies the platform used to write are taken out (see the merge below
+            // for why each).
             if (rel === IGNORE_FILENAME) {
                 // A template still shipping the unanchored preamble rule an earlier
                 // release had is respelled first, so the guarantee below adds nothing
                 // beside it.
                 content = withPlatformIgnorePatternRespelled(content, PREAMBLE_FILE, PREAMBLE_IGNORE_PATTERN);
-                content = withoutIgnoreLine(withoutPlatformIgnorePattern(withIgnorePattern(withIgnorePattern(content, gitignoreLiteral(agentsFile), agentsFile), PREAMBLE_IGNORE_PATTERN, agentsFile), `${layout.skillsDir}/`), `${layout.pluginsDir}/`);
-                // …and a template (a distribution's, a stale packaged one) still
-                // hiding `AGENTS.md` while this deployment's guide is called something
-                // else would hide the CUSTOMER'S file from the first boot — the exact
-                // thing the rename exists to prevent.
-                if (renamed)
-                    content = withoutPlatformAgentsRule(content);
+                content = withoutPlatformGuideRules(withoutIgnoreLine(withoutPlatformIgnorePattern(withIgnorePattern(content, PREAMBLE_IGNORE_PATTERN), `${layout.skillsDir}/`), `${layout.pluginsDir}/`), [LEGACY_AGENTS_FILE, PRE_RENAME_AGENTS_FILE]);
             }
             branch.write(rel, content);
             added.push(rel);
         }
-        // The guide or mcp-description.md left VISIBLE by a stale `.bevelignore`
-        // is closed here — and
-        // UNCONDITIONALLY, not only when the file was just added: a KB whose
-        // guide predates the CLAUDE.md→AGENTS.md rename has an ignore file
-        // that lists the old name and knows nothing of the new one, so the
-        // conventions doc shows up in the file tree and the agent view. A KB
-        // whose deployment has just RENAMED the guide is the same story one
-        // rename later: the rule names a file that is now the customer's.
+        // mcp-description.md left VISIBLE by a stale `.bevelignore` is closed
+        // here — and UNCONDITIONALLY, not only when the file was just added.
         // Idempotent: an ignore file already carrying the rule — or absent, in
         // which case the template's copy declared above arrives with the rule in
         // it — changes nothing and produces no note. Deliberately checked by
-        // LINE PRESENCE, not effective outcome: a later `!<guide>` negation is
-        // the operator explicitly choosing to SHOW the file, and hiding it is a
-        // default this step provides, not a mandate it re-imposes every boot.
+        // LINE PRESENCE, not effective outcome: a later `!/mcp-description.md`
+        // negation is the operator explicitly choosing to SHOW the file, and
+        // hiding it is a default this step provides, not a mandate it re-imposes
+        // every boot.
         //
         // The shared-skills root goes the OTHER way. An earlier release hid it
         // like `Plugins/`; the Skills & Tools sidebar now renders it as a file
@@ -277,144 +239,101 @@ export class TemplateFilesStep {
         // it as a file tree too, so the rule that hid it since the first seed
         // comes out. That one has no comment to know it by — it was in the
         // template body from the start — so every line spelling it goes,
-        // whoever wrote it (see `withoutIgnoreLine`). ONE read-modify-write for
-        // all the rules: separate passes would each read the on-disk file and
-        // a later declared write would lose an earlier one's.
+        // whoever wrote it (see `withoutIgnoreLine`).
+        //
+        // And the guide's rules go the same way as the skills root's. Every
+        // release that wrote the guide to disk hid it with a rule of its own —
+        // under `AGENTS.md`, under the name a deployment gave the guide (any
+        // name it ever gave it: the copies found at the root say which), and
+        // under `CLAUDE.md` for the copy that predates the rename. The guide is
+        // not on disk any more, so a root file under any of those names is the
+        // organisation's own conventions page, which they must be able to see
+        // and edit in the app. The platform's own lines come out, recognised by
+        // the comment or the template slot each release wrote them in (see
+        // {@link withoutPlatformGuideRules}); a rule an operator wrote by hand
+        // is theirs and stays. ONE read-modify-write for all the rules: separate
+        // passes would each read the on-disk file and a later declared write
+        // would lose an earlier one's.
+        //
+        // The copies come out first only so the one commit this step makes can
+        // name them in its subject; the rule pass below does not read the names
+        // — a guide rule is known by the platform's comment above it, whatever
+        // name it spells.
+        const retired = await this.retireGuideCopies(repoDir, branch);
+        added.push(...retired);
         added.push(...(await this.reconcileIgnoreRules(repoDir, branch, {
             // The preamble rule is respelled before it is added: a knowledge base
             // that booted the release shipping the unanchored spelling carries the
             // platform's own line, and that line hides a nested namesake too.
             respell: [[PREAMBLE_FILE, PREAMBLE_IGNORE_PATTERN]],
-            // As a gitignore PATTERN: a guide name that reads as syntax there is
-            // escaped, or the rule would hide nothing.
-            add: [gitignoreLiteral(agentsFile), PREAMBLE_IGNORE_PATTERN],
+            add: [PREAMBLE_IGNORE_PATTERN],
             drop: [`${this.kb.layout.skillsDir}/`],
             dropEvery: [`${this.kb.layout.pluginsDir}/`],
-            // The guide's rule FOLLOWS its name. Once the guide is `HEXIS.md`, the
-            // root's `AGENTS.md` is the customer's own conventions file and they
-            // must be able to see and edit it in the app — so the platform's own
-            // line comes out, recognised the way the skills-root line was
-            // (see {@link withoutPlatformAgentsRule}); a rule an operator wrote by
-            // hand is theirs and stays.
-            dropAgentsRule: renamed,
+            // The two names the template itself shipped a rule for. A rule under
+            // any other name — a retired copy's, or a name no copy is left to
+            // tell — is known by the platform's comment above it instead.
+            guideNames: [LEGACY_AGENTS_FILE, PRE_RENAME_AGENTS_FILE],
         })));
-        // The guide is MANAGED, not merely seeded: the platform owns its content,
-        // and a stale copy is replaced with the packaged template's every startup
-        // phase. The file's own header says so, which is what makes overwriting
-        // edits a stated contract instead of a surprise.
-        let agentsRefreshed = false;
-        if (!added.includes(agentsFile) &&
-            (await templates.differsFrom(repoDir, agentsFile, LEGACY_AGENTS_FILE))) {
-            branch.write(agentsFile, await templates.read(LEGACY_AGENTS_FILE));
-            added.push(agentsFile);
-            agentsRefreshed = true;
-        }
-        // What becomes of the `AGENTS.md` the platform used to own, now that the
-        // guide lives somewhere else. Nothing at all while the name is the default.
-        if (renamed) {
-            added.push(...(await this.reconcileLegacyGuide(repoDir, branch, {
-                agentsFile,
-                // Only on the boot the rename lands — the boot that first writes the
-                // guide under its new name. Said every boot after, the "kept" note
-                // would caption commits about other things forever.
-                announceKept: added.includes(agentsFile),
-            })));
-        }
         added.push(...this.ensureRequiredDirs(repoDir, branch, await this.missingDirs(repoDir)));
         if (added.length === 0)
             return;
         // One honest line; it becomes the commit subject when this step is the
         // first to dirty the branch.
-        branch.note(agentsRefreshed && added.length === 1
-            ? `Update ${agentsFile} to the current platform template`
+        const others = added.filter((rel) => !retired.includes(rel));
+        branch.note(retired.length > 0
+            ? `Remove the platform-written ${retired.join(' and ')} — the agent guide is served by the platform now` +
+                (others.length > 0 ? `; update ${others.join(', ')}` : '')
             : `Add missing KB scaffolding: ${added.join(', ')}`);
     }
     /**
-     * The root `AGENTS.md` on a deployment whose guide is called something else:
-     * removed when the platform can PROVE it wrote it, otherwise left alone —
-     * and, while the admin keeps the link setting on, given the one sentence
-     * that points at the guide beside it.
-     *
-     * Removal is gated on the managed header and nothing else. An admin who
-     * renames the guide on a knowledge base the platform seeded would otherwise
-     * be left with stale platform content sitting under the very name they
-     * wanted for their own file; an admin who renames it on a repository whose
-     * `AGENTS.md` is their own must find that file byte-for-byte untouched. The
-     * header is the one fact that tells the two apart, so it is the one thing
-     * asked.
+     * The copies of the guide the platform wrote to the repository root while
+     * the guide was a file — under `AGENTS.md`, under `CLAUDE.md` from before
+     * the rename, and under every name a deployment ever gave the guide —
+     * removed when the platform can PROVE it wrote them, and otherwise left
+     * exactly alone.
      *
-     * The pointer is bounded by three conditions, all of them the customer's to
-     * control: the admin keeps the setting on, the file exists (one is NEVER
-     * created for this), and the guide's name appears nowhere in the text. That
-     * last one is a plain content search on purpose — a mention in the
-     * customer's own words, a link, a heading, all count, and the platform stays
-     * out of a file it does not own.
+     * Found by SCANNING the root's markdown files rather than by the names the
+     * deployment knows today: a deployment that renamed the guide more than
+     * once left a copy under each earlier name, and the current setting
+     * remembers only the last. The header is what makes a scan safe, and the
+     * one fact that tells a copy of ours from a file of theirs: the
+     * organisation's own `AGENTS.md`, a `CLAUDE.md` its people edited, a note
+     * of theirs that happens to sit at the root, must all be found byte for
+     * byte untouched. A SYMLINK or a directory is left as it is: reading a link
+     * follows it, so a link pointing at a copy of the guide — or at any other
+     * file carrying the header — would read as ours and the removal would take
+     * the organisation's entry. Links are never followed anywhere else in the
+     * platform, and they are not followed here.
      *
-     * Returns the paths changed, for the note.
+     * Returns the names removed, in name order, for the note and for the
+     * ignore rules that hid them.
      */
-    async reconcileLegacyGuide(repoDir, branch, opts) {
-        const legacyPath = path.join(repoDir, LEGACY_AGENTS_FILE);
-        // `lstat` first, and a REGULAR FILE or nothing at all.
-        //
-        // Nothing there is the ordinary case: no customer file means nothing to
-        // remove and nothing to point at the guide — the platform never creates an
-        // `AGENTS.md` for this.
-        //
-        // Anything that is not a plain file is left exactly as it is. A SYMLINK is
-        // the case that matters: reading one follows it, so a link pointing at a
-        // knowledge base's managed guide — or at any other file carrying the
-        // header — would read as "ours" and the removal would take the customer's
-        // entry; writing one follows it too, and the pointer sentence would land
-        // in a file at the other end that nobody asked us to edit. Links are never
-        // followed anywhere else in the platform, and they are not followed here.
-        // A directory under the name is the same answer for the same reason.
-        const found = await this.disk.lstatOrNull(legacyPath);
-        if (found === null || !found.isFile())
-            return [];
-        let current;
-        try {
-            current = await this.disk.readTextFile(legacyPath);
-        }
-        catch (err) {
-            // Gone between the probe and the read — a concurrent delete reads as the
-            // absence it is, on the same terms as the probe above.
-            if (isAbsence(err))
-                return [];
-            throw err;
-        }
-        if (isManagedGuide(current)) {
-            branch.remove(LEGACY_AGENTS_FILE);
-            branch.note(`Remove the platform-written AGENTS.md — the agent guide is now ${opts.agentsFile}`);
-            return [LEGACY_AGENTS_FILE];
-        }
-        if (opts.announceKept) {
-            branch.note('Keep AGENTS.md — it is not a platform template, so it is the knowledge base\'s own');
-        }
-        // The admin's consent gates every write below, this file being theirs.
-        if (!this.agentsFileLink())
-            return [];
-        // A sentence of OURS already in the file is updated rather than joined by
-        // a second one. The guide's name can be changed again, and after a second
-        // rename the sentence this step wrote last time points at a file that is
-        // no longer there — which asking "is the new name mentioned?" cannot see,
-        // because the old sentence does not mention it.
-        const retargeted = retargetAgentsFilePointer(current, opts.agentsFile);
-        if (retargeted !== null) {
-            if (retargeted === current)
-                return [];
-            branch.write(LEGACY_AGENTS_FILE, retargeted);
-            branch.note(`Point the sentence in AGENTS.md at ${opts.agentsFile}`);
-            return [LEGACY_AGENTS_FILE];
+    async retireGuideCopies(repoDir, branch) {
+        const removed = [];
+        const entries = await fs.readdir(repoDir, { withFileTypes: true });
+        // `isFile` is false for a link, which is the point (see above).
+        const candidates = entries
+            .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith('.md'))
+            .map((entry) => entry.name)
+            .sort();
+        for (const name of candidates) {
+            let current;
+            try {
+                current = await this.disk.readTextFile(path.join(repoDir, name));
+            }
+            catch (err) {
+                // Gone between the listing and the read — a concurrent delete reads
+                // as the absence it is.
+                if (isAbsence(err))
+                    continue;
+                throw err;
+            }
+            if (!isManagedGuide(current))
+                continue;
+            branch.remove(name);
+            removed.push(name);
         }
-        // Nothing of ours in there, so the question is the customer's own text.
-        // Asked through the shared reading, not a raw `includes`: the sentence
-        // spells the name escaped and percent-encoded, so on a punctuated name the
-        // copy written last boot need not carry the raw name at all.
-        if (mentionsAgentsFile(current, opts.agentsFile))
-            return [];
-        branch.write(LEGACY_AGENTS_FILE, withPointerSentence(current, opts.agentsFile));
-        branch.note(`Add a pointer to ${opts.agentsFile} at the end of AGENTS.md`);
-        return [LEGACY_AGENTS_FILE];
+        return removed;
     }
     /**
      * Which reserved roots are absent — and which are SQUATTED. `lstat`, not
@@ -488,9 +407,9 @@ export class TemplateFilesStep {
             return [];
         }
         const respelled = (rules.respell ?? []).reduce((text, [from, to]) => withPlatformIgnorePatternRespelled(text, from, to), current);
-        const added = rules.add.reduce((text, pattern) => withIgnorePattern(text, pattern, this.kb.layout.agentsFile), respelled);
+        const added = rules.add.reduce((text, pattern) => withIgnorePattern(text, pattern), respelled);
         const dropped = (rules.dropEvery ?? []).reduce((text, pattern) => withoutIgnoreLine(text, pattern), rules.drop.reduce((text, pattern) => withoutPlatformIgnorePattern(text, pattern), added));
-        const merged = rules.dropAgentsRule ? withoutPlatformAgentsRule(dropped) : dropped;
+        const merged = withoutPlatformGuideRules(dropped, rules.guideNames);
         if (merged === current)
             return [];
         branch.write(IGNORE_FILENAME, merged);
@@ -565,15 +484,99 @@ function followsTemplateHygieneBlock(kept) {
         return false;
     return kept.slice(-block.length).every((line, i) => line.trim() === block[i]);
 }
+/**
+ * `text` without the rules THE PLATFORM WROTE to hide the guide while it was a
+ * file. Under WHATEVER name: every rule sitting directly under one of the two
+ * comments the platform wrote above the guide's rule
+ * ({@link withoutPlatformConventionsRules}) — the name a deployment saved for
+ * the guide is not read any more, so the rule for it is known by its comment
+ * and by nothing else. Then the two names the template itself shipped a rule
+ * for, under each of `names`: the `AGENTS.md` line in the slot at the end of
+ * the template's own repo-hygiene block
+ * ({@link TEMPLATE_HYGIENE_BLOCK_ABOVE_AGENTS_RULE}) and the `CLAUDE.md` line
+ * under the two-line comment the template carried it with. Each goes with
+ * its comment.
+ *
+ * The guide is not on disk any more, which is what makes every one of these
+ * lines wrong: it hides a file the platform never writes, which is therefore
+ * the organisation's own. A `!AGENTS.md` negation is not the rule and stays,
+ * as everywhere else here, and so does a bare rule an operator wrote by hand.
+ */
+export function withoutPlatformGuideRules(text, names) {
+    let out = withoutPlatformConventionsRules(text);
+    for (const name of new Set(names)) {
+        if (name === LEGACY_AGENTS_FILE)
+            out = withoutPlatformAgentsRule(out);
+        else if (name === PRE_RENAME_AGENTS_FILE)
+            out = withoutPlatformClaudeRule(out);
+    }
+    return out;
+}
+/**
+ * `text` without every rule line that sits DIRECTLY under one of the two
+ * comments the platform wrote above the guide's rule while the guide was a
+ * file ({@link PLATFORM_RULE_COMMENT}, {@link AGENTS_RULE_COMMENT}), whatever
+ * name the rule spells — `AGENTS.md`, `CLAUDE.md`, or the escaped form of a
+ * name a deployment chose — and without that comment, plus the blank line
+ * that opened the appended block. Those two comments were written above
+ * nothing else, so the comment is the whole provenance: a rule for a name
+ * nobody remembers is retired exactly like one for a name still known. A
+ * `!negation`, a blank or a further comment under the comment is not a rule
+ * and stays, comment included.
+ */
+function withoutPlatformConventionsRules(text) {
+    const lines = text.split('\n');
+    const kept = [];
+    for (const line of lines) {
+        const above = kept[kept.length - 1]?.trim();
+        const rule = line.trim();
+        const ours = (above === PLATFORM_RULE_COMMENT || above === AGENTS_RULE_COMMENT) &&
+            rule !== '' &&
+            !rule.startsWith('#') &&
+            !rule.startsWith('!');
+        if (!ours) {
+            kept.push(line);
+            continue;
+        }
+        kept.pop();
+        if (kept.length > 1 && kept[kept.length - 1]?.trim() === '')
+            kept.pop();
+    }
+    return kept.join('\n');
+}
+/** The two comment lines the packaged template carried above its `CLAUDE.md` rule, in order. */
+const TEMPLATE_CLAUDE_RULE_COMMENT = [
+    '# The pre-rename name. Listed so a knowledge base carrying both files hides',
+    '# both — top-up adds AGENTS.md but never deletes the CLAUDE.md beside it.',
+];
+/**
+ * `text` without the `CLAUDE.md` line the packaged template wrote, and without
+ * the two comment lines it wrote above it. Provenance is that comment, as
+ * everywhere else here: a bare `CLAUDE.md` an operator wrote is theirs.
+ */
+function withoutPlatformClaudeRule(text) {
+    const lines = text.split('\n');
+    const kept = [];
+    for (const line of lines) {
+        const [first, second] = TEMPLATE_CLAUDE_RULE_COMMENT;
+        const ours = line.trim() === PRE_RENAME_AGENTS_FILE &&
+            kept.length >= 2 &&
+            kept[kept.length - 1].trim() === second &&
+            kept[kept.length - 2].trim() === first;
+        if (!ours) {
+            kept.push(line);
+            continue;
+        }
+        kept.splice(-2, 2);
+    }
+    return kept.join('\n');
+}
 /**
  * `text` without the `AGENTS.md` line THE PLATFORM WROTE — under its own
  * comment (either spelling), or in the slot at the end of the template's own
  * repo-hygiene block ({@link TEMPLATE_HYGIENE_BLOCK_ABOVE_AGENTS_RULE}) — and
- * without that comment.
- *
- * Called only when the guide has been renamed, which is what makes the line
- * wrong: it hides a file the platform no longer owns. A `!AGENTS.md` negation
- * is not the rule and stays, as everywhere else here.
+ * without that comment. A `!AGENTS.md` negation is not the rule and stays, as
+ * everywhere else here.
  */
 export function withoutPlatformAgentsRule(text) {
     const lines = text.split('\n');
@@ -601,17 +604,6 @@ export function withoutPlatformAgentsRule(text) {
     }
     return kept.join('\n');
 }
-/**
- * `text` with the platform's pointer sentence appended as its own paragraph.
- *
- * One blank line between the customer's last line and ours, whether or not
- * their file ended in a newline: a sentence glued onto the end of their last
- * paragraph would read as a continuation of something they wrote.
- */
-export function withPointerSentence(text, agentsFile) {
-    const body = text.replace(/\n+$/, '');
-    return `${body}\n\n${agentsFilePointerSentence(agentsFile)}\n`;
-}
 /** The comment written above the preamble rule on an existing knowledge base. */
 const PREAMBLE_RULE_COMMENT = '# Added by the platform: agent instructions are edited from External agent access.';
 /**
@@ -719,20 +711,14 @@ function withPlatformIgnorePatternRespelled(text, from, to) {
  * still standing here is the operator's: it already hides the file, and
  * appending the anchored rule beside it would say nothing they have not.
  */
-function withIgnorePattern(text, pattern, agentsFile) {
+function withIgnorePattern(text, pattern) {
     const lines = text.split('\n').map((l) => l.trim());
     const operatorPreambleRule = pattern === PREAMBLE_IGNORE_PATTERN &&
         (lines.includes(PREAMBLE_FILE) || lines.includes(`!${PREAMBLE_FILE}`));
     if (lines.includes(pattern) || lines.includes(`!${pattern}`) || operatorPreambleRule)
         return text;
     const separator = text.endsWith('\n') ? '' : '\n';
-    // The guide's rule arrives as a gitignore literal (escaped where the name
-    // needs it), so it is recognised in that spelling.
-    const comment = pattern === PREAMBLE_IGNORE_PATTERN
-        ? PREAMBLE_RULE_COMMENT
-        : pattern === gitignoreLiteral(agentsFile)
-            ? AGENTS_RULE_COMMENT
-            : PLATFORM_RULE_COMMENT;
+    const comment = pattern === PREAMBLE_IGNORE_PATTERN ? PREAMBLE_RULE_COMMENT : PLATFORM_RULE_COMMENT;
     return `${text}${separator}\n${comment}\n${pattern}\n`;
 }
 //# sourceMappingURL=template-files.step.js.map