@softspark/ai-toolkit 2.1.3 → 2.2.0

package/AGENTS.md

@@ -578,28 +578,98 @@ Derived from the immutable safety constitution (5 articles):
 - **No Secrets in Code**: Never commit credentials, API keys, or sensitive configuration values
 <!-- TOOLKIT:ai-toolkit END -->
 
-<!-- TOOLKIT:jira-rules START -->
+<!-- TOOLKIT:jira-mcp START -->
 <!-- Auto-injected by ai-toolkit. Re-run to update. -->
 
 # Jira MCP Server
 
-Tools: `sync_tasks`, `read_cached_tasks`, `update_task_status`, `add_task_comment`, `reassign_task`, `get_task_statuses`, `get_task_details`, `log_task_time`, `get_task_time_tracking`
+Tools: `sync_tasks`, `read_cached_tasks`, `update_task_status`, `update_task`, `add_task_comment`, `reassign_task`, `get_task_statuses`, `get_task_details`, `get_project_language`, `log_task_time`, `get_task_time_tracking`, `list_comment_templates`, `add_templated_comment`, `create_task`, `search_tasks`
 
 ## Key Rules
 
-- **Always `sync_tasks` first** before reading — cache may be stale.
-- **Time format:** `"2h 30m"` — hours and minutes only, never days.
+- **Always `sync_tasks` first** before reading -- cache may be stale.
+- **Language first:** before writing ANY comment, description, or task content, call `get_project_language(project_key)` or check the `language` field in `get_task_details` response. Write ALL content in the project's configured language. Never assume Polish or English — always check first.
+- **Time format:** `"2h 30m"` -- hours and minutes only, never days.
 - **Status changes:** call `get_task_statuses` first to check valid transitions.
 - **Multi-instance:** project key determines which Jira instance is used (mapped in config.json).
+- **Comments are ADF:** `add_task_comment` converts markdown to ADF (Atlassian Document Format) automatically.
+- **Templates:** use `list_comment_templates` to discover available templates, then `add_templated_comment` with `template_id` + `variables`.
 
 ## Workflow
 
-1. `sync_tasks(jql="assignee=currentUser() AND status!=Done")` — fetch fresh
-2. `read_cached_tasks()` — work offline
-3. `get_task_details(task_key="PROJ-123")` — deep dive
-4. `update_task_status(...)` / `add_task_comment(...)` / `log_task_time(...)` — mutate
-
-<!-- TOOLKIT:jira-rules END -->
+1. `sync_tasks(jql="assignee=currentUser() AND status!=Done")` -- fetch fresh
+2. `read_cached_tasks()` -- work offline
+3. `get_task_details(task_key="PROJ-123")` -- deep dive (description + comments as markdown)
+4. `update_task_status(...)` / `add_task_comment(...)` / `log_task_time(...)` -- mutate
+
+## Comment Templates (8 built-in)
+
+| ID | Use for |
+|----|---------|
+| `status-update` | Progress report with completed/next/blockers |
+| `blocker-notification` | Escalate blocking issue |
+| `handoff-transition` | Task handoff between people |
+| `review-request` | Request code review |
+| `sprint-update` | Sprint progress report |
+| `bug-report` | Structured bug report |
+| `deployment-note` | Deployment documentation |
+| `time-log-summary` | Time logging with description |
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `jira-mcp config init` | Initialize global config (~/.softspark/jira-mcp/) |
+| `jira-mcp config add-project <key> <url>` | Add Jira project mapping |
+| `jira-mcp config remove-project <key>` | Remove a project |
+| `jira-mcp config list-projects` | Show configured projects with language |
+| `jira-mcp config set-default <key>` | Set default project |
+| `jira-mcp config set-credentials` | Set API credentials |
+| `jira-mcp config set-language <lang>` | Set global default language |
+| `jira-mcp config set-project-language <key> <lang>` | Set language for a specific project |
+| `jira-mcp create <path>` | Create tasks from template (dry-run default) |
+| `jira-mcp create-monthly` | Create monthly admin tasks |
+| `jira-mcp cache sync-users` | Cache user list for reassignment |
+| `jira-mcp cache sync-workflows` | Cache status transitions |
+| `jira-mcp cache list-users` | Show cached users |
+| `jira-mcp cache list-workflows` | Show cached workflows |
+
+## Architecture
+
+Four layers -- each depends only on layers below:
+
+1. **Types & Config** (`config/`, `errors/`, `*/types.ts`) -- pure data, zero runtime deps
+2. **Infrastructure** (`connector/`, `cache/`, `adf/`, `templates/`) -- I/O and external APIs
+3. **Business Logic** (`operations/`, `bulk/`) -- orchestrates infrastructure
+4. **Entry Points** (`tools/`, `cli/`, `server.ts`) -- thin dispatchers
+
+## Coding Conventions
+
+- **Strict TypeScript**: `strict: true`, NO `any`, `readonly` interfaces, `import type`, `.js` imports
+- **Zod schemas** for all external data: `type Foo = z.infer<typeof FooSchema>`
+- **Error classes**: extend `JiraMcpError` with `code` property
+- **ADF round-trip**: `markdownToAdf()` for writes, `adfToMarkdown()` for reads -- NEVER throw
+- **InstancePool**: singleton, lazy connectors, dedup by URL
+- **Dual-write**: after Jira mutation, update local cache, return API result
+- **Dry-run default**: `--execute` required for destructive operations
+- **DI pattern**: handlers accept `deps?` parameter for testing
+- **Config path**: ALWAYS `~/.softspark/jira-mcp/` via `GLOBAL_CONFIG_DIR` -- no manual config, no env vars in MCP client setup
+- **SoftSpark standard**: all open-source tools use `~/.softspark/<tool-name>/` -- see SOP in rag-mcp `kb/procedures/softspark-config-standard.md`
+
+## Testing
+
+- **Vitest**: 70% coverage threshold, `vi.fn()` for mocks
+- **No real Jira API calls** in tests, use `tests/fixtures/mocks.ts`
+- **Filesystem tests**: `os.tmpdir()` + `mkdtemp()`, NEVER write to `~/.softspark/`
+- Quick pre-commit: `npm run typecheck && npm run lint && npm test && npm run build`
+
+## KB & SOPs
+
+- `kb/reference/` -- architecture, api, configuration, adf, caching, templates
+- `kb/howto/` -- setup, multi-instance, cli-usage
+- `kb/procedures/` -- sop-pre-commit, sop-release, sop-post-release-testing
+
+<!-- TOOLKIT:jira-mcp END -->
 
 <!-- TOOLKIT:rag-mcp-rules START -->
 <!-- Auto-injected by ai-toolkit. Re-run to update. -->

