clckernel 1.2.19 → 2.0.1

package/.agents/skills/clckernel_cli/SKILL.md

@@ -5,7 +5,9 @@ description: >-
   Use when the user issues a clckernel command (e.g. clckernel feature, clckernel fix,
   clckernel audit, clckernel doctor, clckernel commit, clckernel update, clckernel start)
   or /clckernel, or asks to initiate a feature, fix a bug, audit architecture, run tests,
-  diagnose health, or commit changes in a project governed by CLC Kernel.
+  diagnose health, or commit changes in a project governed by CLC Kernel. Also use in the
+  first session after install (tools/.clckernel-managed.json present, no .clckernel.yaml) to
+  orient the user and offer the start playbook.
 ---
 
 # 🤖 CLC Kernel — Agent Governance Engine
@@ -21,12 +23,12 @@ When the developer issues a \`clckernel <command>\` or \`/clckernel <command>\`
 | `feature` | Lifecycle | Execute full AIUP cycle for a new feature (Spec -> HIT -> TDD -> Clean Code -> Audit) | [reference/feature.md](reference/feature.md) |
 | `fix` | Lifecycle | Reproduce root cause with failing test, execute surgical fix, and audit | [reference/fix.md](reference/fix.md) |
 | `test` | Verification | Run stack test runner and verify clean green exit code | [reference/test.md](reference/test.md) |
-| `audit` | Verification | Run mandatory educational audit gate & AST validation | [reference/audit.md](reference/audit.md) |
-| `doctor` | Diagnostics | Check configuration health, hook parity, symlinks & AST engine | [reference/doctor.md](reference/doctor.md) |
+| `audit` | Verification | Run mandatory educational audit gate & guard checks | [reference/audit.md](reference/audit.md) |
+| `doctor` | Diagnostics | Check configuration health, hook parity, symlinks & guard scripts | [reference/doctor.md](reference/doctor.md) |
 | `commit` | Version Control | Pre-flight audit, verify SDD scope, and commit with Conventional Commits | [reference/commit.md](reference/commit.md) |
 | `update` | Maintenance | Non-destructive update: refresh core tools, playbooks & symlinks (preserves SDDs & custom guards) | [reference/update.md](reference/update.md) |
-| `start` | Setup | Discover tech stack & initialize `.clckernel.yaml` | [reference/start.md](reference/start.md) |
-| `create_guard` | Safeguards | Scaffold a new AST/linter guard in native stack language | [reference/guard.md](reference/guard.md) |
+| `start` | Setup | Discover tech stack, install the harness if missing (`npx clckernel . --yes`) & propose an optional `.clckernel.yaml` | [reference/start.md](reference/start.md) |
+| `create_guard` | Safeguards | Scaffold a new pattern-based/linter guard in native stack language | [reference/guard.md](reference/guard.md) |
 | `remove_guard` | Safeguards | Safely remove an existing guard and clean up config | [reference/guard.md](reference/guard.md) |
 | `phase` | Lifecycle | Add or remove pipeline execution phases | [reference/phase.md](reference/phase.md) |
 
@@ -43,4 +45,19 @@ When the developer issues a \`clckernel <command>\` or \`/clckernel <command>\`
    - *"Auditar / verificar arquitectura"* -> Route to `audit` ([reference/audit.md](reference/audit.md))
    - *"Revisar estado / diagnóstico"* -> Route to `doctor` ([reference/doctor.md](reference/doctor.md))
    - *"Commitear / guardar cambios"* -> Route to `commit` ([reference/commit.md](reference/commit.md))
-4. **Mandatory Audit Gate:** Never declare success on code changes without running the audit gate and outputting the summary.
+4. **First session after install** (`tools/.clckernel-managed.json` exists, `.clckernel.yaml` does not):
+   follow the "First session after install" section of AGENTS.md. The user's own request comes first;
+   otherwise explain briefly what is installed, ask ONE question (run [reference/start.md](reference/start.md)
+   or keep the defaults) and STOP.
+5. **Mandatory Audit Gate:** Never declare success on code changes without running the audit gate and outputting the summary.
+
+## Human checkpoint
+
+The user's explicit approval is required before any step that changes shared state or cannot be undone. At each checkpoint, show what will happen, stop, and wait for a clear "yes"; silence, an earlier approval, or approval of a different step does not count.
+
+- **Spec before code:** after writing the spec for `feature` (or the root-cause plan for `fix`), present it and wait for approval before writing tests or code.
+- **Before committing:** show the staged files, the audit result and the commit message, and wait for approval before running `git commit`.
+- **Before publishing:** never push, open a pull request, tag or release without the user's explicit request.
+- **Before destructive actions:** removing a guard or phase, deleting files, or overwriting files the project edited locally requires approval of the exact list of paths.
+
+If the user declines, stop and report the current state; do not retry or look for a workaround.

package/.agents/skills/clckernel_cli/reference/audit.md

@@ -4,13 +4,23 @@ Use this playbook when auditing code quality, architecture compliance, or execut
 
 ## Execution
 
-1. **Locate Audit Tool:** Check available audit scripts:
+1. **Locate Audit Tool:** `npx clckernel audit [dir] [--change <name>]` runs every installed orchestrator for you. Or check the available audit scripts:
    - `node tools/audit.js` (JavaScript / Node environment)
    - `python tools/audit.py` (Python / Backend environment)
-2. **Execute Audit:** Run the tool within project workspace.
+2. **Execute Audit:** Run the tool within the project workspace. CLI (both scripts):
+   `audit.(js|py) [targetDir] [--change <name>] [--staged]`.
+   - Working on an SDD change (`sdds/<name>/`): pass `--change <name>`. Only then are the report
+     (`05-audit-report.md`) and the receipt (`audit-receipt.json`) written, in `sdds/<name>/`.
+     On a mixed stack (both `tools/audit.js` and `tools/audit.py` installed) each orchestrator
+     writes its own pair: `05-audit-report.js.md` + `audit-receipt.js.json` and
+     `05-audit-report.py.md` + `audit-receipt.py.json`. Read both.
+   - Without `--change` nothing is written: read the summary from stdout.
+   - `--staged` is the default snapshot (staged changes, or the last commit when nothing is staged).
+   - An unknown flag exits 2 with the usage line: fix the command, do not report it as a guard failure.
 3. **Educational Summary:** Output the educational audit summary highlighting:
-   - AST Architectural conformance
+   - Architectural conformance (layer-boundary guards)
    - TDD compliance & test coverage
    - Security & Secrets scan results
    - Performance / DB efficiency checks
 4. **Actionable Feedback:** If any guard fails, explain the exact violation, why it breaches architectural invariants, and how to remediate it.
+5. **Warnings:** A guard marked `WARN` / ⚠️ (level `warning`, from the guard or `severities` in `.clckernel.yaml`) failed but does not block: the verdict is `PASSED_WITH_WARNINGS`. Report it and propose the fix; do not hide it. A guard that crashed always blocks.

package/.agents/skills/clckernel_cli/reference/commit.md

@@ -4,7 +4,7 @@ Safely commit changes after verifying all pre-flight quality and architecture ga
 
 ## Mandatory Execution Protocol
 
-### Step 1: Pre-Flight AST Audit
+### Step 1: Pre-Flight Guard Audit
 1. Run \`node tools/audit.js\` or \`python tools/audit.py\`.
 2. Ensure 100% of discovered guards pass with 0 errors and 0 secret leaks.
 

package/.agents/skills/clckernel_cli/reference/doctor.md

@@ -4,7 +4,9 @@ Use this playbook to diagnose environment health, detect hook drift, or verify c
 
 ## Checks
 
-1. **Config Integrity:** Validate `.clckernel.yaml` syntax and presence of required sections (`framework`, `language`, `project_type`, `safeguards`).
-2. **Hook Parity:** Check that git hooks (`.githooks/pre-commit` or `.husky/pre-commit`) are installed and executable (`chmod +x`).
-3. **Tools & Guards Health:** Verify that scripts referenced in `.clckernel.yaml` exist in `tools/` and run without syntax errors.
+Start with `npx clckernel doctor [dir]`: it checks `AGENTS.md`, `sdds/`, `docs/Journal/`, `tools/`, the pre-commit hook, that each `tools/check_*` guard loads (JS) or parses (Python), and the orchestrators' imports. Then:
+
+1. **Config Integrity:** When `.clckernel.yaml` exists, check its keys against the README "Configuration" table (`rules`, `exclude_paths`, `mirrors`, `hitl`, `update`, `tdd`, `severities`); report any invalid value or deprecated key the guards warn about.
+2. **Hook Parity:** Check that the hook git runs (`.githooks/pre-commit` with `core.hooksPath=.githooks`, or `.husky/pre-commit` when Husky owns `core.hooksPath`) is executable and calls `node tools/audit.js --hook` and/or `python3 tools/audit.py --hook`.
+3. **Tools & Guards Health:** Run `npx clckernel audit`: it runs every guard the hook runs (kernel guards and project guards in `tools/guards/`).
 4. **Drift Remediation:** If drift is detected, offer automatic fix or report clear steps.

package/.agents/skills/clckernel_cli/reference/feature.md

@@ -32,7 +32,7 @@ Guide the developer through implementing a new feature strictly governed by the
 2. Maintain strict Clean Architecture boundaries (Domain -> Use Case -> Infrastructure).
 3. Re-run tests to confirm 100% green pass.
 
-### Step 6: Mandatory AST Audit Gate
-1. Execute \`node tools/audit.js\` or \`python tools/audit.py\`.
+### Step 6: Mandatory Audit Gate
+1. Execute \`node tools/audit.js --change <name>\` or \`python tools/audit.py --change <name>\` (writes the report and receipt to \`sdds/<name>/\`).
 2. Output the Educational Summary table to stdout.
-3. Verify zero secrets, zero layer violations, and zero N+1 queries.
+3. Verify zero secret findings, zero layer violations, and zero N+1 heuristic findings.

package/.agents/skills/clckernel_cli/reference/guard.md

@@ -1,23 +1,59 @@
 # Playbook: Safeguards Management (Create & Remove)
 
-Use this playbook when the user wants to add, modify, or delete custom architecture/security guards (via `/clc create_guard`, `/clc remove_guard`, or natural language like *"creá un guard para bloquear imports prohibidos"*).
+Use this playbook when the user wants to add, modify, or delete a project guard (via `/clc create_guard`, `/clc remove_guard`, or natural language like *"creá un guard para bloquear imports prohibidos"*).
+
+Project guards hold the rules of this project's domain; the kernel ships none. They are project code: never listed in `tools/.clckernel-managed.json`, preserved by `clckernel update`, and evaluated by the other guards like any other file. Put them in `tools/guards/` (any `*.js` / `*.py` name). A guard file at the top of `tools/` whose name starts with `check_`, `scan_` or `verify_` (or ends with `_guard`) and that the registry does not list is a project guard too — for example a kernel guard the kernel no longer ships, which `clckernel update` leaves in place.
+
+## How project guards run
+
+- **One discovery, two entry points:** the pre-commit hook calls `node tools/audit.js --hook` and `python3 tools/audit.py --hook` (each when installed); `clckernel audit` runs the same orchestrators without `--hook`. Both run exactly the same guards — the kernel guards and every project guard — each once, from the repository root. Adding a guard needs no `clckernel update`.
+- **Which orchestrator runs which guard:** `audit.js` runs the `.js` guards and `audit.py` the `.py` ones. When a project has only one orchestrator (e.g. a Node stack without `tools/audit.py`), that one also runs the other language's guards (`python3` / `node`).
+- **Audit:** the report lists them (architecture lens unless the JSON result names another). `--hook` writes no report: it prints one line per guard and the details of each failure.
+- **Contract:** a non-zero exit code blocks the commit and fails the audit. Printing the standard JSON result is optional; when present the audit uses it for the report: `{ "exitCode": 0, "skipped": false, "name": "check_x", "data": { "message": "...", "violations": [{ "file": "...", "message": "..." }] } }` (optional `"lens"`: `correctness`, `security`, `architecture` or `performance`). Plain output is reported by its last line.
+- **Snapshot helpers:** evaluate the commit being made, not the working copy. A JS guard imports `require('../_changes')`; a Python guard imports `_changes` after adding the parent directory to `sys.path`. Each helper exists only when the harness installed it (`tools/_changes.js` with JS guards, `tools/_changes.py` with Python guards).
 
 ## 🛠️ Create Guard
 
-1. **Clarify Objective:** If not specified, ask what AST node, pattern, or security risk to intercept. **STOP.** Wait for details.
-2. **Native Language Implementation:** Write the guard script in the native stack language:
-   - Python projects -> Python `ast` script in `tools/guards/<name>_guard.py`
-   - Node / TS projects -> JS/TS script in `tools/guards/<name>_guard.js`
-   - Go projects -> Go `go/parser` / `ast` script
-   - Ruby projects -> Ruby `parser` gem script
-3. **Register in Config:** Add the guard definition under `custom_safeguards` or `tools` in `.clckernel.yaml`.
-4. **Validation:** Run the script against test fixtures to confirm it flags violations and exits cleanly on compliant code.
+1. **Clarify Objective:** If not specified, ask what pattern, rule, or risk to intercept. **STOP.** Wait for details.
+2. **Write the guard** in `tools/guards/<name>.js` (Node) or `tools/guards/<name>.py` (Python). Only these two extensions run; use the one whose snapshot helper the project has. Minimal working examples:
+
+   ```js
+   // tools/guards/check_no_draft_json.js
+   const { changedFiles, readFile } = require('../_changes');
+
+   const { mode, files } = changedFiles(process.cwd(), { extensions: ['.json'] });
+   const violations = files
+     .filter((file) => (readFile(process.cwd(), file, mode) || '').includes('"draft": true'))
+     .map((file) => ({ file, message: 'draft data must not be committed' }));
+   const exitCode = violations.length > 0 ? 1 : 0;
+   console.log(JSON.stringify({ exitCode, skipped: false, name: 'check_no_draft_json', data: { message: `${violations.length} violation(s)`, violations } }));
+   process.exit(exitCode);
+   ```
+
+   ```python
+   # tools/guards/check_no_draft_json.py
+   import json, pathlib, sys
+   sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))
+   from _changes import changed_files, read_file
+
+   snapshot = changed_files(".", extensions=[".json"])
+   violations = [
+       {"file": f, "message": "draft data must not be committed"}
+       for f in snapshot["files"]
+       if '"draft": true' in (read_file(".", f, snapshot["mode"]) or "")
+   ]
+   exit_code = 1 if violations else 0
+   print(json.dumps({"exitCode": exit_code, "skipped": False, "name": "check_no_draft_json",
+                     "data": {"message": f"{len(violations)} violation(s)", "violations": violations}}))
+   sys.exit(exit_code)
+   ```
+
+3. **Validation:** stage a violating file and run `node tools/guards/<name>.js` (or `python3 tools/guards/<name>.py`): it must exit 1. Stage a compliant one: it must exit 0. Then run `node tools/audit.js` to see it reported.
 
 ---
 
 ## 🗑️ Remove Guard
 
 1. Identify the target guard from user request or ask for confirmation.
-2. Update `.clckernel.yaml` removing the guard entry.
-3. If requested, delete the corresponding file from `tools/guards/`.
-4. Confirm removal cleanly.
+2. Delete the corresponding file from `tools/guards/` (or the top of `tools/`): the hook and the audit stop running it; nothing else to update. A kernel guard listed in `tools/.clckernel-managed.json` cannot be removed by deleting it (the hook fails on a missing kernel guard); exclude it with `update.exclude` in `.clckernel.yaml` instead.
+3. Confirm removal cleanly.

package/.agents/skills/clckernel_cli/reference/phase.md

@@ -7,12 +7,15 @@ Use this playbook when adding, modifying, or removing lifecycle phases in the AI
 1. **Understand Phase Purpose:**
    - Pre-implementation (e.g. Research, SDD spec, RFC alignment)
    - Implementation (e.g. TDD Red/Green, Layer Check)
-   - Verification / Audit (e.g. AST Audit, E2E, Smoke test)
+   - Verification / Audit (e.g. Guard Audit, E2E, Smoke test)
    - Delivery (e.g. Git pre-commit, PR generation)
 
-2. **Update `.clckernel.yaml`:**
+2. **Update `AGENTS.md`:**
+   - Phases are agent instructions: record the new order in the Loop section of `AGENTS.md`, never in
+     `.clckernel.yaml` (its `phases` key is deprecated and has no effect).
    - Preserve execution order and dependencies.
-   - Specify whether the phase is blocking (`required: true`) or advisory (`required: false`).
+   - Say whether the phase is blocking or advisory; a blocking check belongs in a guard under
+     `tools/guards/`, which the pre-commit hook runs.
 
 3. **Confirm & Validate:**
    - Present the updated pipeline flow to the user.

package/.agents/skills/clckernel_cli/reference/start.md

@@ -1,6 +1,7 @@
 # Playbook: Start / Initialize CLC Kernel
 
 Use this playbook when the user wants to initialize, start, or set up governance in a project (via `/clc start`, `/clckernel start`, or conversational request like *"inicializar el proyecto con clc"*).
+It is also the playbook offered in the first session after install (AGENTS.md, "First session after install").
 
 ## Sequence
 
@@ -17,12 +18,21 @@ Use this playbook when the user wants to initialize, start, or set up governance
 
 ### Phase 2: Interactive Alignment
 Present detected stack and proposal clearly:
-1. Summarize detected architecture and auto-provisioned safeguards (e.g., TDD Red/Green, AST architecture guard, DB efficiency, secrets scan, tech-specific guards).
+1. Summarize detected architecture and auto-provisioned safeguards (e.g., Red→Green TDD verifier on FastAPI/Django, architecture guard, N+1 heuristic, secrets scan, tech-specific guards).
 2. Ask one clear question:
    - *"¿Activamos estas fases y salvaguardas estándar, o querés personalizar alguna regla o fase?"*
 3. **STOP.** Wait for the user's response.
 
 ### Phase 3: Materialization
-1. Write or update `.clckernel.yaml` at project root.
-2. If hooks are configured, ensure `.githooks/pre-commit` or `.husky/pre-commit` are provisioned.
-3. Confirm completion with a concise summary.
+1. If the harness is not installed (no `AGENTS.md` / `tools/audit.js` / `tools/audit.py`), run
+   `npx clckernel . --yes` (`--dry-run` first to show the plan). The CLI writes the guards, the
+   pre-commit hook (`.githooks/pre-commit`, or `.husky/pre-commit` when Husky already runs the
+   repository's hooks), the playbooks and the IDE mirrors. Never write the hook by hand.
+2. `.clckernel.yaml` is optional: without it every default applies. Write keys only when the user
+   chose a customization, only with the keys the README "Configuration" table lists (`rules`,
+   `exclude_paths`, `mirrors`, `hitl`, `update`, `tdd`, `severities`) and only what differs from the
+   defaults.
+3. If the user keeps the defaults, write a `.clckernel.yaml` that holds only a comment (for example
+   `# CLC Kernel: defaults accepted. Add keys only for settings that differ.`). It parses to the
+   defaults and ends the first-session onboarding, so the question is not asked again.
+4. Confirm completion with a concise summary.

