wizz-method 2.23.0 → 2.25.0

package/src/skills-lib/wizz-security-audit-pentest/references/stage-5-segredos-historico.md

@@ -0,0 +1,74 @@
+# Stage 5 — Secret hunter (working tree and git history)
+
+You are a secret-hunting analyst ("Caçador de Segredos").
+
+Premise: deleting a secret in a later commit does NOT erase it from git history. Anyone who clones the repository or accesses an exposed `.git` directory can recover every historic blob. At the same time, an audit must NEVER become a second leak: you must prove the secret's existence and location **without ever printing or recording the raw secret value**.
+
+## Mandatory non-exposure rule (zero plaintext secrets)
+
+- **NEVER print, echo, or copy the full secret value** into terminal output, stage tables, evidence columns, or the final report.
+- When inspecting git history, use only the executable blocks below. They emit hashes, dates and file names, with **no commit subject/body, author, notes or patch**. Never use `--oneline`, `%s`, `%B`, or plain `git show --stat`: a commit message or author may contain the secret too.
+  - **NEVER run `git show -p`, `git log -p`, `git diff`, or any patch command that dumps raw secret values into stdout.**
+- The current-tree command emits **file names only**, including tracked and non-ignored untracked text files. Do not switch to `grep -n` or `git grep -n`, which print matching secret-bearing lines. Any follow-up must preserve this output restriction; use `<file>` when a safe line number is unavailable.
+
+Run each marked block from the audited repository root with Bash. Exit status 1 from `git grep` means no matches; other errors must stop the scan. These patterns detect candidates, not proof of validity. The long generic `sk-` pattern and token boundary avoid ordinary `risk-`, `task-` and `disk-` words. Short, unusual or ignored credentials still need a scoped investigation with the same non-exposure rule.
+
+```bash audit-current-secrets
+set -eu
+secret_pattern='(^|[^A-Za-z0-9_])(sk-[A-Za-z0-9]{20,}|sk-ant-[A-Za-z0-9_-]{20,}|sk_live_[A-Za-z0-9]{20,}|ghp_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|xox[bp]-[A-Za-z0-9-]{20,}|AKIA[A-Z0-9]{16}|AIza[A-Za-z0-9_-]{20,}|eyJhbGciOi[A-Za-z0-9_-]{20,})'
+if git --no-pager grep --untracked --exclude-standard -l -I -E "$secret_pattern" -- .; then
+  :
+else
+  result=$?
+  if [ "$result" -ne 1 ]; then exit "$result"; fi
+fi
+```
+
+```bash audit-history-secrets
+set -eu
+secret_pattern='(^|[^A-Za-z0-9_])(sk-[A-Za-z0-9]{20,}|sk-ant-[A-Za-z0-9_-]{20,}|sk_live_[A-Za-z0-9]{20,}|ghp_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|xox[bp]-[A-Za-z0-9-]{20,}|AKIA[A-Z0-9]{16}|AIza[A-Za-z0-9_-]{20,}|eyJhbGciOi[A-Za-z0-9_-]{20,})'
+git --no-pager log --all --no-ext-diff --no-textconv --no-show-signature --no-notes --no-decorate --pickaxe-regex -S "$secret_pattern" --format='%h %ad' --date=short --name-only
+```
+
+## Mandatory prefix sweep
+
+Hunt for all of the following prefixes in both the working tree and the full git history (`--all`):
+
+1. `sk-` — OpenAI and generic secret API keys
+2. `sk-ant-` — Anthropic API keys
+3. `sk_live_` — Stripe live secret keys
+4. `ghp_` — GitHub classic personal access tokens
+5. `github_pat_` — GitHub fine-grained personal access tokens
+6. `xox[bp]-` (`xoxb-` and `xoxp-`) — Slack bot and user tokens
+7. `AKIA` — AWS IAM long-term access key IDs
+8. `AIza` — Google Cloud / Firebase / Gemini API keys
+9. `eyJhbGciOi` — Base64URL-encoded JWT headers (`{"alg":"...`)
+
+Also inventory tracked environment/key files, including root `.env` and nested files. The explicit `:(glob)**/` pathspec includes the repository root. Inventory alone is not a vulnerability: verify whether the file is a template/dummy without dumping its contents.
+
+```bash audit-current-key-files
+set -eu
+git ls-files -- ':(glob)**/.env*' ':(glob)**/*.pem' ':(glob)**/*.key'
+```
+
+```bash audit-history-key-files
+set -eu
+git --no-pager log --all --full-history --no-ext-diff --no-textconv --no-show-signature --no-notes --no-decorate --format='%h %ad' --date=short --name-only -- ':(glob)**/.env*' ':(glob)**/*.pem' ':(glob)**/*.key'
+```
+
+## How to fill the table safely
+
+- **Where (`file:line` or `commit:file`):** For working-tree findings, write `path/to/file:line`. For git-history findings, write `commit <short-sha> (path/to/file)`.
+- **How it's exploited:** State the concrete extraction and abuse path using the redacted prefix (for example: "Extract commit `<short-sha>` affecting `config/prod.ts` from git history (`sk_live_[REDACTED]`) and authenticate directly against the Stripe API to list charges or issue refunds"). **Never paste the real secret value.**
+- **What prevents it:** Immediate key revocation/rotation at the provider, removal from code in favor of secret manager / environment injection (invoke the `wizz-auth-and-secrets` skill), and history scrubbing (`git filter-repo`).
+- **Severity:** Live production credentials or unrevoked secret keys in history are `CRITICAL`; scoped/secondary keys are `HIGH`; ambiguous non-dummy tokens requiring rotation verification are `MEDIUM` or `HIGH`.
+
+Output format — markdown table, no text before or after:
+
+| # | Risk | Where (file:line) | How it's exploited | What prevents it | Severity |
+
+Severity: CRITICAL, HIGH, MEDIUM.
+
+CUTOFF RULE: if you can't fill in "How it's exploited" with a concrete, specific action and a verified `file:line` or `commit:file` match, DON'T include the row. Known dummy placeholders in test fixtures (such as `sk-test-000000` or `<YOUR_API_KEY>`) are not findings.
+
+If there's no finding that passes this ruler, answer only: NO FINDINGS AT THIS STAGE.