package/CHANGELOG.md

@@ -7,6 +7,20 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v2.2.0 — URL Rules & Registry Safety (2026-04-14)
+
+### Added
+- **URL rule registration** — `ai-toolkit add-rule https://...` registers rules from HTTPS URLs. URL-sourced rules are tracked in `rules/sources.json` and auto-refreshed on every `ai-toolkit update`. Falls back to cached local copy on network failure.
+- **Version consistency validation** — `validate.py --strict` now cross-checks `package.json`, `manifest.json`, and `plugin.json` versions match
+
+### Fixed
+- **Project registry race condition** — parallel `install --local` during `ai-toolkit update` could silently drop registry entries. Fixed with `fcntl.flock` exclusive lock, atomic writes (tempfile + rename), and deferred sequential registration after parallel phase.
+- **Version drift** — `manifest.json` and `plugin.json` were stuck at 1.9.0 since v2.0.0, now synced
+- **Language rules count** — ARCHITECTURE.md claimed 70 files, actual is 68
+- **Skills catalog tiers** — added missing Tier 1.5 (planning pipeline + design/architecture)
+
+---
+
 ## v2.1.3 — Idempotent Update Fix (2026-04-13)
 
 ### Fixed

package/README.md

@@ -6,7 +6,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-92-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-598%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-604%20passing-success)](tests/)
 
 ---
 