package/.agents/skills/clckernel_cli/reference/test.md

@@ -5,7 +5,7 @@ Execute the repository test suite within the native environment runner.
 ## Mandatory Execution Protocol
 
 ### Step 1: Detect Test Runner
-1. Inspect \`.clckernel.yaml\` or project files to identify the configured test runner:
+1. Inspect the project files to identify the test runner:
    - Node: \`npm test\` / \`vitest\` / \`jest\`
    - Python: \`pytest\`
    - Go: \`go test ./...\`

package/.agents/skills/clckernel_cli/reference/update.md

@@ -5,29 +5,29 @@ Use this playbook when the user wants to update an existing project to the lates
 ## Invariants: The Non-Destructive Update Contract
 
 1. **NEVER DELETE OR OVERWRITE `sdds/`:** All local specifications (`sdds/*/spec.md`, `plan.md`) must stay 100% intact.
-2. **NEVER TOUCH CUSTOM GUARDS:** Any user-defined scripts under `tools/guards/` are preserved without alteration.
-3. **NEVER OVERWRITE CONFIGURATION:** Existing `.clckernel.yaml` or `.clc-forge.yaml` settings and custom thresholds remain intact.
-4. **NEVER MODIFY APPLICATION CODE:** Source files, domain layers, and application tests are never touched.
+2. **NEVER TOUCH PROJECT GUARDS:** Scripts under `tools/guards/` and unmanaged guard files at the top of `tools/` are preserved without alteration. A kernel guard the new release no longer ships stays where it is and keeps running as a project guard; nothing is moved or deleted.
+3. **NEVER OVERWRITE CONFIGURATION:** Existing `.clckernel.yaml` settings (or a config under an older name) remain intact.
+4. **NEVER OVERWRITE EDITED KERNEL FILES:** A kernel file the project edited is kept; the new version is written next to it as `<file>.clckernel-new`.
+5. **NEVER MODIFY APPLICATION CODE:** Source files, domain layers, and application tests are never touched.
 
 ## Update Sequence
 
-### Phase 1: Inspection & Detection
-1. Verify the project is already governed by checking for `AGENTS.md`, `.clckernel.yaml`, `.husky/pre-commit`, or `.githooks/pre-commit`.
-2. Inspect the active framework and test runner.
+### Phase 1: Inspection & Plan
+1. Verify the project is already governed by checking for `AGENTS.md`, `tools/.clckernel-managed.json`, `.githooks/pre-commit` or `.husky/pre-commit`.
+2. Run `npx clckernel update [dir] --dry-run` and show the plan (written, kept, excluded by `update.exclude`). Nothing is written.
+3. **STOP.** Wait for the user's approval of the plan.
 
-### Phase 2: Refresh Core Infrastructure
-1. Refresh bundled AST audit tools in `tools/`:
-   - `tools/audit.js` / `tools/audit.py`
-   - Built-in guards (`scan_secrets.js`, `check_responsive.js`, `check_seo.js`, `check_db_efficiency.py`, `check_custom.js`, `docker_guard.py`, etc.)
-2. Refresh Agent Skills & Playbooks:
-   - Synchronize `.agents/skills/clckernel_cli/` with latest playbooks and references.
-3. Refresh Cross-IDE Rule Symlinks:
-   - Ensure `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, and `.antigravity/rules.md` link to `AGENTS.md`.
-4. Refresh Pre-commit Hook:
-   - Ensure the git pre-commit hook runs the latest standard guards while preserving any custom checks.
+### Phase 2: Run the Update
+1. Run `npx clckernel update [dir]`. It refreshes, in one pass:
+   - the kernel tools the project already has in `tools/` (`audit.js` / `audit.py`, guards, helpers) — update never adds a guard the project did not choose;
+   - the skill and playbooks in `.agents/skills/clckernel_cli/`;
+   - the IDE mirrors that link to `AGENTS.md`;
+   - the pre-commit hook, which calls `node tools/audit.js --hook` and/or `python3 tools/audit.py --hook` (every kernel and project guard, once) and then the stack's external tools when they are available.
+2. To install additional guards, add `--add-guards <a,b|all>` (e.g. `npx clckernel update . --add-guards check_skills`), only with the user's approval.
+3. Never copy or edit kernel files by hand to "refresh" them.
 
 ### Phase 3: Verification & Reporting
-1. Run `node tools/audit.js` or `python tools/audit.py` to verify harness health.
+1. Run `npx clckernel audit` (or `node tools/audit.js` / `python3 tools/audit.py`) to verify harness health.
 2. Output a transparent Educational Summary highlighting:
-   - What was updated (core tools, playbooks, symlinks)
-   - What was preserved (SDDs, custom guards, YAML configuration)
+   - What was updated (core tools, hook, playbooks, symlinks)
+   - What was preserved (SDDs, project guards, edited files kept with a `.clckernel-new` copy, YAML configuration)

package/CHANGELOG.md

@@ -0,0 +1,250 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Fixed
+
+- `npx clckernel` no longer prints the `clc-forge` deprecation notice. The legacy `clc-forge` and
+  `create-clc-forge` binaries now point to `bin/deprecated.js`, so npx runs the bin named like the package
+  instead of the first (alphabetically sorted) one.
+
+## [2.0.0] - 2026-10-26
+
+### ⚠ BREAKING CHANGES
+
+- **Strict YAML subset for `.clckernel.yaml`.** `check_custom` (JS and Python) now parses a documented YAML
+  subset and fails closed: a config that relied on lenient parsing, or that contains invalid rules or invalid
+  regexes, now fails the pre-commit hook instead of being silently skipped.
+- **Frontend hook location.** On Next.js and Astro projects the pre-commit hook is written to `.husky/` only
+  when Husky is active; otherwise it goes to `.githooks/` with `core.hooksPath`. Re-running `update` may move
+  your hook.
+- **Legacy `clc-forge` artifacts.** Installs no longer create the `clc_forge_cli` skill, the
+  `clc_forge_context.mdc` Cursor rule or `.clc-forge.resolved.json`, and `clckernel update` removes them when
+  they are provably harness-generated (it reports anything it keeps).
+- **`check_hitl` requires an explicit marker.** A changed skill or playbook must contain a `HITL:` line or a
+  `## Human checkpoint` / `## HITL` section; words such as "review" or "confirm" no longer pass. The guard now
+  also covers `playbooks/` and evaluates the files changed in the commit. Existing Agent-OS repositories may
+  start failing when they touch a skill or playbook without a marker.
+- **Domain guards leave the kernel.** `check_domain_data` and `check_test_calendar_sync` are no longer shipped
+  or installed, and Agent-OS detection no longer reacts to the `marketing-os` / `laila-mos` names or a
+  "marketing operating system" description (`agent-os` and `ai-agents` still work). `clckernel update` leaves
+  copies installed by earlier releases exactly where they are in `tools/` (never moves or deletes them), takes
+  them out of the registry and reports them as retired kernel guards, so they keep running as project guards.
+- **The pre-commit hook and `clckernel audit` run the same guards (sdds/unified-discovery).** The generated hook
+  no longer lists one line per guard plus a `tools/guards/` loop: it calls `node tools/audit.js --hook` and
+  `python3 tools/audit.py --hook` (each when installed; with neither the commit fails), then the external tools.
+  The orchestrators discover every guard — kernel guards and project guards, both `tools/guards/*` and
+  unmanaged `check_*` / `scan_*` / `verify_*` / `*_guard` files at the top of `tools/` — and run each exactly
+  once (`.js` via `audit.js`, `.py` via `audit.py`; a lone orchestrator runs both languages). A project guard
+  placed at the top of `tools/`, previously run only by `clckernel audit`, now also blocks commits. A guard the
+  registry lists but that is missing on disk now fails the hook and the audit. `--hook` writes no report or
+  receipt and prints one line per guard. Re-run `clckernel update` to get the new hook.
+- **Retired kernel guards stay in place.** A guard in the registry that the current kernel no longer ships is
+  kept where it is (no move to `tools/guards/`, which broke guards that `require` a sibling such as
+  `./_changes`), leaves the registry, and `update` reports it as "retired kernel guard kept as project guard".
+  `updateHarness()` returns `retiredGuards` instead of `guardMigration`.
+- **`.clckernel.yaml` is read by install, update and the guards; keys without an effect are gone
+  (sdds/config-foundation).** `active_guards`, `phases`, `gate_mode`, `layers` and `scope` never
+  changed anything: they now print a deprecation warning and are ignored (`severities` got a real effect in
+  sdds/audit-cli, below). The config-driven metadata path (`.clckernel.resolved.json`, `CLCKERNEL_SEVERITIES`) is
+  removed. An invalid value now stops install, update and every guard with
+  `Invalid .clckernel.yaml: key "<key>" — <reason>`.
+- **The audit writes a report only when told where (sdds/audit-cli).** `node tools/audit.js`,
+  `python3 tools/audit.py` and `clckernel audit` used to write `05-audit-report.md` and `audit-receipt.json`
+  into a guessed folder (the first directory under `sdds/`, or `sdds/audit-run/`), i.e. into an unrelated spec.
+  Now a plain run only prints the summary; `--change <name>` (also `clckernel audit [dir] --change <name>`)
+  writes both files to `sdds/<name>/`, creating that folder only then. `<name>` must be one path segment.
+  The orchestrators take `[targetDir] [--hook] [--change <name>] [--staged]`; any other flag, a second
+  positional or `--hook` with `--change` exits 2 with the usage (unknown flags used to be ignored). The Python
+  orchestrator now resolves `sdds/` against the target directory, like the JS one. Agents that need the report
+  must pass `--change <sdd name>`: re-run `clckernel update` to get the AGENTS.md and playbook wording.
+
+### Added
+
+- **Onboarding after install (sdds/onboarding).** A real install ends with a "Next steps" block true to that
+  install: commit the harness (or the exact command that activates the hook when it is not active), the AI
+  harnesses whose mirrors were written, `clckernel start`, `npx clckernel audit`, `tools/guards/` and
+  `npx clckernel update --dry-run`. An update prints a short one only when protected `*.clckernel-new` files or
+  available guards need attention. Every generated AGENTS.md gains a "First session after install" section, and
+  the skill triggers on it: the user's request comes first; otherwise the agent explains what is installed, asks
+  one question (run the `start` playbook or keep the defaults) and stops.
+- **Red→Green TDD verification for Go, Rust, Ruby and PHP (sdds/tdd-other-stacks).** `tools/verify_tdd.js`
+  gains language profiles (`go test`, `cargo test --test`, RSpec / Minitest through bundler, Pest / PHPUnit),
+  grouped by the nearest `go.mod` / `Cargo.toml` / `Gemfile` / `composer.json`, and is installed for the Go,
+  Rust, Rails and Laravel stacks: their commits now fail when production code changes without a test that
+  fails on `HEAD` and passes on the staged code. A missing toolchain fails closed with an install hint. Rust
+  unit tests inside `src/` cannot be separated for the red run: a `src/` change needs an integration test.
+- **Wider secret coverage in `scan_secrets` (sdds/secret-patterns).** New labels: `Anthropic API Key`,
+  `OpenAI Project Key` (project, service-account and admin keys), `Google API Key`, `Slack Token`, `GitHub Token`
+  (OAuth, user, server and refresh prefixes) and `GitHub Fine-Grained PAT`. `Quoted Key Secret` flags a quoted
+  JSON/YAML key (`"api_key": "…"`) whose value holds a letter and a digit. `Dotenv Secret` flags a committed
+  `.env`, `.env.*` or `*.env` file (unquoted values included) when a secret-looking variable has a real value;
+  `.env.example`, `.env.sample` and `.env.template` are left alone. Both generic rules skip placeholders (`${VAR}`,
+  `<…>`, `changeme`, `your-…`, `xxx`, one repeated character, …). Existing labels are unchanged. The pure matcher
+  is exported as `findSecrets(text, filename)` (JS) and `find_secrets(text, filename)` (Python).
+
+- **Non-blocking warnings in the audit and the pre-commit hook (sdds/audit-cli).** A guard result may carry
+  `level: 'warning'`, and `.clckernel.yaml` `severities: { <guard name>: warning | error }` sets it per guard
+  (overriding the guard; values are validated — the key is no longer deprecated). A failing guard at `warning`
+  prints `WARN`, does not change the exit code, and is listed separately in the report and in the receipt's
+  `warnings`; the verdict is `PASSED_WITH_WARNINGS` when only warnings failed. A guard that crashes (throws,
+  returns no result, cannot run, or is missing) always blocks, whatever its severity. `--staged` is accepted as
+  an explicit name for the default snapshot (staged changes, else the last commit).
+
+- **Configuration keys with a real effect (sdds/config-foundation).** `exclude_paths` (paths no diff-based guard
+  evaluates), `mirrors.list` / `mirrors.required` (mirrors install creates and `check_symlinks` verifies),
+  `hitl.markers` / `hitl.paths` / `hitl.optOut` (`check_hitl`), `update.exclude` (paths install/update never
+  write; reported as *excluded by config*) and `tdd.code` / `tdd.ignore` (what `verify_tdd.js/.py` count as
+  production code, e.g. Python tools tested by JS tests). Defaults keep the earlier behaviour. One schema in
+  `tools/_config.js` and its twin `tools/_config.py` (the Python YAML fallback parser moved to `tools/_yaml.py`),
+  installed next to `_changes.js/.py`. README "Configuration" lists every key.
+
+- **Safe `update` and `--dry-run` (sdds/safe-update).** `clckernel update` and a reinstall with `--yes` never
+  overwrite a kernel file (`tools/*`, the pre-commit hook, the `clckernel_cli` skill) they cannot prove is
+  theirs and intact: a locally edited file, or a project file that only shares a kernel file's name, is kept
+  and the new version is written as `<file>.clckernel-new` (added to the consumer `.gitignore`). An older
+  intact install without hashes still updates silently: `src/known-hashes.json` holds the sha256 of every
+  version the kernel published (built from the git history by `scripts/build-known-hashes.js`).
+  `--dry-run` (`clckernel update [dir] --dry-run`, `clckernel [dir] --yes --dry-run`) prints the plan and
+  writes nothing — no files, directories, `.gitignore` or `git config`.
+
+- **Full-stack and monorepo support.** The detector finds code parts at the root, in declared workspaces
+  (`package.json#workspaces`, `pnpm-workspace.yaml`) and in conventional directories (`frontend`, `backend`,
+  `web`, `api`, `server`, `client`, `apps/*`, `services/*`, `packages/*`). Several parts install the union of
+  their guards once, run each part's external tools inside its directory, list the parts in AGENTS.md and in
+  the install summary, and `update` re-detects them. `verify_tdd.py` and `verify_tdd.js` group the changed
+  files by their nearest project root and verify red→green per group; code changed in a part without a test
+  in that part fails. A repository with a single part at its root is installed exactly as before.
+- `tools/verify_tdd.py` now runs the changed tests with pytest and requires them to fail on the base tree and
+  pass on the staged tree; it is installed for FastAPI and Django.
+- `tools/verify_tdd.js`, its twin for vitest, jest and node:test, installed for Next.js, Astro and Agent-OS.
+- `tools/_changes.js` / `tools/_changes.py`: guards read the staged snapshot (or `HEAD` when nothing is staged)
+  instead of the working copy.
+- `clckernel audit [dir]` runs every installed audit orchestrator.
+- `tools/.clckernel-managed.json` registry, so guards and both TDD verifiers skip the harness's own files and
+  the first commit after an install passes the real hook.
+- `scan_secrets` detects Stripe `sk_`/`rk_` live and test keys.
+- Generic Agent-OS detection: `SKILL.md` in `skills/<name>/`, `.agents/skills/<name>/` or
+  `.claude/skills/<name>/`, or a `playbooks/` / `rules/` folder with Markdown (the `package.json` keywords
+  still work). The harness's own skill is ignored, and a code stack in the same repository wins.
+- Agent-OS guards `check_skills` (SKILL.md frontmatter: `name`, `description`, unique names),
+  `check_links` (relative Markdown links resolve in the commit) and `check_placeholders` (forgotten draft
+  markers outside `templates/`); `check_custom` is now installed for Agent-OS.
+- `listFiles` / `list_files` in `tools/_changes.*`: every file of the snapshot being verified.
+- **Project guards run.** Every generated pre-commit hook ends with a generic block that runs each
+  `tools/guards/*.js` with `node` and `tools/guards/*.py` with `python3` (alphabetical, after the kernel guards;
+  no-op without `tools/guards/`), and `audit.js` / `audit.py` report them. A non-zero exit blocks; the standard
+  JSON result is used when printed. Guards can import the snapshot helpers (`require('../_changes')`).
+- Agent-OS guard `check_data_files`: every changed `.json` file must parse (snapshot content, any folder).
+- CI on Node 18/20/22 and Python 3.9/3.13 (without PyYAML), plus a shared YAML conformance suite and
+  regression tests for documentation claims and repository hygiene.
+
+### Changed
+
+- **Mixed stacks keep both audit reports (sdds/residual-fixes).** When `tools/audit.js` and `tools/audit.py`
+  are both installed, `--change <name>` makes each orchestrator write its own pair:
+  `05-audit-report.js.md` + `audit-receipt.js.json` and `05-audit-report.py.md` + `audit-receipt.py.json`
+  (before, `clckernel audit --change` ran both and the second overwrote the first). Single-orchestrator
+  projects keep `05-audit-report.md` and `audit-receipt.json`.
+- **`update` never adds what the project did not choose.** It refreshes only the guards the project has (in
+  the registry or present in `tools/`) and runs only those in the hook; the stack's other guards are listed
+  as *available, not installed* and opted in with the new `clckernel update --add-guards <name,...|all>`
+  (an unknown name exits 1 without writing). It no longer recreates IDE mirrors the project deleted (*not
+  present (skipped)*), and neither install nor update adds a `.gitignore` entry for a path git tracks
+  (*tracked, not ignored*). `--dry-run` shows the three new sections. A part added to a monorepo gets its
+  external tools on update; its guards are offered as available.
+- **The kernel skill obeys `check_hitl`.** `check_hitl` no longer exempts `clckernel_cli` (it also reads
+  registry-listed files, via the new `includeManaged` option of `_changes.js`); the skill gains a
+  `## Human checkpoint` section: approval before code after a spec, before committing, before destructive
+  steps, and no publishing without an explicit request. The retired `clc_forge_cli` and vendored plugin
+  skills (`impeccable`) stay exempt.
+- **Hashed registry.** `tools/.clckernel-managed.json` is now `{ "kernelVersion", "files": [{ "path",
+  "sha256" }] }` and also covers the hook and the skill; `_changes.js`/`_changes.py` read both this and the
+  older list format, and `update` migrates it. Protected files are left out of it.
+- **Every install/update write goes through `src/io.js`**, one write point that applies the ownership rule and
+  records the plan. The `update` summary now lists written, unchanged, protected, moved, removed, `.gitignore`
+  and `git config` changes, and exits 0 with a visible warning when files were protected. `update` rejects
+  unknown flags.
+- **Old domain guards are moved only when intact.** A locally modified `tools/check_domain_data.js` or
+  `tools/check_test_calendar_sync.js` stays in `tools/` with a warning instead of being moved.
+
+- Generated hooks run under `set -e` without `|| true`; audit orchestrators report a crashing guard as
+  FAILED.
+- Hooks run each stack's external tools (ruff, pytest, rubocop, rspec, phpstan, golangci-lint, go test, cargo)
+  when available and print "not available, skipped" otherwise; Rails, Go, Laravel and Rust run the secret scan.
+- Choosing another stack in the prompt selects a real adapter instead of only changing the project type.
+- Agent-OS: the kernel installs only guards that hold for any Agent-OS (domain rules belong in the project's
+  `tools/guards/`); `check_symlinks` also fails a rule mirror that does not point to `AGENTS.md` (symlink or
+  identical copy); the generated `AGENTS.md` describes only the folders the repository has, and its Clean
+  Creation State rule is domain-neutral (a field without a real value stays empty or `null`).
+- The CLI refuses missing targets and reserved words as directories, sets `core.hooksPath` only at the
+  repository root when unset or already `.githooks`, and `doctor` exits 1 when a check fails.
+- `scan_secrets` redacts detected secrets in its output.
+- Documentation, the website and generated `AGENTS.md` describe guards by what they check and drop claims the
+  code does not support.
+
+### Fixed
+
+- A fresh install no longer adds `.agents/skills/clc_forge_cli/`, `.clckernel.resolved.json` or
+  `.clc-forge.resolved.json` to `.gitignore`; each is added only when that artifact exists in the project.
+- `check_scope.py` reads paths that start with a dot (`.agents/...`, `.clckernel.yaml`,
+  `.github/workflows/ci.yml`; extension-less dotfiles such as `` `.gitignore` `` in backticks) and no longer
+  truncates table cells (`| src/foo.js |` was read as `oo.js`) (sdds/final-sweep).
+- Docs and website describe the real hook (`.githooks/pre-commit` calling `tools/audit.js --hook` /
+  `tools/audit.py --hook`, `.husky/pre-commit` only when Husky already runs the hooks), the real install
+  command (`npx clckernel` / `npx clckernel . --yes`; `start` is an agent command) and only real
+  `.clckernel.yaml` keys. The AGENTS.md command tables and the playbooks name the CLI options (`--change`,
+  `--dry-run`, `--add-guards`) and no longer say `start` materializes `.clckernel.yaml`; the READMEs gained
+  a "Known limitations" section (sdds/final-sweep).
+- Install/update decide from the repository's own (`--local`) `core.hooksPath`: a global or system value
+  (a user-wide hooks dir) no longer blocks setting `.githooks` nor makes a frontend project look like Husky.
+  The local value is set and a note says a global `core.hooksPath` is configured (sdds/residual-fixes).
+- `check_architecture.py` decides Django vs Clean Architecture per changed file, from its nearest project root
+  (`manage.py`, `pyproject.toml`, `setup.cfg`, `requirements*.txt`), so a Django app in `backend/` or
+  `apps/api/` gets the Django rules and a FastAPI part next to it keeps the layer rules (sdds/residual-fixes).
+- `verify_tdd`: a file native to one verifier that matches `tdd.code` is handed to the other-language verifier
+  when both are installed (`.py` to `verify_tdd.js`, JS/TS to `verify_tdd.py`), so "Python tools tested by JS
+  tests" no longer fails `verify_tdd.py` for lack of a pytest test. With one verifier nothing changes
+  (sdds/residual-fixes).
+- Website: no "100% Verified Code" claim; the file-tree hook example is the generated `.githooks/pre-commit`
+  (`audit.js --hook` / `audit.py --hook`, then external tools; `.husky/` only when Husky is active)
+  (sdds/residual-fixes).
+- `scan_secrets.py` matches the assignment rules case-insensitively, as the JS guard always did, and splits
+  lines the same way, so both report identical findings.
+- `check_custom`: Python glob translation, JS/Python glob parity and an infinite loop on empty regex matches.
+- `check_architecture`: classifies layers by path segment and checks every imported name, including relative
+  imports.
+- `check_migrations`: compares upgrade and downgrade to check that destructive upgrades are reversed.
+- `check_db_efficiency`: flags only ORM-like calls inside loops, not `dict.get` or `requests.get`.
+- `postgres_guard`: detects unsafe SQL passed to `execute()`.
+- `check_ui_reuse`: skips test files and harness-owned `tools/` sources.
+- `check_test_calendar_sync` reports drift instead of writing files from the hook (`--fix` keeps the old
+  behavior).
+- Technology guards are run by the generated hook and discovered by `audit`.
+- `update` prints success lines with a defined color.
+
+### Deprecated
+
+- The `clc-forge` and `create-clc-forge` binaries print a deprecation notice and will be removed in the next
+  major release; use `clckernel`.
+- `.clc-forge.yml` / `.clc-forge.yaml` still load with a warning; rename them to `.clckernel.yaml`.
+
+### Upgrade notes
+
+- Run `clckernel update` in each existing project to refresh guards, the hook and the managed-files registry,
+  then review any `.clckernel.yaml` that now fails to parse.
+- After pulling this repository on another machine, regenerate the local IDE mirrors (they are no longer
+  tracked) with `clckernel update`.
+
+## [1.2.19]
+
+- Previous release.
+
+[Unreleased]: https://github.com/CarlosLeonCode/clc_forge/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/CarlosLeonCode/clc_forge/compare/v1.2.19...v2.0.0
+[1.2.19]: https://github.com/CarlosLeonCode/clc_forge/releases/tag/v1.2.19

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Leon Code
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.