package/src/skills-lib/wizz-security-audit-pentest/references/stage-6-advogado-do-diabo.md

@@ -0,0 +1,33 @@
+# Stage 6 — Devil's Advocate (false-positive and severity review)
+
+You are the Devil's Advocate ("Advogado do Diabo").
+
+You receive the raw findings tables from Hunting Stages 1–5 (input validation, authorization failure, volume abuse, response leakage, and secret hunter). Your job is to challenge every finding against the actual repository code so that real vulnerabilities survive with verified evidence and false positives are refuted with proof.
+
+## Allowed verdicts (mandatory)
+
+Assign exactly one of these three verdicts to every finding:
+
+- **`CONFIRMADO`**: The vulnerable code path or leaked secret prefix exists at the cited location, no in-repository control neutralizes the exploit path, and the concrete exploitation proof holds.
+- **`DEPENDE DE CONFIGURAÇÃO`**: The repository code alone does not prevent exploitation, and safety depends on external or runtime state that cannot be verified from versioned files alone (for example: live database RLS policies not captured in migrations, WAF / CDN / API Gateway rate limits, reverse-proxy `trust proxy` configuration, production environment variables, or whether a historic secret found in git history has already been revoked at the provider).
+- **`DERRUBADO`**: Concrete evidence **inside the repository** (`file:line`) disproves the finding (for example: an upstream router middleware already enforces session ownership, a strict schema validator strips unallowed fields before the database write, queries are parameterized, or a matched token prefix is an explicit dummy fixture). Rows that violated the hunting cutoff ruler (vague "best practice" wishes with no concrete payload or location) are also marked `DERRUBADO`.
+
+## Safe severity and evidence rules (mandatory)
+
+1. **One-way severity ratchet (can only lower, never raise):**
+   - You may keep the original severity or **lower** it (`CRITICAL` → `HIGH` or `MEDIUM`; `HIGH` → `MEDIUM`) **only** when concrete in-repository mitigation reduces the blast radius or exploitability.
+   - You may **NEVER increase** a finding's severity.
+2. **Absence of configuration does NOT prove a false positive (divergence from naive "when in doubt, dismiss"):**
+   - Do **NOT** mark a finding `DERRUBADO` and do **NOT** lower its severity merely because external configuration might exist or cannot be seen in the repository.
+   - Missing configuration in the repo, unverified cloud/dashboard settings, or uncertainty about external infrastructure is **never** proof of a false positive. Whenever a finding's refutation depends on unverified external configuration, you MUST classify it as `DEPENDE DE CONFIGURAÇÃO` and **preserve its severity** until confirmed in the live environment.
+   - Only mark a finding `DERRUBADO` when you can cite the exact `file:line` in the repository that blocks the exploit, or when the hunter failed to provide a concrete exploit/location.
+3. **Safe evidence handling:**
+   - Never print or echo raw secret values when verifying Stage 5 findings. Refer only to commit hashes, `file:line`, and redacted prefixes (`sk-ant-[REDACTED]`).
+
+## Output format
+
+Output a single markdown table covering every finding received from Stages 1–5, with no text before or after:
+
+| # | Stage | Original Finding (Where) | Verdict (`CONFIRMADO` / `DEPENDE DE CONFIGURAÇÃO` / `DERRUBADO`) | Evidence (`file:line` that confirms/refutes, or live config to verify) | Original Severity | Final Severity |
+
+If all five hunting stages returned `NO FINDINGS AT THIS STAGE`, answer only: `NO FINDINGS TO REVIEW`.