@@ -142,7 +142,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (598 tests)
+├── tests/               # Bats test suite (604 tests)
 └── CHANGELOG.md
 ```
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "1.9.0",
+  "version": "2.2.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -304,7 +304,7 @@ Lead Session (You)
 ### MCP Templates (25)
 `app/plugins/mcp-templates/` ships 25 ready-to-use MCP server config templates (filesystems, databases, GitHub, Slack, etc.). Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
 
-### Language Rules (70 files, 13 languages)
+### Language Rules (68 files, 13 languages)
 `app/rules/` contains per-language coding rules. Supported languages: TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby, and common (shared). Auto-detected from project files via `--auto-detect` or selected with `--modules rules-<lang>`.
 
 Language rules are propagated to **all configured editors** — not just Claude. `dir_rules_shared.build_language_rules()` reads `app/rules/<lang>/*.md`, strips frontmatter, and returns combined content per language. Each directory-based generator (Cursor, Windsurf, Cline, Roo, Augment, Antigravity, Codex) emits `ai-toolkit-lang-<lang>` files in its native format. Registered custom rules (`~/.softspark/ai-toolkit/rules/`) are similarly propagated as `ai-toolkit-custom-<name>` files via `build_registered_rules()`.

package/bin/ai-toolkit.js

@@ -63,7 +63,7 @@ const COMMANDS = {
   status: 'Show installed modules, version, and profile from state.json',
   reset: 'Wipe and recreate project-local configs from scratch (requires --local)',
   uninstall: 'Remove ai-toolkit from ~/.claude/',
-  'add-rule': 'Register a rule file in ~/.softspark/ai-toolkit/rules/ (applied on every install/update)',
+  'add-rule': 'Register a rule file or URL in ~/.softspark/ai-toolkit/rules/ (URL rules auto-refresh on update)',
   'remove-rule': 'Unregister a rule from ~/.softspark/ai-toolkit/rules/ and remove its block from CLAUDE.md',
   'inject-hook': 'Inject external hooks into ~/.claude/settings.json (tagged with _source for idempotent updates)',
   'remove-hook': 'Remove injected hooks by source name from ~/.claude/settings.json',
@@ -232,8 +232,8 @@ function showHelp() {
   console.log('  <source-name>   Source tag to remove (derived from hooks filename stem)');
   console.log('  [target-dir]    Target dir containing .claude/settings.json (default: $HOME)');
   console.log('\nOptions for add-rule:');
-  console.log('  <rule-file>     Path to .md rule file to register globally');
-  console.log('  [rule-name]     Override rule name (default: filename without .md)');
+  console.log('  <rule-file>     Path to .md rule file or HTTPS URL to register globally');
+  console.log('  [rule-name]     Override rule name (default: filename/URL stem without .md)');
   console.log('\nOptions for plugin:');
   console.log('  install <name>  Install a plugin pack (--editor claude|codex|all)');
   console.log('  install --all   Install all available plugin packs for selected editor(s)');
@@ -333,16 +333,18 @@ function handleRemoveRule(args) {
 }
 
 /**
- * Handle `ai-toolkit add-rule` -- validates rule file, resolves absolute path.
+ * Handle `ai-toolkit add-rule` -- validates rule file/URL, resolves absolute path.
  * @param {string[]} args
  */
 function handleAddRule(args) {
   const ruleFile = args[0];
   if (!ruleFile) {
-    console.error('Usage: ai-toolkit add-rule <rule-file> [rule-name]');
+    console.error('Usage: ai-toolkit add-rule <rule-file-or-url> [rule-name]');
     process.exit(1);
   }
-  const absRuleFile = path.resolve(CWD, ruleFile);
+  // Pass URLs through directly (don't resolve as filesystem path)
+  const isUrl = ruleFile.startsWith('https://') || ruleFile.startsWith('http://');
+  const absRuleFile = isUrl ? ruleFile : path.resolve(CWD, ruleFile);
   const ruleName = args[1];
   run(scriptPath('add_rule.py'), ruleName ? [absRuleFile, ruleName] : [absRuleFile]);
 }

package/kb/procedures/maintenance-sop.md

@@ -319,6 +319,7 @@ Follow this sequence before every `npm publish` / `git tag`:
 
 ```bash
 # Edit package.json version field (semver: X.Y.Z)
+# Sync package-lock.json: npm install --package-lock-only
 # Add entry to CHANGELOG.md
 ```
 

package/kb/procedures/release-preparation-sop.md

@@ -108,8 +108,9 @@ The canonical version lives in `package.json`. These files **must** match:
 | `README.md` | Badge counts, "What You Get" table |
 | `app/ARCHITECTURE.md` | Section headings with counts |
 
-> **Tip:** `validate.py --strict` and `npm test` (metadata contract tests) catch
-> count drift automatically. If tests pass, counts are correct.
+> **Tip:** `validate.py --strict` catches count drift AND version mismatches
+> (package.json vs manifest.json vs plugin.json) automatically.
+> If validation passes, counts and versions are correct.
 
 ### Verification command
 

package/kb/reference/skills-catalog.md

@@ -17,7 +17,9 @@ All functionality is unified under skills. Task and hybrid skills are user-invoc
 
 | Tier | Skills | When |
 |------|--------|------|
-| **1 — Quick single-agent** | `/debug`, `/review`, `/refactor`, `/analyze`, `/docs`, `/plan`, `/explain` | One concern, fast |
+| **1 — Quick single-agent** | `/debug`, `/review`, `/refactor`, `/analyze`, `/docs`, `/plan`, `/explain`, `/tdd`, `/grill-me`, `/triage-issue` | One concern, fast |
+| **1.5 — Product planning** | `/write-a-prd` → `/prd-to-plan` → `/prd-to-issues` | Interview-driven PRD → vertical-slice plan → GitHub issues |
+| **1.5 — Design & architecture** | `/design-an-interface`, `/architecture-audit`, `/refactor-plan`, `/ubiquitous-language`, `/qa-session` | Parallel sub-agent exploration |
 | **2 — Multi-agent workflow** | `/workflow <type>` | Cross-cutting task with known pattern |
 | **3 — Custom parallelism** | `/orchestrate`, `/swarm` | No predefined workflow matches |
 

package/llms-full.txt

@@ -3441,6 +3441,7 @@ Follow this sequence before every `npm publish` / `git tag`:
 
 ```bash
 # Edit package.json version field (semver: X.Y.Z)
+# Sync package-lock.json: npm install --package-lock-only
 # Add entry to CHANGELOG.md
 ```
 
@@ -3619,8 +3620,9 @@ The canonical version lives in `package.json`. These files **must** match:
 | `README.md` | Badge counts, "What You Get" table |
 | `app/ARCHITECTURE.md` | Section headings with counts |
 
