Dead code: two helpers exported but never called

createNamespacedFlatRuleOperations (line 120) and createRemappedOperation (line 107) are exported in module.exports (lines 304–305) but have zero callers anywhere in the codebase. Both Cursor and Antigravity adapters call createFlatRuleOperations directly. Shipping unused exports pollutes the public API of the module and can mislead future contributors about which helper to use when adding a new adapter.

If these are intentionally reserved for future adapters, a code comment would clarify intent. Otherwise they should be removed to keep the surface clean.

Unreachable previousJson fallback inside render-template uninstall

The render-template branch first tries getOperationPreviousContent (looks for previousContent, originalContent, backupContent). If that fails, it falls through to getOperationPreviousJson (looks for previousValue, previousJson, originalValue) and writes the result through formatJson (pretty-printed JSON with trailing newline).

render-template operations store their previous state as raw text in previousContent; the previousValue/previousJson keys are semantically associated with merge-json operations. No test exercises this path and no code path currently writes a previousValue on a render-template operation, making these six lines effectively dead. At best it is confusing; at worst it could silently re-format a file that happened to contain valid JSON as a side-effect of some unexpected field.

Consider removing the previousJson fallback from the render-template branch, or leaving an explicit comment explaining under what future conditions it would be reached.

Flat-name collision when a namespace contains a hyphenated filename