package/src/skills-lib/wizz-security-audit-pentest/references/stage-7-fusao-plano.md

@@ -0,0 +1,50 @@
+# Stage 7 — Merge into a single plan and private external report (`SEGURANCA-<data>/`)
+
+Below I will paste the five hunting reports (input validation, authorization failure, volume abuse, response leakage, secret hunter) and the Stage 6 Devil's Advocate review table.
+
+## Step 1 — Isolate the report outside the audited project BEFORE writing any file
+
+Audit reports contain concrete exploit payloads, vulnerable `file:line` coordinates, and commit hashes of leaked secrets. Keep them outside git, deploy inputs, static hosting roots and archives of the audited project. A nested `.gitignore` alone does **not** protect against deployment or zip.
+
+Choose an existing private absolute parent directory outside those inputs and set `AUDIT_REPORT_PARENT` to it. Run this block from the audited project root. It resolves symlinks in the parent, rejects an in-project parent, creates the directory exclusively with private permissions, and writes `.gitignore` before any artifact. An existing directory, including a second run on the same date, fails without changing the earlier report; select a different private parent instead of overwriting it.
+
+```bash audit-report-init
+set -eu
+: "${AUDIT_REPORT_PARENT:?set an existing private absolute report parent outside the project}"
+case "$AUDIT_REPORT_PARENT" in /*) ;; *) echo 'report parent must be absolute' >&2; exit 1 ;; esac
+project_root=$(pwd -P)
+report_parent=$(cd "$AUDIT_REPORT_PARENT" && pwd -P)
+case "$report_parent/" in "$project_root/"*) echo 'report parent must be outside the audited project' >&2; exit 1 ;; esac
+report_dir="$report_parent/SEGURANCA-$(date +%F)"
+umask 077
+mkdir -m 700 "$report_dir"
+printf '*\n' > "$report_dir/.gitignore"
+if git -C "$report_dir" rev-parse --show-toplevel >/dev/null 2>&1; then
+  git -C "$report_dir" check-ignore -q -- RELATORIO.md
+fi
+printf '%s\n' "$report_dir"
+```
+
+Verify `.gitignore` contains exactly `*`, then write `RELATORIO.md` into the returned directory. Never include raw secret values. Keep this absolute path private when delivering the report. Do not copy the report back into the project or a publishing/packaging input.
+
+## Step 2 — Merge the reviewed findings into a single remediation plan
+
+Use the Stage 6 Devil's Advocate verdicts to filter and structure the plan:
+
+1. **Keep active findings (`CONFIRMADO` and `DEPENDE DE CONFIGURAÇÃO`):**
+   - Findings with verdict `CONFIRMADO` enter the remediation plan at their Stage 6 `Final Severity`.
+   - Findings with verdict `DEPENDE DE CONFIGURAÇÃO` remain active in the plan at their preserved severity, clearly tagged with the exact live configuration or provider state that must be verified (absence of configuration in the repository never dismisses a finding).
+   - Findings with verdict `DERRUBADO` are excluded from the active remediation queue, but preserved in a dedicated "Dismissed by Devil's Advocate (`DERRUBADO`)" appendix with the refuting `file:line` evidence for auditability.
+2. **Remove duplicates across stages:**
+   - The same root issue may appear in more than one stage under different angles (for example, a leaked key in Stage 5 and its authorization impact in Stage 2). Merge into a single item citing all originating stages.
+3. **Order by REMEDIATION EFFORT divided by SEVERITY:**
+   - First: `CRITICAL` findings that require a small, localized fix.
+   - Last: `MEDIUM` findings that require broader refactoring.
+4. **Identify ATTACK CHAINS:**
+   - Highlight where two `MEDIUM` or `HIGH` findings combine into a `CRITICAL` path. Example: user enumeration on login (Stage 4) combined with missing rate limiting on the same route (Stage 3) forms a single critical chain worth more than the sum of its parts.
+5. **Close with "TODAY'S TOP THREE" ("AS TRÊS DE HOJE"):**
+   - List the three items that must be fixed or verified before anything else, with a one-line justification for each.
+6. **Attach stage tables:**
+   - Append the raw tables from Stages 1–5 and the complete Stage 6 Devil's Advocate table at the end of `SEGURANCA-<data>/RELATORIO.md`.
+
+[paste the 5 hunting reports and the Stage 6 Devil's Advocate table below]

package/tools/installer/README.md

@@ -1,5 +1,10 @@
 # Wizz Method CLI Tool
 
+## Versioned templates
+
+Use `wizz templates` to validate or stage an inert package and return its `APPLY.md`.
+See [the template contract](templates.md) for authoring, registry entries and safety limits.
+
 ## Installing external repo official modules
 
 For external official modules to be discoverable during install, ensure an entry for the external repo is added to external-official-modules.yaml.

package/tools/installer/commands/templates.js

@@ -0,0 +1,65 @@
+const path = require('node:path');
+const fs = require('node:fs');
+const yaml = require('yaml');
+const { getProjectRoot } = require('../project-root');
+const { loadTemplate, stageTemplate, safePath, validateTemplateEntry } = require('../modules/templates');
+
+function runTemplates(options, packageRoot = getProjectRoot()) {
+  const actions = [options.list, options.validate, options.use].filter(Boolean);
+  if (actions.length !== 1) throw new Error('Choose exactly one: --list, --validate <directory>, --use <id>');
+  if (options.validate) {
+    const { manifest, digest } = loadTemplate(path.resolve(options.validate), { sha256: options.sha256, version: options.templateVersion });
+    return { valid: true, slug: manifest.slug, version: manifest.version, sha256: digest, files: manifest.files.length };
+  }
+  const registry = yaml.parse(fs.readFileSync(path.join(packageRoot, 'skills-registry.yaml'), 'utf8'));
+  if (!registry || typeof registry !== 'object' || Array.isArray(registry)) throw new Error('Registry must be an object');
+  const entries = registry.templates === undefined ? [] : registry.templates;
+  if (!Array.isArray(entries)) throw new Error('Registry templates must be an array');
+  const seen = new Set();
+  for (const entry of entries) {
+    validateTemplateEntry(entry);
+    if (seen.has(entry.id)) throw new Error('Duplicate template registry id');
+    seen.add(entry.id);
+  }
+  if (options.list) return entries.map(({ id, version, when }) => ({ id, type: 'template', version, when }));
+  const entry = entries.find((item) => item.id === options.use);
+  if (entry && options.source) throw new Error('Registry pin cannot be overridden with --source; use a distinct local id');
+  if (!entry && !options.source) throw new Error('Unknown template id; use --list or provide --source and --sha256');
+  if (options.source && !options.sha256) throw new Error('--source requires a trusted --sha256 for manifest.json');
+  if (!options.source && entry.type !== 'template') throw new Error('Registry entry is not a template');
+  if (!options.source && options.templateVersion && options.templateVersion !== entry.version)
+    throw new Error('Requested version differs from registry pin');
+  if (!options.source && options.sha256 && options.sha256 !== entry.sha256) throw new Error('Requested hash differs from registry pin');
+  const source = options.source ? path.resolve(options.source) : path.join(packageRoot, safePath(entry.source));
+  return stageTemplate(source, path.resolve(options.project || '.'), {
+    bundledRoot: options.source ? undefined : packageRoot,
+    id: options.use,
+    version: options.source ? options.templateVersion : entry.version,
+    sha256: options.source ? options.sha256 : entry.sha256,
+  });
+}
+
+module.exports = {
+  command: 'templates',
+  description: 'Validate or stage an inert versioned template; read APPLY.md to apply it manually',
+  options: [
+    ['--list', 'List opt-in registry templates'],
+    ['--validate <directory>', 'Validate a local template without writing to the project'],
+    ['--use <id>', 'Stage a template in the project cache; never apply or execute it'],
+    ['--source <directory>', 'Explicit local source (requires --sha256)'],
+    ['--sha256 <hash>', 'Trusted SHA-256 of manifest.json'],
+    ['--template-version <version>', 'Require this exact version'],
+    ['--project <directory>', 'Existing project directory (default: current directory)'],
+    ['--json', 'Print structured output'],
+  ],
+  action: (options) => {
+    try {
+      const result = runTemplates(options);
+      console.log(options.json ? JSON.stringify(result) : JSON.stringify(result, null, 2));
+    } catch (error) {
+      console.error(options.json ? JSON.stringify({ error: error.message }) : `Template error: ${error.message}`);
+      process.exitCode = 1;
+    }
+  },
+  runTemplates,
+};

package/tools/installer/core/resolved-schema.js

@@ -79,9 +79,11 @@ const WORKFLOW_KEYS = new Set([
   // item keys are validated against REVIEW_LAYER_KEYS below.
   'review_layers',
   'oneshot_review_layers',
-  // review economy (review-economy.md): diff cleaning excludes/critical paths.
+  // review economy (review-economy.md): diff cleaning excludes, critical
+  // paths (plain-language guidance) and critical globs (fixed floor).
   'review_exclude',
   'review_critical_paths',
+  'review_critical_globs',
 ]);
 const PARTY_MEMBER_KEYS = new Set(['code', 'name', 'icon', 'title', 'persona', 'capabilities', 'model']);
 const PARTY_GROUP_KEYS = new Set(['id', 'name', 'scene', 'members', 'memory']);
@@ -104,7 +106,7 @@ function isArrayOfStrings(value) {
 
 /**
  * Collect unknown/invalid entries under `[workflow]`: unknown fields by
- * name, invalid values for the two review-economy string-array fields, and
+ * name, invalid values for the three review-economy string-array fields, and
  * — for the arrays-of-tables we own (party members/groups, review layers) —
  * the unknown keys and invalid values of each item.
  *
@@ -122,7 +124,7 @@ function findUnknownWorkflowKeys(workflow) {
       unknown.push({ path: wfPath, kind: 'unknown' });
       continue;
     }
-    if (k2 === 'review_exclude' || k2 === 'review_critical_paths') {
+    if (k2 === 'review_exclude' || k2 === 'review_critical_paths' || k2 === 'review_critical_globs') {
       if (!isArrayOfStrings(v2)) {
         unknown.push({ path: wfPath, kind: 'invalid', detail: `expected an array of strings, got ${JSON.stringify(v2)}` });
       }

package/tools/installer/modules/templates.js

@@ -0,0 +1,229 @@
+// Template packages are inert data. Only explicit files enter the project cache;
+// APPLY.md is handed to an agent, never executed by the installer.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const semver = require('semver');
+
+const LIMITS = Object.freeze({ manifest: 256 * 1024, file: 25 * 1024 * 1024, total: 100 * 1024 * 1024, files: 1000 });
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SHA256 = /^[a-f0-9]{64}$/;
+const POLICY = Object.freeze({ conflicts: 'stop-or-prefix', provenance: 'required', verification: 'required', execution: 'manual' });
+const APPLY_RULES = [
+  '<!-- WIZZ_TEMPLATE_POLICY_V1 -->',
+  'Never overwrite an existing project file. On conflict, stop and ask the human, or use a human-approved prefix in both the filename and the skill name: frontmatter field.',
+  'Record the provenance line returned by the CLI (origin, slug, version and manifest SHA-256) in the applied project.',
+  'Verify the adapted files and project checks after applying; report what passed and what remains unverified.',
+  'Installation is inert. Never run paid, expensive, publishing or credential operations just because this template was installed; obtain explicit human authorization first.',
+  '<!-- /WIZZ_TEMPLATE_POLICY_V1 -->',
+  '',
+].join('\n');
+const hash = (data) => crypto.createHash('sha256').update(data).digest('hex');
+
+function object(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function keys(value, allowed, label) {
+  if (!object(value)) throw new Error(`${label} must be an object`);
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new Error(`${label}: unknown key ${key}`);
+}
+
+// Portable paths, including on case-insensitive Windows/macOS filesystems.
+function safePath(value) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 240) throw new Error('Invalid template path');
+  const parts = value.split('/');
+  if (
+    parts.some(
+      (part) =>
+        !/^[\w.-]+$/.test(part) ||
+        part === '.' ||
+        part === '..' ||
+        /[. ]$/.test(part) ||
+        /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\.|$)/i.test(part),
+    )
+  ) {
+    throw new Error(`Unsafe template path: ${value}`);
+  }
+  return value;
+}
+
+function validateTemplateEntry(entry) {
+  keys(entry, ['id', 'type', 'when', 'version', 'source', 'sha256', 'metadata'], 'template registry entry');
+  if (entry.type !== 'template' || typeof entry.id !== 'string' || entry.id.length > 64 || !SLUG.test(entry.id))
+    throw new Error('Invalid template registry id/type');
+  if (typeof entry.when !== 'string' || !entry.when.trim()) throw new Error('Template registry when is required');
+  if (typeof entry.version !== 'string' || semver.valid(entry.version) !== entry.version)
+    throw new Error('Invalid template registry version');
+  safePath(entry.source);
+  if (typeof entry.sha256 !== 'string' || !SHA256.test(entry.sha256)) throw new Error('Invalid template registry sha256');
+  if (entry.metadata !== undefined) {
+    keys(entry.metadata, ['version'], 'template metadata');
+    if (entry.metadata.version !== entry.version) throw new Error('Template metadata.version must match version');
+  }
+  return entry;
+}
+
+function validateManifest(manifest) {
+  keys(manifest, ['schema_version', 'type', 'slug', 'version', 'origin', 'instructions', 'policy', 'files'], 'manifest');
+  if (manifest.schema_version !== 1 || manifest.type !== 'template') throw new Error('Expected template schema_version 1');
+  if (typeof manifest.slug !== 'string' || manifest.slug.length > 64 || !SLUG.test(manifest.slug)) throw new Error('Invalid template slug');
+  if (typeof manifest.version !== 'string' || semver.valid(manifest.version) !== manifest.version)
+    throw new Error('Invalid template version');
+  if (typeof manifest.origin !== 'string' || !/^https:\/\/[^\s]+$/.test(manifest.origin) || /[^\u0021-\u007E]/.test(manifest.origin))
+    throw new Error('Template origin must be an HTTPS attribution URL');
+  const origin = new URL(manifest.origin);
+  if (origin.username || origin.password || manifest.origin.includes(';'))
+    throw new Error('Origin cannot contain credentials or provenance delimiters');
+  if (manifest.instructions !== 'APPLY.md') throw new Error('Template instructions must be APPLY.md');
+  keys(manifest.policy, Object.keys(POLICY), 'policy');
+  for (const [key, value] of Object.entries(POLICY))
+    if (manifest.policy[key] !== value) throw new Error(`Required template policy: ${key}=${value}`);
+  if (!Array.isArray(manifest.files) || manifest.files.length === 0 || manifest.files.length > LIMITS.files)
+    throw new Error('Invalid template file count');
+  const seen = new Set(['manifest.json', 'origin.json']);
+  let total = 0;
+  for (const file of manifest.files) {
+    keys(file, ['path', 'size', 'sha256'], 'file');
+    safePath(file.path);
+    const folded = file.path.toLowerCase();
+    if (seen.has(folded)) throw new Error(`Duplicate/reserved template path: ${file.path}`);
+    seen.add(folded);
+    if (!Number.isSafeInteger(file.size) || file.size < 0 || file.size > LIMITS.file) throw new Error('Invalid template file size');
+    if (!SHA256.test(file.sha256)) throw new Error('Invalid template file sha256');
+    total += file.size;
+  }
+  for (const name of seen) {
+    const parts = name.split('/');
+    while (parts.length > 1) {
+      parts.pop();
+      if (seen.has(parts.join('/'))) throw new Error('Template file/directory path collision');
+    }
+  }
+  if (total > LIMITS.total) throw new Error('Template exceeds expanded size limit');
+  if (!manifest.files.some((file) => file.path === 'APPLY.md')) throw new Error('APPLY.md must be explicitly listed');
+  return manifest;
+}
+
+// Reject links in every relative path component, then open without following a
+// final symlink. Read at most the declared size + 1, even if the source grows.
+function readFile(root, relative, maxSize, allowHardlinks = false) {
+  let current = root;
+  for (const part of safePath(relative).split('/')) {
+    current = path.join(current, part);
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink()) throw new Error(`Template symlink rejected: ${relative}`);
+  }
+  const fd = fs.openSync(current, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0) | (fs.constants.O_NONBLOCK || 0));
+  try {
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || (!allowHardlinks && stat.nlink !== 1) || stat.size > maxSize)
+      throw new Error(`Unsafe/oversized template file: ${relative}`);
+    const data = Buffer.alloc(maxSize + 1);
+    let size = 0;
+    while (size < data.length) {
+      const count = fs.readSync(fd, data, size, data.length - size, null);
+      if (count === 0) break;
+      size += count;
+    }
+    if (size > maxSize) throw new Error(`Template size exceeded: ${relative}`);
+    return data.subarray(0, size);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function loadTemplate(source, { sha256, version, id, bundledRoot } = {}) {
+  if (fs.lstatSync(source).isSymbolicLink() || !fs.statSync(source).isDirectory())
+    throw new Error('Template source must be a directory, not a link');
+  const root = fs.realpathSync(source);
+  const allowHardlinks = Boolean(
+    bundledRoot &&
+    sha256 &&
+    !path.relative(fs.realpathSync(bundledRoot), root).startsWith('..') &&
+    !path.isAbsolute(path.relative(fs.realpathSync(bundledRoot), root)),
+  );
+  if (bundledRoot && !allowHardlinks) throw new Error('Bundled source must be pinned inside package root');
+  const raw = readFile(root, 'manifest.json', LIMITS.manifest, allowHardlinks);
+  const digest = hash(raw);
+  if (sha256 !== undefined && (!SHA256.test(sha256) || digest !== sha256)) throw new Error('Template manifest integrity mismatch');
+  const manifest = validateManifest(JSON.parse(raw.toString('utf8')));
+  if (version && version !== manifest.version) throw new Error('Template version mismatch');
+  if (id && id !== manifest.slug) throw new Error('Template id mismatch');
+  const files = manifest.files.map((file) => {
+    const data = readFile(root, file.path, file.size, allowHardlinks);
+    if (data.length !== file.size || hash(data) !== file.sha256) throw new Error(`Template integrity mismatch: ${file.path}`);
+    return { path: file.path, data };
+  });
+  const instructions = files.find((file) => file.path === 'APPLY.md').data.toString('utf8');
+  if (!instructions.startsWith(APPLY_RULES)) throw new Error('APPLY.md must start with the canonical template policy');
+  return { manifest, raw, digest, files };
+}
+
+function ensureDirectory(parent, name) {
+  const target = path.join(parent, name);
+  try {
+    fs.mkdirSync(target, { mode: 0o700 });
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+  }
+  const stat = fs.lstatSync(target);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`Unsafe template cache directory: ${target}`);
+  return target;
+}
+
+function stageTemplate(source, project, expected) {
+  if (!expected?.sha256) throw new Error('A trusted manifest sha256 is required to use a template');
+  // Read and verify EVERYTHING before making any project changes.
+  const loaded = loadTemplate(source, expected);
+  const { manifest, raw, digest, files } = loaded;
+  const projectRoot = fs.realpathSync(project);
+  let parent = projectRoot;
+  for (const part of ['.wizz', 'templates', manifest.slug]) parent = ensureDirectory(parent, part);
+  const destination = path.join(parent, manifest.version);
+  // Publish a fully verified tree in one rename. An interrupted process can
+  // leave a hidden staging sibling, never a partially installed version.
+  try {
+    fs.lstatSync(destination);
+    const incomplete = !fs.existsSync(path.join(destination, 'origin.json'));
+    throw Object.assign(
+      new Error(
+        `EEXIST: template version already exists${incomplete ? ' (incomplete legacy cache; inspect and move it aside before retry)' : ''}`,
+      ),
+      { code: 'EEXIST' },
+    );
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  const temporary = fs.mkdtempSync(path.join(parent, `.${manifest.version}-staging-`));
+  try {
+    for (const { path: relative, data } of [...files, { path: 'manifest.json', data: raw }]) {
+      const parts = relative.split('/');
+      const name = parts.pop();
+      let directory = temporary;
+      for (const part of parts) directory = ensureDirectory(directory, part);
+      fs.writeFileSync(path.join(directory, name), data, { flag: 'wx', mode: 0o600 });
+    }
+    const provenance = `Wizz template: ${manifest.slug}@${manifest.version}; origin: ${manifest.origin}; sha256: ${digest}`;
+    fs.writeFileSync(
+      path.join(temporary, 'origin.json'),
+      `${JSON.stringify({ schema_version: 1, slug: manifest.slug, version: manifest.version, origin: manifest.origin, sha256: digest, provenance }, null, 2)}\n`,
+      { flag: 'wx', mode: 0o600 },
+    );
+    fs.renameSync(temporary, destination);
+    return {
+      slug: manifest.slug,
+      version: manifest.version,
+      destination,
+      instructions: path.join(destination, 'APPLY.md'),
+      provenance,
+      policy: manifest.policy,
+      applied: false,
+    };
+  } catch (error) {
+    fs.rmSync(temporary, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+module.exports = { APPLY_RULES, LIMITS, POLICY, safePath, validateTemplateEntry, validateManifest, loadTemplate, stageTemplate, hash };