@opengsd/gsd-core 1.13.0 → 1.14.0

package/gsd-core/bin/lib/roadmap.cjs

@@ -89,7 +89,7 @@ function coerceTruthToString(t) {
     return '';
 }
 // ─── countPhasePlansAndSummaries ──────────────────────────────────────────────
-function countPhasePlansAndSummaries(phaseDir) {
+function countPhasePlansAndSummaries(phaseDir, convention) {
     const { planCount, summaryCount } = scanPhasePlans(phaseDir);
     // hasContext and hasResearch are not plan-scan concerns — read the directory
     // once and share the listing for all non-plan metadata that cmdRoadmapAnalyze needs.
@@ -112,7 +112,9 @@ function countPhasePlansAndSummaries(phaseDir) {
     // summaryCount above stay on scanPhasePlans's own unscoped listing since a
     // PLAN/SUMMARY leading number is a plan sequence number, not a phase
     // number. Mirrors core-utils.cts's getPhaseFileStats.
-    const scopedFiles = scopeToPhase(phaseFiles, node_path_1.default.basename(phaseDir));
+    // #612: `convention` threaded from the one caller (which already threads it
+    // into matchPhaseDirs) so a bracket dir scopes by its real token.
+    const scopedFiles = scopeToPhase(phaseFiles, node_path_1.default.basename(phaseDir), convention);
     return {
         planCount,
         summaryCount,
@@ -349,8 +351,17 @@ function collectAnalyzePhases(content, phasesDir, phaseDirNames, convention) {
     // #3036: widen the id capture to accept non-numeric-leading ids (e.g. B7, P0.3-2)
     // that get-phase/execute-phase already resolve. An optional leading letter prefix
     // ([A-Za-z]?) covers letter-prefixed ids without breaking numeric-leading ones.
+    // #4478: line-anchored (`^ {0,3}`, `/m`) — unanchored, `#{2,4}` matched a
+    // `### Phase N:`-shaped mention ANYWHERE `exec()`'s scan reached: mid-sentence
+    // prose, inside a blockquote, inside an inline code span (backtick-quoted on
+    // the same line, not a fenced block `tokenizeHeadings` would exclude). Any
+    // such line minted a phantom phase entry, inflating phase_count and able to
+    // collide on a phase NUMBER with a real heading nearby. `{0,3}` leading
+    // spaces mirrors `tokenizeHeadings`'s own CommonMark ATX-heading tolerance
+    // (src/markdown-sectionizer.cts:453) so a legitimately-indented heading that
+    // matched before this fix still matches after it.
     // phase-id-owner: uses the [.-] (dot-or-dash) separator variant, not the canonical dot-only token; a swap to PHASE_NUMBER_TOKEN_SOURCE would drop hyphenated phase-id matches.
-    const phasePattern = new RegExp(`#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.ANY_BRACKET, convention, true)}([A-Za-z]?\\d+[A-Z]?(?:[.-]\\d+)*)(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
+    const phasePattern = new RegExp(`^ {0,3}#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.ANY_BRACKET, convention, true)}([A-Za-z]?\\d+[A-Z]?(?:[.-]\\d+)*)(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gim');
     // The capturing intro inserts the bracket id at group 1 only under the
     // bracket convention; the token and name shift by the same offset.
     const G = convention === 'bracket' ? 1 : 0;
@@ -372,7 +383,13 @@ function collectAnalyzePhases(content, phasesDir, phaseDirNames, convention) {
         // #3691: `\d` → `\d[\d.]*` so decimal phase headings (e.g. `### Phase 02.3:`) are
         // recognised as section boundaries. #3036: `[A-Za-z]?\d` so non-numeric-leading ids
         // (e.g. B7) are also recognised.
-        const nextHeader = restOfContent.match(new RegExp(`\\n#{2,4}\\s+${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.ANY_BRACKET, convention)}[A-Za-z]?\\d[\\d.-]*`, 'i'));
+        // #4478 follow-up (independent code review on this same fix): ` {0,3}` after
+        // the literal `\n` mirrors phasePattern's own new leading-space tolerance
+        // above -- without it, a legitimately-indented (1-3 space) NEXT phase
+        // heading was invisible to this boundary lookup, letting the PRIOR phase's
+        // goal/mode/depends_on extraction bleed across the section boundary into
+        // the next phase's own body.
+        const nextHeader = restOfContent.match(new RegExp(`\\n {0,3}#{2,4}\\s+${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.ANY_BRACKET, convention)}[A-Za-z]?\\d[\\d.-]*`, 'i'));
         const sectionEnd = nextHeader ? sectionStart + nextHeader.index : content.length;
         const section = content.slice(sectionStart, sectionEnd);
         const goalMatch = section.match(/\*\*Goal(?::\*\*|\*\*:)\s*([^\n]+)/i);
@@ -420,7 +437,7 @@ function collectAnalyzePhases(content, phasesDir, phaseDirNames, convention) {
         // convention into that owner rather than reviving the primitive `.find()`.
         const dirMatch = matchPhaseDirs(phaseDirNames, normalized, convention).matches[0];
         if (dirMatch) {
-            const counts = countPhasePlansAndSummaries(node_path_1.default.join(phasesDir, dirMatch));
+            const counts = countPhasePlansAndSummaries(node_path_1.default.join(phasesDir, dirMatch), convention);
             planCount = counts.planCount;
             summaryCount = counts.summaryCount;
             hasContext = counts.hasContext;
@@ -433,7 +450,10 @@ function collectAnalyzePhases(content, phasesDir, phaseDirNames, convention) {
             // NOT a precondition, so a zero-plan phase with a passing
             // `*-VERIFICATION.md` reports complete here too, not just via
             // `phase.complete`.
-            const completionResult = isPhaseComplete(node_path_1.default.join(phasesDir, dirMatch));
+            // #612: `convention` (a parameter of this function, same thread as
+            // matchPhaseDirs above) rides into completion so a bracket phase dir
+            // resolves and scopes its verification report like its legacy twin.
+            const completionResult = isPhaseComplete(node_path_1.default.join(phasesDir, dirMatch), { convention });
             if (completionResult.value.complete)
                 diskStatus = 'complete';
             else if (summaryCount > 0)
@@ -841,7 +861,11 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     // the same phase (ADR-3180 §7.4's headline: one predicate for the read
     // path and the write path).
     const phaseDir = node_path_1.default.join(cwd, phaseInfo.directory);
-    const completionResult = isPhaseComplete(phaseDir);
+    // ADR-3180 §7.4 read/write-path symmetry with the threaded site at ~583:
+    // thread convention here too, so this write path's completion reading
+    // agrees with the read path's under the bracket convention.
+    const convention = resolvePhaseIdConvention(cwd);
+    const completionResult = isPhaseComplete(phaseDir, { convention });
     const verificationResult = completionResult.value.verification;
     // #2648 precedent, applied at this write site (ADR-3180 §7.4 / #3186):
     // `isPhaseComplete` deliberately carries NO plan-count precondition — the
@@ -872,6 +896,23 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     }
     // Wrap entire read-modify-write in lock to prevent concurrent corruption
     let updated = false;
+    // #4247: the refusal flag. The write/report decision below must be keyed to
+    // "a writable roadmap representation of THIS phase was found", never to "any
+    // byte moved". On a checklist-form ROADMAP (`- [ ] **Phase N: …**`, the
+    // roadmapper's own summary-checklist form) every phase-targeted grammar
+    // below requires an ATX `#{2,4} Phase N` heading and therefore finds
+    // nothing; the Progress-table row is the only other writable target, and
+    // when its Phase cell does not match `phaseCellRe` (e.g. a word-prefixed
+    // `Phase 68` cell — deliberately unrecognized on the read side too,
+    // `deriveProgressFromRoadmap`'s `/^\d/` data-row filter) the command used
+    // to fall through to unrelated byte deltas (an UN-scoped plan-checkbox mark
+    // anywhere in the document) and report `updated: true` while the phase's
+    // own row stayed untouched — with the file-global write then letting the
+    // platform write seam's markdown normalization inject blank lines around
+    // other phases' bullets, splitting hand-wrapped sentences mid-entry. The
+    // refusal below declines with the analyzer's own `missing_phase_details`
+    // vocabulary and leaves ROADMAP.md byte-identical.
+    let missingPhaseDetails = false;
     withPlanningLock(cwd, () => {
         // #3957 (B9.4): captured BEFORE any transform runs, so the write/report
         // decision below reflects whether the transforms actually changed
@@ -881,6 +922,32 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         const originalContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
         let roadmapContent = originalContent;
         const phasePattern = phaseMarkdownRegexSource(phaseNum);
+        // #4247: ONE local source for the ATX phase-heading anchor that every
+        // section-scoped writer below (`planCountPattern`,
+        // `insertRowsPatternA|B`) starts with — extracted so the target-detection
+        // gate below reads the SAME grammar the writers anchor on, and a future
+        // edit to one cannot drift from the other three copies.
+        const phaseHeadingAnchor = `#{2,4}\\s*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s])`;
+        // #4247: target detection runs against the ORIGINAL content's active
+        // (post-</details>) region — the same milestone scoping every writer
+        // below applies — so the gate asks "does the file carry a writable phase
+        // representation" rather than "did some regex fire mid-transform".
+        const gateDetailsClose = originalContent.lastIndexOf('</details>');
+        const gateActiveRegion = gateDetailsClose === -1
+            ? originalContent
+            : originalContent.slice(gateDetailsClose + '</details>'.length);
+        // Heading target: the exact grammar `planCountPattern` /
+        // `insertRowsPatternA|B` anchor on (an ATX phase heading for this phase).
+        const headingTargetFound = new RegExp(phaseHeadingAnchor, 'i').test(gateActiveRegion);
+        // Checklist target: when the phase is complete, its own checklist bullet
+        // (`- [ ] **Phase N: …**`) IS a writable phase row — the completion
+        // checkbox stamp below updates it. Same grammar as that writer, widened
+        // one notch to `[ x]` so an ALREADY-checked bullet still counts as a
+        // found target: an idempotent re-run then takes the honest
+        // "no changes were needed" decline instead of this refusal.
+        const checklistTargetFound = isComplete && new RegExp(`-\\s*\\[[ x]\\]\\s*.*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'i').test(gateActiveRegion);
+        // Table-row target: set by the row-scoped cell updates below.
+        let tableRowFound = false;
         // Progress table row: update Plans Complete/Status/Completed columns BY
         // COLUMN NAME (handles 4- or 5-column RoadmapProgress tables regardless of
         // Milestone-column presence) via the markdown-table seam (ADR-2143 §7) —
@@ -899,11 +966,15 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         roadmapContent = editProgressTableSlice(roadmapContent, (scoped) => {
             let text = scoped;
             const plansResult = (0, markdown_table_cjs_1.updateTableCell)(text, rowMatch, 'Plans Complete', ` ${summaryCount}/${planCount} `);
-            if (plansResult.ok)
+            if (plansResult.ok) {
                 text = plansResult.value;
+                tableRowFound = true;
+            }
             const statusResult = (0, markdown_table_cjs_1.updateTableCell)(text, rowMatch, 'Status', ` ${status.padEnd(11)}`);
-            if (statusResult.ok)
+            if (statusResult.ok) {
                 text = statusResult.value;
+                tableRowFound = true;
+            }
             // Preserve only a valid ISO date (#1161: idempotent; self-heal garbage).
             // Ragged-tolerant (#2245 Blocker 2): probe the CURRENT Completed cell via
             // a no-op updateTableCell write (its own tolerant row scan) rather than
@@ -918,8 +989,10 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
                 }
                 return '  ';
             });
-            if (completedResult.ok)
+            if (completedResult.ok) {
                 text = completedResult.value;
+                tableRowFound = true;
+            }
             return text;
         });
         // Update plan count in phase detail section.
@@ -960,7 +1033,7 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         //      `_match` unchanged. An untouched first line cannot orphan its own
         //      continuation on the next line, since the pattern never spans past
         //      `\n` in the first place.
-        const planCountPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s])(?:(?!\\n#{1,4}\\s)[\\s\\S])*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*|(?:^|\\n)Plans:)\\s*)(\\d+\\s*\\/\\s*\\d+\\s+plans(?:\\s+(?:complete|executed))?|\\d+\\s+plans?)?([^\\r\\n]*)`, 'i');
+        const planCountPattern = new RegExp(`(${phaseHeadingAnchor}(?:(?!\\n#{1,4}\\s)[\\s\\S])*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*|(?:^|\\n)Plans:)\\s*)(\\d+\\s*\\/\\s*\\d+\\s+plans(?:\\s+(?:complete|executed))?|\\d+\\s+plans?)?([^\\r\\n]*)`, 'i');
         const planCountText = isComplete
             ? `${summaryCount}/${planCount} plans complete`
             : `${summaryCount}/${planCount} plans executed`;
@@ -1040,8 +1113,8 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
             //
             // Pattern A: anchor to bare `Plans:` header (preferred).
             // Pattern B: fallback to bold summary when no bare header exists.
-            const insertRowsPatternA = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s])(?:(?!\\n#{1,4}\\s)[\\s\\S])*?(?:^|\\n)(?:Plans:)[^\\n]*)`, 'i');
-            const insertRowsPatternB = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s])(?:(?!\\n#{1,4}\\s)[\\s\\S])*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*)[^\\n]*)`, 'i');
+            const insertRowsPatternA = new RegExp(`(${phaseHeadingAnchor}(?:(?!\\n#{1,4}\\s)[\\s\\S])*?(?:^|\\n)(?:Plans:)[^\\n]*)`, 'i');
+            const insertRowsPatternB = new RegExp(`(${phaseHeadingAnchor}(?:(?!\\n#{1,4}\\s)[\\s\\S])*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*)[^\\n]*)`, 'i');
             const sortedMissing = [...missingPlans].sort();
             const newRows = sortedMissing.map(p => `- [ ] ${p}`).join('\n');
             const inserter = (match) => `${match}\n${newRows}`;
@@ -1081,10 +1154,24 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         // `cmdRoadmapAnnotateDependencies`'s existing `nextContent !== content`
         // gate. Previously this wrote and reported `updated: true`
         // unconditionally, even on an idempotent re-run that changed nothing.
-        if (roadmapContent !== originalContent) {
+        //
+        // #4247: ...but ONLY when a writable representation of THIS phase was
+        // found. Without the target gate, a byte delta from an unrelated
+        // transform (the un-scoped plan-checkbox mark) satisfied the #3957 gate
+        // and produced a success-shaped `updated: true` while the phase's own
+        // row stayed untouched — and the file-global write let the platform
+        // write seam's markdown normalization reflow unrelated entries. When no
+        // target exists the command refuses: no write at all, so ROADMAP.md is
+        // left byte-identical, and the caller gets a typed
+        // `missing_phase_details` decline instead of a false green.
+        const phaseRepresentationFound = tableRowFound || headingTargetFound || checklistTargetFound;
+        if (phaseRepresentationFound && roadmapContent !== originalContent) {
             (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, roadmapContent);
             updated = true;
         }
+        if (!phaseRepresentationFound) {
+            missingPhaseDetails = true;
+        }
     });
     const computed = {
         phase: phaseNum,
@@ -1097,6 +1184,13 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     if (updated) {
         output({ updated: true, ...computed }, raw, `${summaryCount}/${planCount} ${status}`);
     }
+    else if (missingPhaseDetails) {
+        // #4247: honest refusal — the reason names the real condition (the
+        // analyzer's `missing_phase_details` vocabulary), never "already
+        // reflects", which was false: the ROADMAP was never able to record this
+        // phase's progress in the first place.
+        declineNoOp(raw, 'updated', 'missing_phase_details', `roadmap update-plan-progress skipped — ROADMAP.md has no writable entry for phase ${formatDiagnosticToken(String(phaseNum))} (no matching Progress-table row, no phase detail section, and no checklist entry this command can update). ROADMAP.md was left unchanged.`, computed);
+    }
     else {
         declineNoOp(raw, 'updated', "no changes were needed — ROADMAP.md already reflects this phase's plan/summary counts and status", "roadmap update-plan-progress skipped — no changes were needed; ROADMAP.md already reflects this phase's plan/summary counts and status.", computed);
     }

package/gsd-core/bin/lib/runtime-artifact-conversion.cjs

@@ -1011,7 +1011,7 @@ function buildKimiAgentArtifacts({ rootAgent = '', subagents = [], requestedSuba
  * @param {boolean} [isGlobal=false] - Whether this is a global install
  */
 function convertClaudeToAntigravityContent(content, isGlobal = false) {
-    let c = content;
+    let c = filterRuntimeNotesForTarget(content, 'antigravity');
     if (isGlobal) {
         // #3738: global skills install under ~/.gemini/config/skills (the dir AGY
         // scans for global discovery), so skills-path references must divert there
@@ -1103,7 +1103,7 @@ function convertSlashCommandsToCursorSkillMentions(content) {
     return content.replace(/gsd:/gi, 'gsd-');
 }
 function convertClaudeToCursorMarkdown(content) {
-    let converted = convertSlashCommandsToCursorSkillMentions(content);
+    let converted = convertSlashCommandsToCursorSkillMentions(filterRuntimeNotesForTarget(content, 'cursor'));
     // Replace tool name references in body text
     converted = converted.replace(/\bBash\(/g, 'Shell(');
     converted = converted.replace(/\bEdit\(/g, 'StrReplace(');
@@ -1203,7 +1203,7 @@ function convertSlashCommandsToWindsurfSkillMentions(content) {
     return content.replace(/gsd:/gi, 'gsd-');
 }
 function convertClaudeToWindsurfMarkdown(content) {
-    let converted = convertSlashCommandsToWindsurfSkillMentions(content);
+    let converted = convertSlashCommandsToWindsurfSkillMentions(filterRuntimeNotesForTarget(content, 'windsurf'));
     // Replace tool name references in body text
     converted = converted.replace(/\bBash\(/g, 'Shell(');
     converted = converted.replace(/\bEdit\(/g, 'StrReplace(');
@@ -1362,7 +1362,7 @@ function convertSlashCommandsToAugmentSkillMentions(content) {
     return content.replace(/gsd:/gi, 'gsd-');
 }
 function convertClaudeToAugmentMarkdown(content) {
-    let converted = convertSlashCommandsToAugmentSkillMentions(content);
+    let converted = convertSlashCommandsToAugmentSkillMentions(filterRuntimeNotesForTarget(content, 'augment'));
     converted = converted.replace(/\bBash\(/g, 'launch-process(');
     converted = converted.replace(/\bEdit\(/g, 'str-replace-editor(');
     converted = converted.replace(/\bRead\(/g, 'view(');
@@ -1440,7 +1440,7 @@ function convertSlashCommandsToTraeSkillMentions(content) {
     });
 }
 function convertClaudeToTraeMarkdown(content) {
-    let converted = convertSlashCommandsToTraeSkillMentions(content);
+    let converted = convertSlashCommandsToTraeSkillMentions(filterRuntimeNotesForTarget(content, 'trae'));
     converted = converted.replace(/\bBash\(/g, 'Shell(');
     converted = converted.replace(/\bEdit\(/g, 'StrReplace(');
     // Replace general-purpose subagent type with Trae's equivalent "general_purpose_task"
@@ -1548,7 +1548,7 @@ function convertSlashCommandsToCodebuddySkillMentions(content) {
     });
 }
 function convertClaudeToCodebuddyMarkdown(content) {
-    let converted = convertSlashCommandsToCodebuddySkillMentions(content);
+    let converted = convertSlashCommandsToCodebuddySkillMentions(filterRuntimeNotesForTarget(content, 'codebuddy'));
     // CodeBuddy uses the same tool names as Claude Code (Bash, Edit, Read, Write, etc.)
     // No tool name conversion needed
     converted = converted.replace(/\$ARGUMENTS\b/g, '{{GSD_ARGS}}');
@@ -1625,7 +1625,7 @@ function convertClaudeCommandToCodebuddyCommand(content, commandName) {
 }
 // ── Cline converters ────────────────────────────────────────────────────────
 function convertClaudeToCliineMarkdown(content) {
-    let converted = content;
+    let converted = filterRuntimeNotesForTarget(content, 'cline');
     // Cline uses the same tool names as Claude Code — no tool name conversion needed
     converted = converted.replace(/`\.\/CLAUDE\.md`/g, '`.clinerules`');
     converted = converted.replace(/\.\/CLAUDE\.md/g, '.clinerules');
@@ -1712,7 +1712,7 @@ function rewriteBareGsdToolsCommandsForCodex(content) {
         .replace(/((?:&&|\|\||[;|])\s*)gsd-tools(?=\s)/g, `$1${CODEX_GSD_TOOLS_INVOCATION}`);
 }
 function convertClaudeToCodexMarkdown(content) {
-    let converted = convertSlashCommandsToCodexSkillMentions(content);
+    let converted = convertSlashCommandsToCodexSkillMentions(filterRuntimeNotesForTarget(content, 'codex'));
     converted = converted.replace(/\$ARGUMENTS\b/g, '{{GSD_ARGS}}');
     // Remove /clear references — Codex has no equivalent command
     // Handle backtick-wrapped: `\/clear` then: → (removed)
@@ -1901,9 +1901,24 @@ function frontmatterScalar(key, value) {
         ? `${key} "${frontmatterModule.escapeDoubleQuotedScalar(value)}"`
         : `${key} ${value}`;
 }
+const RUNTIME_NOTE_AUDIENCE_BY_HEADING = new Map([
+    ['copilot (vs code)', 'copilot'],
+]);
+function filterRuntimeNotesForTarget(content, targetRuntime) {
+    return content.replace(/<runtime_note(?:\s+runtime=["']([^"']+)["'])?>([\s\S]*?)<\/runtime_note>/g, (whole, declaredAudience, inner) => {
+        if (declaredAudience && declaredAudience.toLowerCase() !== targetRuntime)
+            return '';
+        const remaining = inner.replace(/(?:^|\n)[ \t]*\*\*([^*\n]+):\*\*[^\n]*(?:\n(?![ \t]*\n)[^\n]*)*/g, (section, heading) => {
+            const audience = RUNTIME_NOTE_AUDIENCE_BY_HEADING.get(heading.trim().toLowerCase());
+            return audience && audience !== targetRuntime ? '' : section;
+        });
+        const body = remaining.trim();
+        return body ? `<runtime_note>\n${body}\n</runtime_note>` : '';
+    });
+}
 function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOverride = null, variant = null } = {}) {
     // Replace tool name references in content (applies to all files)
-    let convertedContent = content;
+    let convertedContent = filterRuntimeNotesForTarget(content, 'opencode');
     convertedContent = convertedContent.replace(/\bAskUserQuestion\b/g, 'question');
     convertedContent = convertedContent.replace(/\bSlashCommand\b/g, 'skill');
     convertedContent = convertedContent.replace(/\bTodoWrite\b/g, 'todowrite');
@@ -2064,7 +2079,7 @@ function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOve
 // (#2093).
 function convertClaudeToKiloFrontmatter(content, { isAgent = false, modelOverride = null } = {}) {
     // Replace tool name references in content (applies to all files)
-    let convertedContent = content;
+    let convertedContent = filterRuntimeNotesForTarget(content, 'kilo');
     convertedContent = convertedContent.replace(/\bAskUserQuestion\b/g, 'question');
     convertedContent = convertedContent.replace(/\bSlashCommand\b/g, 'skill');
     convertedContent = convertedContent.replace(/\bTodoWrite\b/g, 'todowrite');
@@ -2945,6 +2960,7 @@ function restoreClaudeGlobalAtRefTilde(content, pathPrefix) {
 function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false, attribution = undefined) {
     const dirName = getDirName(runtime);
     const normalizedPathPrefix = pathPrefix.replace(/\/$/, '');
+    content = filterRuntimeNotesForTarget(content, runtime);
     // #1521: stamp runtime identity + use_worktrees=false for every non-Claude runtime
     // before brand-specific path rewrites, so the replace operates on the pristine
     // source line and is idempotent regardless of subsequent path substitutions.
@@ -3613,6 +3629,7 @@ module.exports = {
     neutralizeAgentReferences,
     convertClaudeCommandToOpencodeSkill,
     convertClaudeCommandToKiloSkill,
+    filterRuntimeNotesForTarget,
     // #2087 — opencode/kilo command-frontmatter converters, exported so the
     // layout-driven `convertedCommandsKind` can resolve them by name (routes the
     // opencode/kilo command install through the engine instead of the bespoke path).

package/gsd-core/bin/lib/runtime-artifact-install-plan.cjs

@@ -9,6 +9,7 @@
 // In .cts (CommonJS output) files, `require` is available as a global.
 const _require = require;
 const path = _require('node:path');
+const { tryWithinRootLexical } = _require('./security.cjs');
 // #2870: InstallScope is owned by install-scope.cts, not re-declared here.
 // `isGlobalScope` centralizes the `scope === 'global'` boolean projection
 // this module needs at `_computePathPrefix`'s `isGlobal: boolean` boundary
@@ -33,11 +34,19 @@ function assertDestWithinConfigHome(configDir, destSubpath) {
         throw new Error(`destSubpath "${destSubpath}" contains a NUL byte and is not valid`);
     }
     const root = path.resolve(configDir);
-    const resolved = path.resolve(configDir, destSubpath);
-    if (resolved === root || !resolved.startsWith(root + path.sep)) {
+    // `resolved === root` is a DELIBERATE ADDITIONAL rejection, separate from
+    // the containment decision: `tryWithinRootLexical` treats target === root
+    // as CONTAINED, but a destSubpath of "" (or one that resolves to configDir
+    // itself) must never be accepted here — this is the strict-subpath
+    // requirement Phase B of ADR-1239 imposes on third-party descriptors, and
+    // it prevents a descriptor from writing at configHome itself. Kept as its
+    // own check per ADR-4650 decision 6 (a wrapper may add its own conditions
+    // on top of the canonical predicate, never invert it).
+    const contained = tryWithinRootLexical(destSubpath, configDir);
+    if (contained === null || contained === root) {
         throw new Error(`destSubpath "${destSubpath}" must be a strict subpath of configHome "${configDir}" — not configHome itself or outside it (escapes configHome)`);
     }
-    return resolved;
+    return contained;
 }
 function errorMessage(err) {
     if (err instanceof Error)

package/gsd-core/bin/lib/runtime-artifact-layout.cjs

@@ -24,6 +24,7 @@ const node_os_1 = __importDefault(require("node:os"));
 // unless the top-level installRuntimeArtifacts call injected a `deps.fs`.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const installFsAdapter = require("./install-fs-adapter.cjs");
+const security_cjs_1 = require("./security.cjs");
 const { installFs, mkInstallTempDir } = installFsAdapter;
 // Reuse the install manifest's existing parser and streamed SHA-256
 // classification instead of deriving a second integrity implementation here.
@@ -101,10 +102,15 @@ function isReadableDirectory(candidate, routed) {
     }
 }
 function isPhysicallyConfinedTo(root, candidate) {
+    // ADR-4650 decision 6: lexical family on already-realpath'd operands — the
+    // surrounding try/catch must survive verbatim, since a non-existent
+    // candidate throwing out of realpathSync (not `tryWithinRootLexical`, which
+    // would accept it) is exactly the "incomplete manifest" signal this
+    // function's callers depend on.
     try {
         const physicalRoot = installFs().realpathSync(root);
         const physicalCandidate = installFs().realpathSync(candidate);
-        return physicalCandidate === physicalRoot || physicalCandidate.startsWith(physicalRoot + node_path_1.default.sep);
+        return (0, security_cjs_1.tryWithinRootLexical)(physicalCandidate, physicalRoot) !== null;
     }
     catch {
         return false;
@@ -167,9 +173,11 @@ function installedManifestIsComplete(runtimeConfigDir, required) {
                 const parts = key.split('/');
                 if (parts.some((part) => part === '' || part === '.' || part === '..'))
                     return false;
-                const candidate = node_path_1.default.resolve(runtimeConfigDir, ...parts);
-                const root = node_path_1.default.resolve(runtimeConfigDir);
-                if (!candidate.startsWith(root + node_path_1.default.sep))
+                // ADR-4650 decision 6: lexical family — the object is lstat'd (never
+                // stat'd) and refused if it is a symlink just below, so this gate must
+                // refuse rather than resolve.
+                const candidate = (0, security_cjs_1.tryWithinRootLexical)(parts.join('/'), runtimeConfigDir);
+                if (candidate === null || candidate === node_path_1.default.resolve(runtimeConfigDir))
                     return false;
                 const stat = io.lstatSync(candidate);
                 if (!stat.isFile() || stat.isSymbolicLink())
@@ -217,7 +225,7 @@ function providersShareRequiredRoots(left, right, required) {
         const overlap = (leftPath, rightPath) => {
             const relative = node_path_1.default.relative(leftPath, rightPath);
             return relative === '' ||
-                (relative !== '..' && !relative.startsWith(`..${node_path_1.default.sep}`) && !node_path_1.default.isAbsolute(relative));
+                (relative !== '..' && !relative.startsWith(`..${node_path_1.default.sep}`) && !node_path_1.default.isAbsolute(relative)); // allow-handrolled-containment: bidirectional physical-root overlap/identity check between two providers for dedup detection — not a security confinement gate on untrusted input
         };
         const physicalLeft = canonicalize(leftFs, leftRoot);
         const physicalRight = canonicalize(rightFs, rightRoot);