The flattening scheme used in createFlatRuleOperations produces the destination name ${namespace}-${relativeFile.replace(/\//g, '-')}. This means rules/typescript/pre-commit.md and rules/typescript-pre/commit.md would both resolve to typescript-pre-commit.md. With the current rule tree this is unlikely to collide, but the algorithm provides no collision detection and will silently overwrite the earlier operation without any warning if the filesystem produces them in alphabetical order.

A low-cost guard would be to track destination paths as a Set and warn (or throw) on duplicate entries before returning the operations list.

const seen = new Set();
// ... inside the loop before push:
if (seen.has(destPath)) {
  throw new Error(`Flat-rule name collision: ${destPath}`);
}
seen.add(destPath);

deepRemoveJsonSubset uses strict array-length equality; silently skips managed arrays if they were extended

jsonContainsSubset for arrays requires actualValue.length === expectedValue.length. This means that if a user appends items to a managed array after installation (e.g. they add an extra hook to a JSON hooks file), deepRemoveJsonSubset will leave the entire array key intact during uninstall instead of removing the managed value, resulting in orphaned managed configuration.

This is a conservative choice, but it's worth documenting explicitly (a comment in the code or in the PR description) so future maintainers don't assume all managed arrays are reliably cleaned up. If the intent is to remove managed arrays only when they match exactly, a comment would also clarify why the array branch doesn't attempt partial de-merge.

P2: Fallback validation for source.repoVersion/source.repoCommit does not match the schema, causing schema-inconsistent state acceptance/rejection when Ajv is unavailable.

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/lib/install-state.js, line 171:

<comment>Fallback validation for `source.repoVersion`/`source.repoCommit` does not match the schema, causing schema-inconsistent state acceptance/rejection when Ajv is unavailable.</comment>

<file context>
@@ -19,12 +36,188 @@ function getValidator() {
+      pushError('/source', 'must be object');
+    } else {
+      validateNoAdditionalProperties(source, '/source', ['repoVersion', 'repoCommit', 'manifestVersion']);
+      validateOptionalString(source.repoVersion, '/source/repoVersion');
+      validateOptionalString(source.repoCommit, '/source/repoCommit');
+      if (!Number.isInteger(source.manifestVersion) || source.manifestVersion < 1) {
</file context>

Avoid duplicate cursor rule destinations in manifest plans

Flattening rules into .cursor/rules/*.md creates destination collisions with the platform-configs module, which also copies .cursor/rules/*.md via the .cursor path; because those source files differ, a fresh manifest install (for example profile core, which includes both modules) is immediately marked drifted by doctor and repair can repeatedly rewrite these files. The adapter should prevent emitting overlapping destinations for these two module sources.

Useful? React with 👍 / 👎.

Recover from invalid JSON when repairing merge-json ops

Repairing a managed merge-json operation always parses the current destination file, so if a user has drifted that file into invalid JSON (for example by hand-editing hooks.json), repair throws a parse error and returns status: error instead of restoring managed content. This blocks the command in a common remediation scenario where repair is expected to recover from malformed managed files.

Useful? React with 👍 / 👎.

⚠️ Potential issue | 🔴 Critical

Reject recorded operations that escape the discovered target.

The new recorded-operation flow trusts state.target.* and every recorded destinationPath from the on-disk install-state. A repo-supplied .cursor/ecc-install-state.json can therefore point outside the current adapter root and make repair overwrite or uninstall delete arbitrary user files; copy-file repairs can also read outside context.repoRoot via .. in sourceRelativePath.

+function assertPathInside(basePath, candidatePath, label) {
+  const relative = path.relative(path.resolve(basePath), path.resolve(candidatePath));
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`${label} escapes ${basePath}: ${candidatePath}`);
+  }
+}
+
+function assertRecordedOperationsSafe(record, repoRoot, operations) {
+  for (const operation of operations) {
+    assertPathInside(record.targetRoot, operation.destinationPath, 'destinationPath');
+    if (repoRoot && operation.kind === 'copy-file') {
+      assertPathInside(
+        repoRoot,
+        path.join(repoRoot, operation.sourceRelativePath || ''),
+        'sourceRelativePath'
+      );
+    }
+  }
+}
...
-    const statePreview = buildRecordedStatePreview(state, context, operations);
+    assertRecordedOperationsSafe(record, context.repoRoot, operations);
+    const statePreview = buildRecordedStatePreview(state, record, context, operations);
...
-      targetRoot: state.target.root,
-      installRoot: state.target.root,
-      installStatePath: state.target.installStatePath,
+      targetRoot: record.targetRoot,
+      installRoot: record.targetRoot,
+      installStatePath: record.installStatePath,
...
-      const operations = getManagedOperations(state);
+      const operations = getManagedOperations(state);
+      assertRecordedOperationsSafe(record, null, operations);
...
-      if (fs.existsSync(state.target.installStatePath)) {
-        fs.rmSync(state.target.installStatePath, { force: true });
-        removedPaths.push(state.target.installStatePath);
-        cleanupTargets.push(state.target.installStatePath);
+      if (fs.existsSync(record.installStatePath)) {
+        fs.rmSync(record.installStatePath, { force: true });
+        removedPaths.push(record.installStatePath);
+        cleanupTargets.push(record.installStatePath);

Also applies to: 1049-1052, 1161-1167

Verify each finding against the current code and only fix it if needed.

In `@scripts/lib/install-lifecycle.js` around lines 946 - 948, The code currently
trusts recorded operations loaded by hydrateRecordedOperations (used in the
branch gated by state.request.legacyMode or shouldRepairFromRecordedOperations)
and can allow destinationPath or sourceRelativePath to escape the adapter root;
update hydrateRecordedOperations or immediately after it (before
buildRecordedStatePreview and before any filesystem action elsewhere such as the
repair/uninstall/copy-file flows) to validate and reject any recorded operation
whose resolved absolute path is outside the intended root (context.repoRoot or
the resolved state.target root): resolve paths (no string-only checks),
normalize/realpath them, ensure they start with the allowed root, and either
filter out or throw a clear error for offending operations; apply the same
validation where recorded operations are later consumed (e.g., the
repair/uninstall/copy handlers) so operations cannot escape via ../ or
repo-supplied state files.

⚠️ Potential issue | 🟠 Major

Make the fallback source validation match the schema.

The inline validator still treats source.repoVersion and source.repoCommit as optional here, so the same install-state can be accepted in bare environments and rejected once the schema-backed path is available. That makes readInstallState() environment-dependent for malformed state files.

-      validateOptionalString(source.repoVersion, '/source/repoVersion');
-      validateOptionalString(source.repoCommit, '/source/repoCommit');
+      if (
+        !Object.prototype.hasOwnProperty.call(source, 'repoVersion')
+        || (source.repoVersion !== null && typeof source.repoVersion !== 'string')
+      ) {
+        pushError('/source/repoVersion', 'must be string or null');
+      }
+      if (
+        !Object.prototype.hasOwnProperty.call(source, 'repoCommit')
+        || (source.repoCommit !== null && typeof source.repoCommit !== 'string')
+      ) {
+        pushError('/source/repoCommit', 'must be string or null');
+      }

Verify each finding against the current code and only fix it if needed.

In `@scripts/lib/install-state.js` around lines 166 - 175, The fallback validation
for the install state treats source.repoVersion and source.repoCommit as
optional but the schema requires them; in the source validation block (variable
"source") replace the calls to validateOptionalString(source.repoVersion,
'/source/repoVersion') and validateOptionalString(source.repoCommit,
'/source/repoCommit') with the required-string validator used elsewhere (e.g.,
validateString or validateRequiredString) so that missing or non-string
repoVersion/repoCommit will call pushError; keep the existing
validateNoAdditionalProperties and the manifestVersion integer check intact and
ensure readInstallState() behavior is deterministic across environments.

⚠️ Potential issue | 🟠 Major

The flattened rule filename mapping is still ambiguous.

Replacing / with - is not injective: a/b-c.md, a-b/c.md, and a top-level a-b-c.md all collapse to the same destination name. One generated operation will silently win and another rule file will disappear.

+function flattenRulePath(...segments) {
+  return segments
+    .flatMap(segment => normalizeRelativePath(segment).split('/'))
+    .map(segment => segment.replace(/-/g, '--'))
+    .join('-');
+}
...
-        const flattenedFileName = `${namespace}-${normalizeRelativePath(relativeFile).replace(/\//g, '-')}`;
+        const flattenedFileName = flattenRulePath(namespace, relativeFile);
...
-        destinationPath: path.join(targetRulesDir, entry.name),
+        destinationPath: path.join(targetRulesDir, flattenRulePath(entry.name)),
...
-        const flattenedFileName = `${namespace}-${normalizeRelativePath(relativeFile).replace(/\//g, '-')}`;
+        const flattenedFileName = flattenRulePath(namespace, relativeFile);
...
-        destinationPath: path.join(destinationDir, entry.name),
+        destinationPath: path.join(destinationDir, flattenRulePath(entry.name)),

Also applies to: 180-197

Verify each finding against the current code and only fix it if needed.

In `@scripts/lib/install-targets/helpers.js` around lines 138 - 156, The flattened
filename mapping can collide; instead of naively replacing '/' with '-', change
the flattening logic used around listRelativeFiles/normalizeRelativePath when
building flattenedFileName (and the analogous code at the other block around
createManagedOperation for files) to encode each path segment to preserve
boundaries (e.g., split normalizeRelativePath(relativeFile) into segments and
escape each segment with a reversible encoding such as encodeURIComponent or a
length-prefixed scheme, then join with a fixed separator) and additionally keep
a Set of generated destination names to detect duplicates and throw a clear
error if one occurs; apply the same change where sourceRelativePath is
constructed for single files so createManagedOperation receives unique,
unambiguous destinationPath values.