From 4ade4450bf3d74db94ef091fce612cf8bd213bcf Mon Sep 17 00:00:00 2001
From: ClintonEmok <54935030+ClintonEmok@users.noreply.github.com>
Date: Sun, 23 Aug 2026 19:44:16 +0200
Subject: [PATCH] docs(skills): document programmatic-write scope cut in
 skills_guard module docstring
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Enough1122's review on #92249 asked whether language write APIs
(Python open('w')/write_text/os.replace/shutil, Node fs.writeFileSync/
appendFile) are covered by the agent-config persistence tiers. They are
not: those tiers score shell redirection, sed -i, and imperative prose
only; language-API calls surface just the informational *_ref finding.

Static regexes cannot tie a dynamically-built path to the config-file
destination without executing the skill, so this is a documented scope
cut rather than missing coverage — runtime install gates remain the
backstop. Scoring behavior is unchanged, so SCANNER_VERSION stays at
skills-guard-v2 and cached verdicts remain valid.

Refs #92249
---
 tools/skills_guard.py | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/tools/skills_guard.py b/tools/skills_guard.py
index 2605136d09..65062d53f7 100644
--- a/tools/skills_guard.py
+++ b/tools/skills_guard.py
@@ -20,6 +20,20 @@ Usage:
     allowed, reason = should_allow_install(result)
     if not allowed:
         print(format_scan_report(result))
+
+Known limitation — programmatic writes (out of scope for this static pass):
+the agent-config persistence tiers score shell write mechanics
+(">>" redirection, "sed -i") and imperative modification prose only.
+Language write APIs in bundled scripts — Python open(..., 'w'/'a'),
+pathlib.Path.write_text(), os.replace(), shutil.copy*, and Node
+fs.writeFileSync()/appendFile() — aimed at agent-config files surface
+only the low-severity *_ref finding, never a scored persistence tier.
+Static regexes cannot reliably tie such a call to the config-file
+destination (paths may be built dynamically) without executing the
+skill, so language-API persistence is left to runtime gates (install
+confirmation, sandboxing). If coverage is added later, it belongs as a
+fourth "mechanical" tier next to agent_config_mod_shell, requiring the
+config-file name as a literal argument at the call site.
 """
 
 import re