@jenga-ai/agent 3.6.0 → 4.1.0

package/scripts/rewrite-stale-skill-preambles.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""
+E50_S22_T02 — Rewrite the 37 stale generator-era body preambles to the canonical
+hand-edited framing.
+
+37 of the skills/j-*/SKILL.md files open their body (directly under the H1) with a
+two-paragraph preamble describing the retired twin-generation era: a bare
+skills/<name>/ "source" this file was supposedly generated from, and a warning to
+re-run scripts/generate-j-alias.sh instead of hand-editing. Both the bare
+directories (E50_S15) and the generator itself (E50_S14) are gone.
+
+This script:
+  1. Replaces that two-paragraph block, per file, with the canonical/hand-edited
+     framing already used by skills/j-do/SKILL.md and skills/j-dev-done/SKILL.md,
+     name-substituted.
+  2. Corrects skills/j-do/SKILL.md's and skills/j-dev-done/SKILL.md's own existing
+     warning text, which predates E50_S15 landing and still claims a bare copy is
+     "awaiting deletion" and warns against running a generator that no longer
+     exists at all.
+  3. Rewrites j-dev-done's "Known divergence" paragraph, which asserted (future
+     tense) that the bare /dev-done form "still exhibits" old behavior "until
+     E50_S15 deletes it" — E50_S15 already landed, so this is restated as a past-
+     tense historical note.
+
+Idempotent and safe to re-run (already-corrected files simply won't match and are
+skipped). Fails loudly (non-zero exit) if a file containing the trigger phrase
+"literal-directory-name duplicate" doesn't fit the fully-verified-uniform pattern,
+rather than silently leaving it unrewritten.
+
+Usage: scripts/rewrite-stale-skill-preambles.py [--dry-run]
+Run from the repository root.
+"""
+import glob
+import re
+import sys
+
+TRIGGER = "literal-directory-name duplicate"
+
+STALE_PREAMBLE_RE = re.compile(
+    r"This skill is a literal-directory-name duplicate of `skills/(?P<name>[a-z0-9-]+)/`\. "
+    r"It exists so that `/j-(?P=name)` \(and `j\.j-(?P=name)`\) give a guaranteed-unshadowed "
+    r"way to reach the same flow as `/(?P=name)`, even if a host tool's own built-in command "
+    r"of the same name would otherwise shadow or override the bare `/(?P=name)` alias "
+    r"\(Claude Code's native skill resolution is a literal-string, directory-name-based match "
+    r"— see `docs/skill-authoring\.md`'s \"Invocation Convention\"\)\.\n\n"
+    r"This file is generated/synced by `scripts/generate-j-alias\.sh (?P=name)` from "
+    r"`skills/(?P=name)/SKILL\.md` — do not hand-edit it; re-run the generator instead to "
+    r"pick up source changes\."
+)
+
+
+def canonical_replacement(name):
+    return (
+        f"`skills/j-{name}/` is the **canonical, hand-edited** directory for this skill, per "
+        "CLAUDE.md's \"The Canonical Naming Contract\" (the `E50` reopening of 2026-09-09, "
+        f"which promoted `skills/j-{name}/` from generated twin to sole canonical form). The "
+        "`j-` prefix is there for collision safety — a real directory under a distinct name, so "
+        "a host tool shipping its own same-named built-in command cannot shadow it (Claude "
+        "Code's native skill resolution is a literal-string, directory-name-based match; see "
+        "`docs/skill-authoring.md`'s \"Invocation Convention\").\n\n"
+        "> ⚠️ **`scripts/generate-j-alias.sh` was retired by `E50_S14` and no longer exists — "
+        "there is nothing to run.** This file was previously generated from a bare "
+        f"`skills/{name}/SKILL.md` source; `E50_S15` deleted that directory. This file is now "
+        "the sole canonical, hand-edited source for this skill — edit it directly."
+    )
+
+
+# --- j-do and j-dev-done: targeted corrections to their already-correct-model text ---
+
+J_DO_OLD = (
+    "> ⚠️ **Do not run `scripts/generate-j-alias.sh do` against this directory.** This file was\n"
+    "> previously generated from `skills/do/SKILL.md`, and carried a banner saying so. That relationship\n"
+    "> is inverted under the contract above: edits land here first, and `skills/do/` is the copy awaiting\n"
+    "> deletion by `E50_S15`. Regenerating would overwrite this file from the stale bare directory.\n"
+    "> CLAUDE.md states the same prohibition in general terms; this is the concrete instance of it."
+)
+J_DO_NEW = (
+    "> ⚠️ **`scripts/generate-j-alias.sh` was retired by `E50_S14` and no longer exists — there is\n"
+    "> nothing to run.** This file was previously generated from a bare `skills/do/SKILL.md` source;\n"
+    "> `E50_S15` deleted that directory. This file is now the sole canonical, hand-edited source for\n"
+    "> this skill — edit it directly."
+)
+
+J_DEV_DONE_OLD_WARNING = (
+    "> ⚠️ **Do not run `scripts/generate-j-alias.sh dev-done` against this directory.** This file was\n"
+    "> previously generated from `skills/dev-done/SKILL.md`, and carried a banner saying so. That\n"
+    "> relationship is inverted under the contract above: edits land here first, and `skills/dev-done/` is\n"
+    "> the copy awaiting deletion by `E50_S15`. Regenerating would overwrite this file from the stale bare\n"
+    "> directory and silently drop the post-sync commit step below. CLAUDE.md states the same prohibition\n"
+    "> in general terms; this is the concrete instance of it."
+)
+J_DEV_DONE_NEW_WARNING = (
+    "> ⚠️ **`scripts/generate-j-alias.sh` was retired by `E50_S14` and no longer exists — there is\n"
+    "> nothing to run.** This file was previously generated from a bare `skills/dev-done/SKILL.md`\n"
+    "> source; `E50_S15` deleted that directory. This file is now the sole canonical, hand-edited\n"
+    "> source for this skill — edit it directly."
+)
+
+J_DEV_DONE_OLD_DIVERGENCE = (
+    "> **Known divergence:** `skills/dev-done/` does **not** carry the post-sync commit step. Until\n"
+    "> `E50_S15` deletes it, the bare `/dev-done` form still exhibits the original\n"
+    "> leaves-the-tree-dirty behavior. Invoke `/j-dev-done` to get the fix."
+)
+J_DEV_DONE_NEW_DIVERGENCE = (
+    "> **Historical note:** before `E50_S15` deleted the bare `skills/dev-done/` directory, that\n"
+    "> copy did not carry the post-sync commit step below — this canonical file was already ahead\n"
+    "> of it. That divergence is now moot; there is no bare form left to diverge from."
+)
+
+
+def process_generic_file(path, dry_run=False):
+    with open(path, encoding="utf-8") as f:
+        content = f.read()
+    if TRIGGER not in content:
+        return None
+    match = STALE_PREAMBLE_RE.search(content)
+    if not match:
+        return "unmatched"
+    name = match.group("name")
+    new_content = content[: match.start()] + canonical_replacement(name) + content[match.end() :]
+    if not dry_run:
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(new_content)
+    return True
+
+
+def process_special_file(path, old_new_pairs, dry_run=False):
+    with open(path, encoding="utf-8") as f:
+        content = f.read()
+    changed = False
+    for old, new in old_new_pairs:
+        if old not in content:
+            print(f"ERROR: expected text not found verbatim in {path}:", file=sys.stderr)
+            print(repr(old), file=sys.stderr)
+            sys.exit(1)
+        content = content.replace(old, new, 1)
+        changed = True
+    if changed and not dry_run:
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(content)
+    return changed
+
+
+def main():
+    dry_run = "--dry-run" in sys.argv
+    files = sorted(glob.glob("skills/j-*/SKILL.md"))
+    changed_files = []
+    unmatched = []
+
+    for path in files:
+        if path in ("skills/j-do/SKILL.md", "skills/j-dev-done/SKILL.md"):
+            continue
+        result = process_generic_file(path, dry_run=dry_run)
+        if result == "unmatched":
+            unmatched.append(path)
+        elif result:
+            changed_files.append(path)
+
+    if process_special_file("skills/j-do/SKILL.md", [(J_DO_OLD, J_DO_NEW)], dry_run=dry_run):
+        changed_files.append("skills/j-do/SKILL.md")
+
+    if process_special_file(
+        "skills/j-dev-done/SKILL.md",
+        [
+            (J_DEV_DONE_OLD_WARNING, J_DEV_DONE_NEW_WARNING),
+            (J_DEV_DONE_OLD_DIVERGENCE, J_DEV_DONE_NEW_DIVERGENCE),
+        ],
+        dry_run=dry_run,
+    ):
+        changed_files.append("skills/j-dev-done/SKILL.md")
+
+    print(f"Changed {len(changed_files)} file(s):")
+    for p in sorted(changed_files):
+        print(f"  {p}")
+
+    if unmatched:
+        print(
+            f"\nERROR: {len(unmatched)} file(s) contain the trigger phrase but did not match the "
+            "expected preamble pattern — investigate manually:",
+            file=sys.stderr,
+        )
+        for p in unmatched:
+            print(f"  {p}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/strip-polyfill-frontmatter.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""
+E50_S22_T01 — Strip retired-era polyfill boilerplate from j-* skill frontmatter.
+
+For every skills/j-*/SKILL.md file (excluding the 6 natively-authored skills, which
+never carried this boilerplate), this script:
+
+  1. Strips the leading prefix "Polyfill alias of the <name> skill under a
+     collision-safe directory name. Identical behavior to /<name> — " from the
+     frontmatter `description:` field, preserving everything after it verbatim.
+  2. Strips the trailing generic clause "Use when the bare /<name> form is shadowed
+     by another tool's own built-in command of the same name." if present verbatim.
+     (skills/j-init/SKILL.md carries a different, substantive custom clause about a
+     real GitHub Copilot collision — that one is intentionally left untouched.)
+  3. Special-cases skills/j-idea/SKILL.md: also strips the leftover E50_S21
+     "DEPRECATED - use the prefixed 'j-idea' skill instead. " clause.
+  4. Removes any "  - polyfill" line from the frontmatter `keywords:` block.
+
+Idempotent and safe to re-run. Reports every file it changes and fails loudly
+(non-zero exit) if a file matching the target set doesn't fit the expected pattern,
+rather than silently skipping it.
+
+Usage: scripts/strip-polyfill-frontmatter.py [--dry-run]
+Run from the repository root.
+"""
+import glob
+import json
+import re
+import sys
+
+try:
+    import yaml
+except ImportError:
+    yaml = None
+
+NATIVE_SKILLS = {
+    "j-cloud-connect",
+    "j-dashboard",
+    "j-dashboard-share",
+    "j-gitignore",
+    "j-playbook",
+    "j-playbook-new",
+}
+
+PREFIX_RE = re.compile(
+    r"^description: Polyfill alias of the .+? skill under a collision-safe directory name\. "
+    r"Identical behavior to /\S+ — "
+)
+GENERIC_SUFFIX_RE = re.compile(
+    r" Use when the bare /\S+ form is shadowed by another tool's own built-in command of the same name\.$"
+)
+IDEA_DEPRECATED_RE = re.compile(
+    r"^description: DEPRECATED - use the prefixed 'j-idea' skill instead\. "
+)
+# Matches the preceding newline too, so removal doesn't leave a blank line behind
+# (whether "polyfill" sits mid-list or is the last entry right before the closing "---").
+POLYFILL_KEYWORD_RE = re.compile(r"\n[ \t]*-[ \t]*polyfill[ \t]*(?=\n)")
+
+
+def requote_if_unsafe(line):
+    """
+    Stripping the polyfill prefix can leave a plain-scalar description value that
+    starts with a YAML-special character (e.g. j-deep-dive's substantive text is
+    the literal ">.", which YAML reads as an invalid block-scalar indicator once it
+    is no longer preceded by other text). If the resulting `description: <value>`
+    line doesn't parse as valid YAML, re-render it as a double-quoted (JSON-style,
+    which is also valid YAML) scalar instead, preserving the value verbatim.
+    """
+    if yaml is None or not line.startswith("description: "):
+        return line
+    value = line[len("description: ") :]
+    try:
+        yaml.safe_load(line)
+        return line
+    except yaml.YAMLError:
+        return "description: " + json.dumps(value)
+
+
+def process_file(path, dry_run=False):
+    with open(path, encoding="utf-8") as f:
+        content = f.read()
+
+    if not content.startswith("---\n"):
+        return None  # no frontmatter, nothing to do
+    end = content.find("\n---", 4)
+    if end == -1:
+        return None
+    frontmatter = content[: end + 4]
+    rest = content[end + 4 :]
+
+    lines = frontmatter.split("\n")
+    changed = False
+    desc_found = False
+
+    for i, line in enumerate(lines):
+        if line.startswith("description:"):
+            desc_found = True
+            original = line
+            new_line = PREFIX_RE.sub("description: ", line)
+            if new_line == line:
+                # Not the polyfill-prefixed shape — leave untouched (native skills).
+                continue
+            new_line = GENERIC_SUFFIX_RE.sub("", new_line)
+            if "/j-idea/" in path or path.endswith("j-idea/SKILL.md"):
+                new_line = IDEA_DEPRECATED_RE.sub("description: ", new_line)
+            new_line = requote_if_unsafe(new_line)
+            if new_line != original:
+                lines[i] = new_line
+                changed = True
+
+    new_frontmatter = "\n".join(lines)
+
+    # Strip "  - polyfill" keyword lines (including their preceding newline, so no
+    # blank line is left behind regardless of position in the list).
+    if POLYFILL_KEYWORD_RE.search(new_frontmatter):
+        new_frontmatter = POLYFILL_KEYWORD_RE.sub("", new_frontmatter)
+        changed = True
+
+    if not changed:
+        return False
+
+    new_content = new_frontmatter + rest
+    if not dry_run:
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(new_content)
+    return True
+
+
+def main():
+    dry_run = "--dry-run" in sys.argv
+    files = sorted(glob.glob("skills/j-*/SKILL.md"))
+    changed_files = []
+    unmatched_polyfill_prefix = []
+
+    for path in files:
+        skill_dir = path.split("/")[1]
+        if skill_dir in NATIVE_SKILLS:
+            continue
+
+        with open(path, encoding="utf-8") as f:
+            head = f.read(4000)
+        has_prefix = "Polyfill alias of the" in head
+
+        result = process_file(path, dry_run=dry_run)
+        if has_prefix and result is False:
+            unmatched_polyfill_prefix.append(path)
+        elif result:
+            changed_files.append(path)
+
+    print(f"Changed {len(changed_files)} file(s):")
+    for p in changed_files:
+        print(f"  {p}")
+
+    if unmatched_polyfill_prefix:
+        print(
+            f"\nERROR: {len(unmatched_polyfill_prefix)} file(s) contain 'Polyfill alias of the' "
+            "but did not match the expected description pattern — investigate manually:",
+            file=sys.stderr,
+        )
+        for p in unmatched_polyfill_prefix:
+            print(f"  {p}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/todo_manager.sh

@@ -3,7 +3,22 @@
 # Run from the repository root.
 
 TODO_FILE="project/todo.md"
-TEMPLATE="skills/j-todo/assets/todo_template.md"
+
+# PACKAGE_ROOT locates the package-shipped todo template (skills/j-todo/assets/).
+# This script always lives at scripts/, one level below the package root, in
+# both layouts:
+#   - this monorepo checkout
+#   - a consumer install, inside node_modules/@jenga-ai/agent/
+# BASH_SOURCE-derived resolution is exact in both cases (same reasoning as
+# scripts/jenga-permission-level-switch.sh's PACKAGE_ROOT derivation), with a
+# defensive node_modules-relative fallback matching the PKG_ROOT convention in
+# skills/init/scripts/init.sh, in case BASH_SOURCE resolution is ever
+# unavailable (e.g. the script is sourced rather than executed).
+PACKAGE_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TEMPLATE="$PACKAGE_ROOT/skills/j-todo/assets/todo_template.md"
+if [ ! -f "$TEMPLATE" ]; then
+  TEMPLATE="node_modules/@jenga-ai/agent/skills/j-todo/assets/todo_template.md"
+fi
 
 usage() {
   cat >&2 <<EOF