-> **Tip:** `validate.py --strict` and `npm test` (metadata contract tests) catch
-> count drift automatically. If tests pass, counts are correct.
+> **Tip:** `validate.py --strict` catches count drift AND version mismatches
+> (package.json vs manifest.json vs plugin.json) automatically.
+> If validation passes, counts and versions are correct.
 
 ### Verification command
 
@@ -8518,7 +8520,9 @@ All functionality is unified under skills. Task and hybrid skills are user-invoc
 
 | Tier | Skills | When |
 |------|--------|------|
-| **1 — Quick single-agent** | `/debug`, `/review`, `/refactor`, `/analyze`, `/docs`, `/plan`, `/explain` | One concern, fast |
+| **1 — Quick single-agent** | `/debug`, `/review`, `/refactor`, `/analyze`, `/docs`, `/plan`, `/explain`, `/tdd`, `/grill-me`, `/triage-issue` | One concern, fast |
+| **1.5 — Product planning** | `/write-a-prd` → `/prd-to-plan` → `/prd-to-issues` | Interview-driven PRD → vertical-slice plan → GitHub issues |
+| **1.5 — Design & architecture** | `/design-an-interface`, `/architecture-audit`, `/refactor-plan`, `/ubiquitous-language`, `/qa-session` | Parallel sub-agent exploration |
 | **2 — Multi-agent workflow** | `/workflow <type>` | Cross-cutting task with known pattern |
 | **3 — Custom parallelism** | `/orchestrate`, `/swarm` | No predefined workflow matches |
 

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.9.0",
+  "version": "2.2.0",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "2.1.3",
+  "version": "2.2.0",
   "description": "Professional-grade AI coding toolkit: 92 skills, 44 agents, multi-platform support (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity, Codex CLI), machine-enforced safety constitution, persona presets, skill security auditor, expanded lifecycle hooks, 11 plugin packs, and benchmark tooling.",
   "keywords": [
     "claude",

package/scripts/add_rule.py

@@ -1,52 +1,94 @@
 #!/usr/bin/env python3
-"""add-rule -- Register a rule file in ~/.softspark/ai-toolkit/rules/.
+"""add-rule -- Register a rule file or URL in ~/.softspark/ai-toolkit/rules/.
 
 Registered rules are automatically injected into all AI tool configs
-on next 'ai-toolkit install' or 'ai-toolkit update':
+on next 'ai-toolkit install' or 'ai-toolkit update'.
+URL-sourced rules are auto-refreshed on every update.
+
   Global: Claude, Cursor, Windsurf, Gemini, Augment
   Local (--local): all of the above + Copilot, Cline, Roo, Aider, Antigravity
 
 Usage:
-  add_rule.py <rule-file> [rule-name]
+  add_rule.py <rule-file-or-url> [rule-name]
 
 Arguments:
-  rule-file   Path to .md file with the rule content
-  rule-name   Override the rule name (default: filename without .md)
+  rule-file-or-url  Path to .md file or HTTPS URL to register globally
+  rule-name         Override the rule name (default: filename without .md)
 """
 from __future__ import annotations
 
 import re
 import shutil
 import sys
+import urllib.parse
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 
 
+def _name_from_url(url: str) -> str:
+    """Derive a rule name from a URL's last path segment."""
+    parsed = urllib.parse.urlparse(url)
+    filename = parsed.path.rstrip("/").split("/")[-1]
+    stem = filename.rsplit(".", 1)[0] if "." in filename else filename
+    return re.sub(r"[^a-zA-Z0-9_-]", "", stem)
+
+
 def main() -> None:
-    """Register a rule file in the global rules directory."""
+    """Register a rule file or URL in the global rules directory."""
     if len(sys.argv) < 2:
-        print("Usage: add_rule.py <rule-file> [rule-name]", file=sys.stderr)
+        print("Usage: add_rule.py <rule-file-or-url> [rule-name]", file=sys.stderr)
         sys.exit(1)
 
-    rule_file = Path(sys.argv[1])
-    if not rule_file.is_file():
-        print(f"Rule file not found: {rule_file}", file=sys.stderr)
-        sys.exit(1)
+    source = sys.argv[1]
+    is_url = source.startswith("https://") or source.startswith("http://")
 
-    rule_name = sys.argv[2] if len(sys.argv) > 2 else rule_file.stem
-    rule_name = re.sub(r"[^a-zA-Z0-9_-]", "", rule_name)
-    if not rule_name:
-        print("Error: rule name is empty after sanitization", file=sys.stderr)
+    if is_url and source.startswith("http://"):
+        print("Error: only HTTPS URLs are supported. Use https:// for security.", file=sys.stderr)
         sys.exit(1)
+
     from paths import RULES_DIR
     rules_dir = RULES_DIR
     rules_dir.mkdir(parents=True, exist_ok=True)
 
-    dest = rules_dir / f"{rule_name}.md"
-    shutil.copy2(rule_file, dest)
+    if is_url:
+        from rule_sources import fetch_url, register_url_source
+
+        rule_name = sys.argv[2] if len(sys.argv) > 2 else _name_from_url(source)
+        rule_name = re.sub(r"[^a-zA-Z0-9_-]", "", rule_name)
+        if not rule_name:
+            print("Error: could not derive rule name from URL. Provide one explicitly.", file=sys.stderr)
+            sys.exit(1)
+
+        try:
+            data = fetch_url(source)
+        except Exception as exc:
+            print(f"Error fetching URL: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+        dest = rules_dir / f"{rule_name}.md"
+        dest.write_bytes(data)
+        register_url_source(rules_dir, rule_name, source)
+
+        print(f"Registered: '{rule_name}' -> {dest}")
+        print(f"Source URL: {source} (auto-refreshed on update)")
+    else:
+        rule_file = Path(source)
+        if not rule_file.is_file():
+            print(f"Rule file not found: {rule_file}", file=sys.stderr)
+            sys.exit(1)
+
+        rule_name = sys.argv[2] if len(sys.argv) > 2 else rule_file.stem
+        rule_name = re.sub(r"[^a-zA-Z0-9_-]", "", rule_name)
+        if not rule_name:
+            print("Error: rule name is empty after sanitization", file=sys.stderr)
+            sys.exit(1)
+
+        dest = rules_dir / f"{rule_name}.md"
+        shutil.copy2(rule_file, dest)
+
+        print(f"Registered: '{rule_name}' -> {dest}")
 
-    print(f"Registered: '{rule_name}' -> {dest}")
     print()
     print("Apply now:")
     print("  ai-toolkit update            # global (Claude, Cursor, Windsurf, Gemini, Augment)")

package/scripts/install.py

@@ -212,6 +212,7 @@ def parse_args(argv: list[str]) -> dict:
         "editors": "",
         "config": "",
         "refresh_base": False,
+        "skip_register": False,
     }
     i = 0
     while i < len(argv):
@@ -268,6 +269,8 @@ def parse_args(argv: list[str]) -> dict:
             cfg["config"] = argv[i] if i < len(argv) else ""
         elif arg == "--refresh-base":
             cfg["refresh_base"] = True
+        elif arg == "--skip-register":
+            cfg["skip_register"] = True
         elif arg.startswith("-"):
             print(f"Unknown option: {arg}")
             sys.exit(1)
@@ -426,7 +429,8 @@ def install_claude_code(target_dir: Path, hooks_scripts_dir: Path,
     print()
     print(f"  Available: {count_agents()} agents, {count_skills()} skills")
 
-    inject_rules(claude_dir, target_dir, rules_dir, only, skip, dry_run)
+    inject_rules(claude_dir, target_dir, rules_dir, only, skip, dry_run,
+                 refresh_urls=True)
 
 
 VALID_PERSONAS = ("backend-lead", "frontend-lead", "devops-eng", "junior-dev")
@@ -711,7 +715,9 @@ def main() -> None:
         )
 
         # Register project in global registry (for `ai-toolkit update` propagation)
-        if local:
+        # Skipped when called from update_projects.py (--skip-register) to avoid
+        # concurrent writes to projects.json during parallel updates.
+        if local and not cfg.get("skip_register"):
             extends_source = ""
             if extends_info:
                 extends_source = extends_info.get("source", "")

package/scripts/install_steps/markers.py

@@ -32,14 +32,23 @@ def install_marker_files(claude_dir: Path, only: str, skip: str,
 
 
 def inject_rules(claude_dir: Path, target_dir: Path, rules_dir: Path,
-                 only: str, skip: str, dry_run: bool) -> None:
-    """Inject rules into CLAUDE.md."""
+                 only: str, skip: str, dry_run: bool,
+                 refresh_urls: bool = False) -> None:
+    """Inject rules into CLAUDE.md.
+
+    When refresh_urls is True, re-fetches URL-sourced rules before injection.
+    Only the global install path should set this to True (once per update).
+    """
     claude_md = claude_dir / "CLAUDE.md"
 
     if dry_run:
         _inject_rules_dry_run(rules_dir)
         return
 
+    # Refresh URL-sourced rules before injection (global update only)
+    if refresh_urls:
+        _refresh_url_rules(rules_dir)
+
     if not claude_md.is_file():
         claude_md.touch()
         print("  Created: ~/.claude/CLAUDE.md")
@@ -66,6 +75,30 @@ def inject_rules(claude_dir: Path, target_dir: Path, rules_dir: Path,
     print(f"  Rules injected: {' '.join(rules_injected)}")
 
 
+def _refresh_url_rules(rules_dir: Path) -> None:
+    """Re-fetch all URL-sourced rules. Warn on failure, use cached copy."""
+    from rule_sources import get_url_rules, fetch_url, register_url_source
+
+    url_rules = get_url_rules(rules_dir)
+    if not url_rules:
+        return
+
+    for rule_name, url in url_rules.items():
+        rule_file = rules_dir / f"{rule_name}.md"
+        try:
+            data = fetch_url(url)
+            rule_file.write_bytes(data)
+            register_url_source(rules_dir, rule_name, url)
+            print(f"  Refreshed: {rule_name} (from {url})")
+        except Exception as exc:
+            if rule_file.is_file():
+                print(f"  Warning: could not refresh '{rule_name}' from {url}: {exc}")
+                print(f"           Using cached version.")
+            else:
+                print(f"  Warning: could not fetch '{rule_name}' from {url}: {exc}")
+                print(f"           No cached version — rule will be skipped.")
+
+
 def _inject_rules_dry_run(rules_dir: Path) -> None:
     rules_src = app_dir / "rules"
     rule_names = " ".join(

package/scripts/install_steps/project_registry.py

@@ -8,15 +8,43 @@ Stdlib-only — no external dependencies.
 """
 from __future__ import annotations
 
+import contextlib
+import fcntl
 import json
+import os
 import sys
+import tempfile
+import time
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any
+from typing import Any, Generator
 
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 from paths import PROJECTS_FILE
 
+# Max retries when reading a partially-written file
+_LOAD_RETRIES = 3
+_LOAD_RETRY_DELAY = 0.05  # 50ms
+
+
+@contextlib.contextmanager
+def _registry_lock() -> Generator[None, None, None]:
+    """Exclusive file lock for read-modify-write on projects.json.
+
+    Prevents concurrent processes from interleaving loads and saves,
+    which can silently drop entries.
+    """
+    path = _registry_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lock_path = path.with_suffix(".lock")
+    fd = os.open(str(lock_path), os.O_CREAT | os.O_RDWR)
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX)
+        yield
+    finally:
+        fcntl.flock(fd, fcntl.LOCK_UN)
+        os.close(fd)
+
 
 def _registry_path() -> Path:
     """Return the canonical path to projects.json."""
@@ -32,28 +60,66 @@ def _now_iso() -> str:
 # ---------------------------------------------------------------------------
 
 def load_registry() -> list[dict[str, Any]]:
-    """Load project registry. Returns empty list if missing/corrupt."""
+    """Load project registry with retry for partially-written files.
+
+    Retries on JSONDecodeError (another process mid-write).
+    Returns empty list only if the file genuinely doesn't exist.
+    """
     path = _registry_path()
     if not path.is_file():
         return []
-    try:
-        with open(path, encoding="utf-8") as f:
-            data = json.load(f)
-        if isinstance(data, dict):
-            projects = data.get("projects", [])
-            return projects if isinstance(projects, list) else []
-        return []
-    except (json.JSONDecodeError, OSError):
-        return []
+
+    last_err: Exception | None = None
+    for attempt in range(_LOAD_RETRIES):
+        try:
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+            if isinstance(data, dict):
+                projects = data.get("projects", [])
+                return projects if isinstance(projects, list) else []
+            return []
+        except json.JSONDecodeError as exc:
+            last_err = exc
+            if attempt < _LOAD_RETRIES - 1:
+                time.sleep(_LOAD_RETRY_DELAY)
+        except OSError:
+            return []
+
+    # All retries exhausted — file is genuinely corrupt, not mid-write
+    import sys as _sys
+    print(
+        f"Warning: {path} is corrupt after {_LOAD_RETRIES} retries: {last_err}",
+        file=_sys.stderr,
+    )
+    return []
 
 
 def save_registry(projects: list[dict[str, Any]]) -> None:
-    """Save project registry."""
+    """Save project registry atomically (write-to-temp + rename).
+
+    Uses os.rename which is atomic on POSIX, preventing other processes
+    from reading a partially-written file.
+    """
     path = _registry_path()
     path.parent.mkdir(parents=True, exist_ok=True)
-    with open(path, "w", encoding="utf-8") as f:
-        json.dump({"projects": projects}, f, indent=2)
-        f.write("\n")
+
+    fd, tmp_path = tempfile.mkstemp(
+        dir=str(path.parent), prefix=".projects_", suffix=".tmp"
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump({"projects": projects}, f, indent=2)
+            f.write("\n")
+            f.flush()
+            os.fsync(f.fileno())
+        os.rename(tmp_path, str(path))
+    except BaseException:
+        # Clean up temp file on failure
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise
 
 
 # ---------------------------------------------------------------------------
@@ -68,47 +134,52 @@ def register_project(
     """Register a project directory. Returns True if newly added, False if updated.
 
     Idempotent — updates existing entry if path already registered.
+    Uses file lock to prevent concurrent read-modify-write races.
     """
     project_path = str(Path(project_path).resolve())
-    projects = load_registry()
-    now = _now_iso()
-
-    for p in projects:
-        if p.get("path") == project_path:
-            # Update existing
-            p["last_updated"] = now
-            if profile:
-                p["profile"] = profile
-            if extends:
-                p["extends"] = extends
-            elif "extends" in p and not extends:
-                # Clear extends if project no longer uses it
-                pass
-            save_registry(projects)
-            return False
 
-    # New registration
-    projects.append({
-        "path": project_path,
-        "registered_at": now,
-        "last_updated": now,
-        "profile": profile or "standard",
-        "extends": extends or "",
-    })
-    save_registry(projects)
-    return True
+    with _registry_lock():
+        projects = load_registry()
+        now = _now_iso()
+
+        for p in projects:
+            if p.get("path") == project_path:
+                # Update existing
+                p["last_updated"] = now
+                if profile:
+                    p["profile"] = profile
+                if extends:
+                    p["extends"] = extends
+                elif "extends" in p and not extends:
+                    # Clear extends if project no longer uses it
+                    pass
+                save_registry(projects)
+                return False
+
+        # New registration
+        projects.append({
+            "path": project_path,
+            "registered_at": now,
+            "last_updated": now,
+            "profile": profile or "standard",
+            "extends": extends or "",
+        })
+        save_registry(projects)
+        return True
 
 
 def unregister_project(project_path: str | Path) -> bool:
     """Unregister a project. Returns True if found and removed."""
     project_path = str(Path(project_path).resolve())
-    projects = load_registry()
-    original_len = len(projects)
-    projects = [p for p in projects if p.get("path") != project_path]
-    if len(projects) < original_len:
-        save_registry(projects)
-        return True
-    return False
+
+    with _registry_lock():
+        projects = load_registry()
+        original_len = len(projects)
+        projects = [p for p in projects if p.get("path") != project_path]
+        if len(projects) < original_len:
+            save_registry(projects)
+            return True
+        return False
 
 
 def list_projects() -> list[dict[str, Any]]:
@@ -121,18 +192,19 @@ def list_projects() -> list[dict[str, Any]]:
 
 def prune_stale() -> list[str]:
     """Remove projects whose directories no longer exist. Returns pruned paths."""
-    projects = load_registry()
-    pruned: list[str] = []
-    kept: list[dict[str, Any]] = []
-
-    for p in projects:
-        if Path(p["path"]).is_dir():
-            kept.append(p)
-        else:
-            pruned.append(p["path"])
-
-    if pruned:
-        save_registry(kept)
+    with _registry_lock():
+        projects = load_registry()
+        pruned: list[str] = []
+        kept: list[dict[str, Any]] = []
+
+        for p in projects:
+            if Path(p["path"]).is_dir():
+                kept.append(p)
+            else:
+                pruned.append(p["path"])
+
+        if pruned:
+            save_registry(kept)
 
     return pruned
 

package/scripts/remove_rule.py

@@ -43,6 +43,11 @@ def main() -> None:
     else:
         print(f"Not registered: '{rule_name}' not found in {rules_dir}")
 
+    # 1b. Clean up URL source metadata (if any)
+    from rule_sources import unregister_source
+    if unregister_source(rules_dir, rule_name):
+        print(f"Removed URL source for '{rule_name}'")
+
     # 2. Strip injected block from .claude/CLAUDE.md
     found = remove_rule_section(rule_name, target_dir)
     if found:

package/scripts/rule_sources.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""URL source registry for remotely-sourced rules.
+
+Tracks which rules were registered from a URL so that `ai-toolkit update`
+can re-fetch the latest version before injection.
+
+Metadata stored in ~/.softspark/ai-toolkit/rules/sources.json.
+
+Stdlib-only — no external dependencies.
+"""
+from __future__ import annotations
+
+import json
+import os
+import ssl
+import sys
+import tempfile
+import urllib.request
+import urllib.error
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from paths import RULES_DIR
+
+_SOURCES_FILENAME = "sources.json"
+_FETCH_TIMEOUT = 30  # seconds
+_FETCH_MAX_BYTES = 10 * 1024 * 1024  # 10MB
+
+
+# ---------------------------------------------------------------------------
+# Load / Save
+# ---------------------------------------------------------------------------
+
+def _sources_path(rules_dir: Path | None = None) -> Path:
+    return (rules_dir or RULES_DIR) / _SOURCES_FILENAME
+
+
+def load_sources(rules_dir: Path | None = None) -> dict[str, dict[str, Any]]:
+    """Load sources.json. Returns {} if missing or corrupt."""
+    path = _sources_path(rules_dir)
+    if not path.is_file():
+        return {}
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+        if isinstance(data, dict):
+            return data.get("rules", {})
+        return {}
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def save_sources(rules_dir: Path | None = None,
+                 sources: dict[str, dict[str, Any]] | None = None) -> None:
+    """Write sources.json atomically."""
+    rules_dir = rules_dir or RULES_DIR
+    path = _sources_path(rules_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    payload = json.dumps({"schema_version": 1, "rules": sources or {}}, indent=2)
+
+    fd, tmp_path = tempfile.mkstemp(
+        dir=str(path.parent), prefix=".sources_", suffix=".tmp"
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(payload)
+            f.write("\n")
+            f.flush()
+            os.fsync(f.fileno())
+        os.rename(tmp_path, str(path))
+    except BaseException:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise
+
+
+# ---------------------------------------------------------------------------
+# CRUD
+# ---------------------------------------------------------------------------
+
+def register_url_source(rules_dir: Path | None, rule_name: str, url: str) -> None:
+    """Add or update a URL source entry."""
+    rules_dir = rules_dir or RULES_DIR
+    sources = load_sources(rules_dir)
+    sources[rule_name] = {
+        "url": url,
+        "fetched_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+    save_sources(rules_dir, sources)
+
+
+def unregister_source(rules_dir: Path | None, rule_name: str) -> bool:
+    """Remove a source entry. Returns True if found and removed."""
+    rules_dir = rules_dir or RULES_DIR
+    sources = load_sources(rules_dir)
+    if rule_name in sources:
+        del sources[rule_name]
+        save_sources(rules_dir, sources)
+        return True
+    return False
+
+
+def get_url_rules(rules_dir: Path | None = None) -> dict[str, str]:
+    """Return {rule_name: url} for all URL-sourced rules."""
+    sources = load_sources(rules_dir)
+    return {name: entry["url"] for name, entry in sources.items() if "url" in entry}
+
+
+# ---------------------------------------------------------------------------
+# Fetch
+# ---------------------------------------------------------------------------
+
+def fetch_url(url: str) -> bytes:
+    """Fetch URL content. HTTPS only, 30s timeout, 10MB cap.
+
+    Raises:
+        ValueError: if URL is not HTTPS
+        urllib.error.URLError: on network failure
+    """
+    if not url.startswith("https://"):
+        raise ValueError(
+            f"Only HTTPS URLs are supported (got: {url.split('://')[0]}://)"
+        )
+
+    ctx = ssl.create_default_context()
+    with urllib.request.urlopen(url, timeout=_FETCH_TIMEOUT, context=ctx) as resp:
+        data = resp.read(_FETCH_MAX_BYTES)
+
+    # Basic binary detection — reject if null bytes present
+    if b"\x00" in data:
+        raise ValueError(f"URL returned binary content, expected markdown: {url}")
+
+    return data

package/scripts/update_projects.py

@@ -17,7 +17,7 @@ from pathlib import Path
 from typing import Any
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-from install_steps.project_registry import get_active_projects, prune_stale
+from install_steps.project_registry import get_active_projects, prune_stale, register_project
 
 
 def _update_project(project: dict[str, Any], install_script: str, extra_args: list[str]) -> dict:
@@ -91,13 +91,17 @@ def main() -> None:
         print(f"  Updating {len(projects)} registered project(s)...")
         print()
 
+    # --skip-register: parallel installs must NOT write to projects.json
+    # concurrently. We re-register sequentially after all installs complete.
+    parallel_args = extra_args + ["--skip-register"]
+
     # Run in parallel (max 8 workers — don't overwhelm the system)
     max_workers = min(len(projects), 8)
     results: list[dict] = []
 
     with ThreadPoolExecutor(max_workers=max_workers) as pool:
         futures = {
-            pool.submit(_update_project, p, install_script, extra_args): p
+            pool.submit(_update_project, p, install_script, parallel_args): p
             for p in projects
         }
         for future in as_completed(futures):
@@ -118,6 +122,15 @@ def main() -> None:
                     for line in result["error"].strip().split("\n"):
                         print(f"      ERROR: {line}")
 
+    # Re-register projects sequentially (safe — no concurrent writes)
+    for result in results:
+        if result["success"]:
+            register_project(
+                result["path"],
+                profile=result.get("profile", "standard"),
+                extends=result.get("extends", ""),
+            )
+
     # Summary
     passed = sum(1 for r in results if r["success"])
     failed = len(results) - passed

package/scripts/validate.py

@@ -610,10 +610,43 @@ def validate_metadata_contracts(
     else:
         print(f"  OK: tests ({actual_tests})")
 
+    # Cross-validate versions: package.json vs manifest.json vs plugin.json
+    _validate_version_sync(tk_dir, vr)
+
     print()
     return actual_tests
 
 
+def _validate_version_sync(tk_dir: Path, vr: ValidationResult) -> None:
+    """Ensure package.json, manifest.json, and plugin.json versions match."""
+    import json as _json
+
+    version_files = {
+        "package.json": tk_dir / "package.json",
+        "manifest.json": tk_dir / "manifest.json",
+        "plugin.json": tk_dir / "app" / ".claude-plugin" / "plugin.json",
+    }
+
+    versions: dict[str, str] = {}
+    for name, path in version_files.items():
+        if path.is_file():
+            try:
+                data = _json.loads(path.read_text(encoding="utf-8"))
+                versions[name] = data.get("version", "")
+            except Exception:
+                pass
+
+    if len(versions) < 2:
+        return  # Not enough files to compare (e.g., installed copy without source)
+
+    unique = set(versions.values())
+    if len(unique) == 1:
+        print(f"  OK: version sync ({unique.pop()})")
+    else:
+        detail = ", ".join(f"{k}={v}" for k, v in versions.items())
+        vr.error(f"Version mismatch across files: {detail}")
+
+
 def validate_content_quality(tk_dir: Path, vr: ValidationResult) -> None:
     """Check content quality: name matches directory, non-empty body."""
     print()