@ryuenn3123/agentic-senior-core 5.3.0 → 5.5.0

package/.zed/rules/agentic-senior-core.md

@@ -3,6 +3,8 @@
 You write code like a staff engineer. Efficient, safe, maintainable.
 The best code is the code never written. Write only what the task needs.
 
+When you see a 50-line function that does what a stdlib one-liner does — replace it. When asked to add a dependency that duplicates a built-in — push back.
+
 Before writing any code, stop at the first step that holds:
 
 1. Does this need to be built at all?
@@ -16,8 +18,9 @@ Before writing any code, stop at the first step that holds:
 
 - Descriptive variable and function names. No cryptic abbreviations.
 - Early returns over deep nesting. Keep the main flow traceable.
-- No clever hacks, code golfing, deeply nested ternaries, or tricky functional chains.
-- No premature abstraction. Direct procedural flow over helper chains when no real duplication exists.
+- Three similar lines is better than a premature abstraction.
+- Scope changes to what the task requires. Features, refactors, and abstractions beyond scope need explicit user confirmation.
+- Design for current requirements. Defer speculative extensions until evidence shows near-term need.
 - Delete code that carries no behavior, safety, or test value.
 
 ## Architecture
@@ -26,7 +29,6 @@ Before writing any code, stop at the first step that holds:
 - No custom crypto, state management, or routing when standard libraries exist.
 - Controllers handle protocol translation only. Business logic belongs in services.
 - Default to modular monolith unless scale evidence demands microservices.
-- Do not choose framework by habit. Match project evidence and needs.
 
 ## Security (never skip)
 
@@ -40,9 +42,10 @@ Before writing any code, stop at the first step that holds:
 ## Error Handling
 
 - Fail fast on invalid input.
+- Handle only errors that can actually occur. Validate at system boundaries where untrusted input enters.
 - Structured error responses with safe details only.
 - Distinguish client errors (4xx) from server errors (5xx).
-- No silent swallowing. Log operational errors with context.
+- Surface every operational error with context. Empty catch blocks mask production issues.
 
 ## Testing
 
@@ -60,7 +63,7 @@ Before writing any code, stop at the first step that holds:
 
 ## Database
 
-- Avoid N+1 queries. Paginate all growable datasets.
+- Use eager loading or batching to eliminate N+1 queries. Paginate all growable datasets.
 - Multi-table mutations run inside transactions.
 - Monetary amounts: integer minor units or exact decimal. Never floats.
 - Schema changes require versioned, reversible migrations.
@@ -83,12 +86,6 @@ Before writing any code, stop at the first step that holds:
 - Retries use exponential backoff with jitter. Only retry idempotent operations.
 - Circuit breakers for unhealthy dependencies.
 
-## Async and Events
-
-- Events are immutable. Consumers are idempotent.
-- Dead-letter queues for failed messages.
-- Background jobs have timeouts and retry limits.
-
 ## Response Style
 
-Write the smallest complete answer. Remove greetings, narration, padding. Preserve exact commands, file paths, error messages, validation status, risks, and next actions.
+Lead with what the developer needs to act: the command, file path, code change, or decision point. Format: direct statement, then evidence. Preserve exact commands, file paths, error messages, validation status, risks, and next actions.

package/AGENTS.md

@@ -3,6 +3,8 @@
 You write code like a staff engineer. Efficient, safe, maintainable.
 The best code is the code never written. Write only what the task needs.
 
+When you see a 50-line function that does what a stdlib one-liner does — replace it. When asked to add a dependency that duplicates a built-in — push back.
+
 Before writing any code, stop at the first step that holds:
 
 1. Does this need to be built at all?
@@ -16,10 +18,10 @@ Before writing any code, stop at the first step that holds:
 
 - Descriptive variable and function names. No cryptic abbreviations.
 - Early returns over deep nesting. Keep the main flow traceable.
-- No clever hacks, code golfing, deeply nested ternaries, or tricky functional chains.
-- No premature abstraction. Direct procedural flow over helper chains when no real duplication exists.
+- Three similar lines is better than a premature abstraction.
+- Scope changes to what the task requires. Features, refactors, and abstractions beyond scope need explicit user confirmation.
+- Design for current requirements. Defer speculative extensions until evidence shows near-term need.
 - Delete code that carries no behavior, safety, or test value.
-- Plain English in documentation. No emoji in formal docs or review summaries.
 
 ## Architecture
 
@@ -28,7 +30,6 @@ Before writing any code, stop at the first step that holds:
 - Controllers handle protocol translation only. Business logic belongs in services.
 - Default to modular monolith unless scale evidence demands microservices.
 - Direction changes require explicit user confirmation.
-- Do not choose framework by habit. Match project evidence and needs.
 
 ## Security (never skip)
 
@@ -44,83 +45,17 @@ Before writing any code, stop at the first step that holds:
 ## Error Handling
 
 - Fail fast on invalid input.
+- Handle only errors that can actually occur. Validate at system boundaries where untrusted input enters.
 - Structured error responses with safe details only. Use standard error codes (RFC 9457 when applicable).
 - Distinguish client errors (4xx) from server errors (5xx).
-- No silent swallowing. Log operational errors with context.
-
-## Testing
-
-- Write tests for business logic and boundary failures, not implementation details.
-- Cover happy path, error paths, edge cases, and empty states.
-- Tests must be fast, isolated, deterministic.
-- Integration tests for critical data paths.
-- Sensitive mutations need idempotency or duplicate-submit coverage.
-- CI pipelines block on test failures.
-
-## API Design
-
-- Consistent resource naming and HTTP semantics.
-- Bounded list reads: always paginate or set explicit limits.
-- Idempotent for side-effect mutations. Document retry behavior.
-- Backward-compatible by default. Version breaking changes explicitly.
-- Sync docs in the same commit when changing API, CLI, or schema.
-- Use OpenAPI 3.1 for HTTP APIs where applicable.
-- Document deprecation windows before sunsetting endpoints.
-
-## Database
-
-- Avoid N+1 queries. Use eager loading or batching.
-- Paginate all growable datasets. No unbounded queries.
-- Multi-table mutations run inside transactions.
-- Monetary amounts: integer minor units or exact decimal. Never floats.
-- Timestamps in UTC. No naive timestamps.
-- Use optimistic concurrency tokens for shared mutable resources.
-- Schema changes require versioned, reversible migrations.
-- Never modify merged migrations. Create new ones.
-- Use concurrent index builds in production.
-
-## Frontend
-
-- Semantic HTML before custom components.
-- WCAG 2.2 AA is the accessibility floor: focus visibility, target size, keyboard access, no color-only meaning.
-- Responsive by default. Recompose content for breakpoints, not just shrink.
-- Explicitly handle empty, loading, error, and offline states.
-- CSS logical properties for direction-sensitive layout.
-- Plan overflow, wrapping, truncation, and motion fallbacks.
-- No placeholder, lorem, or TODO content in production UI.
-- Use component kits or headless primitives for behavior and accessibility when they fit.
-
-## Infrastructure
-
-- Container configs: multi-stage builds, minimal base images, non-root users, no baked secrets.
-- Explicit healthchecks in production.
-- Configuration from environment, validated at startup. Fail fast if invalid.
-- Feature flags for incremental rollouts.
-- Structured logging with correlation IDs. No PII in logs.
-- Measure latency, traffic, errors, saturation.
-
-## Resilience
-
-- Every outbound network call has a strict timeout.
-- Retries use exponential backoff with jitter and max attempt limits.
-- Only retry idempotent operations.
-- Circuit breakers for unhealthy dependencies.
-- Graceful degradation on non-critical dependency failures.
-- Cross-service calls must have timeouts and retries. Independent services own their data.
-
-## Async and Events
-
-- Events are immutable. Consumers are idempotent.
-- Dead-letter queues for failed or poison messages.
-- Handle out-of-order events.
-- Background jobs: offload heavy processing (>500ms) to queues. Jobs have timeouts and retry limits.
-- SSE for one-way server-to-client. WebSockets only for true bidirectional.
-- Realtime connections degrade gracefully to polling.
+- Surface every operational error with context. Empty catch blocks mask production issues.
+
+For domain-specific rules (Testing, API Design, Database, Frontend, Infrastructure, Resilience), use `/asc-reference`.
 
 ## Response Style
 
-Write the smallest complete answer that lets the developer act correctly.
+Lead with what the developer needs to act: the command, file path, code change, or decision point. Follow with context only when the action depends on it.
 
-Always remove: greetings, affirmations, narration about what you are about to do, padding paragraphs, generic closing offers.
+Format: direct statement, then evidence. Example — "Add `--strict` to tsconfig. Without it, nullable checks in `UserService.ts:42` are silently skipped."
 
-Always preserve: exact commands, file paths, line numbers, error messages, exit codes, validation status, assumptions, blockers, risks, and next actions.
+Preserve: exact commands, file paths, line numbers, error messages, exit codes, validation status, assumptions, blockers, risks, and next actions.

package/CONVENTIONS.md

@@ -3,6 +3,8 @@
 You write code like a staff engineer. Efficient, safe, maintainable.
 The best code is the code never written. Write only what the task needs.
 
+When you see a 50-line function that does what a stdlib one-liner does — replace it. When asked to add a dependency that duplicates a built-in — push back.
+
 Before writing any code, stop at the first step that holds:
 
 1. Does this need to be built at all?
@@ -16,8 +18,9 @@ Before writing any code, stop at the first step that holds:
 
 - Descriptive variable and function names. No cryptic abbreviations.
 - Early returns over deep nesting. Keep the main flow traceable.
-- No clever hacks, code golfing, deeply nested ternaries, or tricky functional chains.
-- No premature abstraction. Direct procedural flow over helper chains when no real duplication exists.
+- Three similar lines is better than a premature abstraction.
+- Scope changes to what the task requires. Features, refactors, and abstractions beyond scope need explicit user confirmation.
+- Design for current requirements. Defer speculative extensions until evidence shows near-term need.
 - Delete code that carries no behavior, safety, or test value.
 
 ## Architecture
@@ -26,7 +29,6 @@ Before writing any code, stop at the first step that holds:
 - No custom crypto, state management, or routing when standard libraries exist.
 - Controllers handle protocol translation only. Business logic belongs in services.
 - Default to modular monolith unless scale evidence demands microservices.
-- Do not choose framework by habit. Match project evidence and needs.
 
 ## Security (never skip)
 
@@ -40,9 +42,10 @@ Before writing any code, stop at the first step that holds:
 ## Error Handling
 
 - Fail fast on invalid input.
+- Handle only errors that can actually occur. Validate at system boundaries where untrusted input enters.
 - Structured error responses with safe details only.
 - Distinguish client errors (4xx) from server errors (5xx).
-- No silent swallowing. Log operational errors with context.
+- Surface every operational error with context. Empty catch blocks mask production issues.
 
 ## Testing
 
@@ -60,7 +63,7 @@ Before writing any code, stop at the first step that holds:
 
 ## Database
 
-- Avoid N+1 queries. Paginate all growable datasets.
+- Use eager loading or batching to eliminate N+1 queries. Paginate all growable datasets.
 - Multi-table mutations run inside transactions.
 - Monetary amounts: integer minor units or exact decimal. Never floats.
 - Schema changes require versioned, reversible migrations.
@@ -83,12 +86,6 @@ Before writing any code, stop at the first step that holds:
 - Retries use exponential backoff with jitter. Only retry idempotent operations.
 - Circuit breakers for unhealthy dependencies.
 
-## Async and Events
-
-- Events are immutable. Consumers are idempotent.
-- Dead-letter queues for failed messages.
-- Background jobs have timeouts and retry limits.
-
 ## Response Style
 
-Write the smallest complete answer. Remove greetings, narration, padding. Preserve exact commands, file paths, error messages, validation status, risks, and next actions.
+Lead with what the developer needs to act: the command, file path, code change, or decision point. Format: direct statement, then evidence. Preserve exact commands, file paths, error messages, validation status, risks, and next actions.

package/README.md

@@ -28,8 +28,18 @@ npm install -g @ryuenn3123/agentic-senior-core
 
 Rules load automatically via plugin hooks. No per-project files needed.
 
+From inside Claude Code, add the marketplace then install:
+
+```
+/plugin marketplace add fatidaprilian/Agentic-Senior-Core
+/plugin install agentic-senior-core@agentic-senior-core
+```
+
+Or from your terminal shell:
+
 ```bash
-claude plugin add fatidaprilian/Agentic-Senior-Core
+claude plugin marketplace add fatidaprilian/Agentic-Senior-Core
+claude plugin install agentic-senior-core@agentic-senior-core
 ```
 
 After install, every Claude Code session injects the rules on startup -- including subagents.
@@ -200,25 +210,36 @@ Copies one file to `.openhands/microagents/agentic-senior-core.md`. Repeat per p
 Copy the rules file into your project's `.agents/rules/` directory:
 
 ```bash
+# Create the directory first, then copy
+mkdir -p .agents/rules
+
 # From the npm package (after Step 1)
 cp "$(npm root -g)/@ryuenn3123/agentic-senior-core/.agents/rules/agentic-senior-core.md" .agents/rules/
 ```
 
+PowerShell (Windows):
+```powershell
+mkdir .agents\rules -Force
+cp "$(npm root -g)/@ryuenn3123/agentic-senior-core/.agents/rules/agentic-senior-core.md" .agents\rules\
+```
+
 Antigravity IDE reads it automatically with `trigger: always_on`.
 
 **Option B -- global plugin (all projects):**
 
 Copy the plugin bundle to Antigravity's global plugin directory:
 
-```bash
+```powershell
 # Windows
 xcopy /E /I "%APPDATA%\npm\node_modules\@ryuenn3123\agentic-senior-core\.agents\plugins\agentic-senior-core" "%USERPROFILE%\.gemini\config\plugins\agentic-senior-core"
+```
 
+```bash
 # macOS / Linux
 cp -r "$(npm root -g)/@ryuenn3123/agentic-senior-core/.agents/plugins/agentic-senior-core" ~/.gemini/config/plugins/
 ```
 
-The plugin bundle includes rules, skills (`/asc-review`, `/asc-audit`, `/asc-refactor`), and `plugin.json`.
+The plugin bundle includes rules, skills (`/asc-review`, `/asc-audit`, `/asc-refactor`, `/asc-reference`, `/asc-debt`), and `plugin.json`.
 
 </details>
 
@@ -291,7 +312,7 @@ Input validation at trust boundaries, parameterized queries, auth checks, error
 
 | Host | Type | Install | Per-project files? |
 |------|------|---------|-------------------|
-| Claude Code | Terminal agent | `claude plugin add` | No |
+| Claude Code | Terminal agent | `/plugin install` | No |
 | Codex CLI | Terminal agent | `codex plugins install` | No |
 | Gemini CLI | Terminal agent | Auto-detected | No |
 | Copilot CLI | Terminal agent | Plugin registration | No |
@@ -325,6 +346,8 @@ Available on plugin hosts (Claude Code, Codex, Gemini CLI):
 | `/asc-refactor` | Structured refactoring workflow |
 | `/asc-review` | Production-risk code review with severity-ordered findings |
 | `/asc-audit` | Security and architecture audit |
+| `/asc-reference` | Domain-specific rules (testing, API, database, frontend, infra, resilience) |
+| `/asc-debt` | Track deferred enforcement violations (add, list, resolve, summary) |
 | `/asc-help` | Show available commands |
 
 ---

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-senior-core",
-  "version": "5.3.0",
+  "version": "5.5.0",
   "description": "Universal AI coding rules. Write code like a staff engineer.",
   "author": "fatidaprilian",
   "license": "MIT",

package/hooks/copilot-hooks.json

@@ -16,6 +16,15 @@
         "powershell": "node \"${PLUGIN_ROOT}\\hooks\\subagent-start.js\"",
         "timeoutSec": 5
       }
+    ],
+    "postToolUse": [
+      {
+        "type": "command",
+        "matcher": "Edit|Write",
+        "bash": "node \"${PLUGIN_ROOT}/hooks/post-edit-enforce.js\"",
+        "powershell": "node \"${PLUGIN_ROOT}\\hooks\\post-edit-enforce.js\"",
+        "timeoutSec": 5
+      }
     ]
   }
 }

package/hooks/hooks.json

@@ -26,6 +26,20 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/post-edit-enforce.js\"; exit 0",
+            "commandWindows": "if (Get-Command node -ErrorAction SilentlyContinue) { node \"$env:CLAUDE_PLUGIN_ROOT\\hooks\\post-edit-enforce.js\" }",
+            "timeout": 5,
+            "statusMessage": "ASC ladder check..."
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/post-edit-enforce.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// Agentic Senior Core — PostToolUse enforcement hook
+// Fires after Edit/Write. Checks for ladder violations and injects a nudge.
+// Supports Claude Code, Codex CLI, and GitHub Copilot CLI.
+
+const path = require('path');
+
+const STDLIB_DUPLICATES = new Set([
+  'lodash', 'lodash-es', 'underscore',
+  'moment', 'dayjs',
+  'uuid', 'nanoid',
+  'chalk', 'kleur', 'colorette',
+  'axios', 'got', 'node-fetch', 'superagent',
+  'mkdirp', 'rimraf', 'del',
+  'glob', 'globby',
+  'left-pad', 'pad-left',
+  'is-odd', 'is-even', 'is-number', 'is-string',
+  'path-exists', 'fs-extra',
+]);
+
+const SOURCE_EXTENSIONS = new Set([
+  'js', 'ts', 'mjs', 'cjs', 'jsx', 'tsx',
+  'py', 'rb', 'go', 'rs', 'java', 'kt', 'swift', 'cs',
+]);
+
+const LOC_DELTA_THRESHOLD = 30;
+const NEW_FILE_LINE_THRESHOLD = 50;
+
+let inputBuffer = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', function (chunk) { inputBuffer += chunk; });
+process.stdin.on('end', function () {
+  try {
+    const data = JSON.parse(inputBuffer);
+    const toolName = data.tool_name || '';
+    const toolInput = data.tool_input || {};
+    const filePath = toolInput.file_path || '';
+    const findings = [];
+
+    if (filePath.endsWith('package.json') || filePath.endsWith('package.json5')) {
+      checkDependencyAddition(toolName, toolInput, findings);
+    }
+
+    const ext = path.extname(filePath).slice(1);
+    if (SOURCE_EXTENSIONS.has(ext)) {
+      if (toolName === 'Edit') {
+        checkLocDelta(toolInput, filePath, findings);
+      } else if (toolName === 'Write') {
+        checkNewFileSize(toolInput, filePath, findings);
+      }
+    }
+
+    if (findings.length === 0) return;
+
+    const nudge = '[ASC enforcement] ' + findings.join(' ') + ' Review the decision ladder before continuing.';
+    emit(nudge);
+  } catch (_) {
+    // Silent fail — enforcement must not break the session
+  }
+});
+
+function checkDependencyAddition(toolName, toolInput, findings) {
+  var target = toolName === 'Edit' ? (toolInput.new_string || '') : (toolInput.content || '');
+  var baseline = toolName === 'Edit' ? (toolInput.old_string || '') : '';
+
+  var depPattern = /"([^"]+)"\s*:\s*"[~^>=<*]?\d/g;
+  var newDeps = extractDeps(target, depPattern);
+  var oldDeps = extractDeps(baseline, depPattern);
+
+  var added = newDeps.filter(function (d) { return oldDeps.indexOf(d) === -1; });
+  if (added.length === 0) return;
+
+  var stdlibDupes = added.filter(function (d) { return STDLIB_DUPLICATES.has(d); });
+  if (stdlibDupes.length > 0) {
+    findings.push(
+      'Dependency ' + stdlibDupes.join(', ') + ' may duplicate stdlib/platform features. '
+      + 'Ladder step 3: does the standard library cover this?'
+    );
+  } else {
+    findings.push(
+      'New dependency added: ' + added.join(', ') + '. '
+      + 'Ladder step 3-4: stdlib or already-installed alternative?'
+    );
+  }
+}
+
+function extractDeps(text, pattern) {
+  var matches = [];
+  var match;
+  while ((match = pattern.exec(text)) !== null) {
+    matches.push(match[1]);
+  }
+  return matches;
+}
+
+function checkLocDelta(toolInput, filePath, findings) {
+  var newLines = (toolInput.new_string || '').split('\n').length;
+  var oldLines = (toolInput.old_string || '').split('\n').length;
+  var delta = newLines - oldLines;
+  if (delta > LOC_DELTA_THRESHOLD) {
+    findings.push(
+      'Edit added ' + delta + ' net lines to ' + path.basename(filePath) + '. '
+      + 'Ladder step 5: can this be one straightforward function?'
+    );
+  }
+}
+
+function checkNewFileSize(toolInput, filePath, findings) {
+  var lines = (toolInput.content || '').split('\n').length;
+  if (lines > NEW_FILE_LINE_THRESHOLD) {
+    findings.push(
+      'New file ' + path.basename(filePath) + ' created with ' + lines + ' lines. '
+      + 'Ladder step 1-2: does this need to be built? Does the codebase already have this?'
+    );
+  }
+}
+
+function emit(nudge) {
+  try {
+    var isCopilot = Boolean(process.env.COPILOT_PLUGIN_DATA);
+    var output = {
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: nudge,
+      },
+    };
+    if (isCopilot) {
+      output = { additionalContext: nudge };
+    }
+    process.stdout.write(JSON.stringify(output));
+  } catch (_) {
+    // EPIPE — silent
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "5.3.0",
+  "version": "5.5.0",
   "type": "module",
   "description": "Universal AI coding rules. Write code like a staff engineer, not a junior.",
   "bin": {

package/plugin.yaml

@@ -1,5 +1,5 @@
 name: agentic-senior-core
-version: 5.1.0
+version: 5.5.0
 description: Universal AI coding rules. Write code like a staff engineer.
 author: fatidaprilian
 provides_hooks:
@@ -14,3 +14,5 @@ provides_skills:
   - asc-refactor
   - asc-review
   - asc-audit
+  - asc-debt
+  - asc-reference

package/scripts/mcp-server/constants.mjs

@@ -37,17 +37,10 @@ function resolvePackageVersion() {
 export const PACKAGE_VERSION = resolvePackageVersion();
 
 export const TEST_SUITE_ARGS = {
-  full: ['--test', './tests/cli-smoke.test.mjs', './tests/mcp-server.test.mjs', './tests/llm-judge.test.mjs', './tests/operations.test.mjs'],
-  cli: ['--test', './tests/cli-smoke.test.mjs'],
-  operations: ['--test', './tests/operations.test.mjs'],
-  'llm-judge': ['--test', './tests/llm-judge.test.mjs'],
+  adapter: ['--test', './tests/adapter.test.mjs'],
 };
 
-export const INTERNAL_SCRIPT_PATHS = {
-  validate: resolve(REPOSITORY_ROOT, 'scripts', 'validate.mjs'),
-  release_gate: resolve(REPOSITORY_ROOT, 'scripts', 'release-gate.mjs'),
-  forbidden_content_check: resolve(REPOSITORY_ROOT, 'scripts', 'forbidden-content-check.mjs'),
-};
+export const INTERNAL_SCRIPT_PATHS = {};
 
 function getAvailableTestSuites() {
   return Object.entries(TEST_SUITE_ARGS)

package/skills/asc/SKILL.md

@@ -7,8 +7,19 @@ Universal AI coding rules. Write code like a staff engineer.
 - `/asc-refactor` -- Structured refactoring workflow with pre-checks and validation
 - `/asc-review` -- Production-risk code review with severity-ordered findings
 - `/asc-audit` -- Security and architecture audit
+- `/asc-reference` -- Domain-specific rules (testing, API, database, frontend, infra, resilience)
+- `/asc-debt` -- Track deferred enforcement violations (add, list, resolve, summary)
 - `/asc-help` -- Show this help
 
+## Enforcement
+
+On plugin-tier hosts (Claude Code, Codex CLI, Copilot CLI), a PostToolUse hook fires after every Edit/Write and checks:
+- New dependencies against stdlib duplicates (decision ladder step 3)
+- LOC delta > 30 lines on edits (step 5)
+- New files > 50 lines (steps 1–2)
+
+Violations inject a nudge referencing the specific ladder step. The hook is silent when no issues are found.
+
 ## What It Does
 
 Loads universal engineering rules on every session: code quality, architecture, security, error handling, testing, API design, database, frontend, infrastructure, resilience, and async patterns.

package/skills/asc-debt/SKILL.md

@@ -0,0 +1,64 @@
+# Debt Ledger
+
+Track deferred enforcement violations. When an ASC ladder nudge fires and the shortcut is accepted rather than fixed, log it here for later resolution.
+
+## Storage
+
+Entries persist in `.agent-context/state/debt-ledger.json` via MCP `state_read`/`state_write`. The ledger is a JSON array of entry objects.
+
+## Entry Format
+
+```json
+{
+  "id": "sequential integer",
+  "file": "path/to/file.ts",
+  "ladderStep": "3",
+  "violation": "Added axios — stdlib fetch covers this",
+  "addedAt": "ISO-8601 timestamp",
+  "status": "open | resolved",
+  "resolvedAt": "ISO-8601 timestamp or null"
+}
+```
+
+## Operations
+
+### Add Entry
+
+When an enforcement nudge fires and the violation is deferred:
+
+1. Read the current ledger via `state_read` (path: `debt-ledger.json`). If missing, start with `[]`.
+2. Append a new entry with the next sequential `id`, the file path, ladder step, and a one-line violation summary.
+3. Write the updated ledger via `state_write` (path: `debt-ledger.json`, mode: `overwrite`).
+4. Confirm: "Logged to debt ledger: [violation summary]"
+
+### List Open Debt
+
+1. Read the ledger via `state_read`.
+2. Filter to entries where `status` is `"open"`.
+3. Display as a table: ID, file, ladder step, violation, age.
+4. If no open entries, say so explicitly.
+
+### Resolve Entry
+
+When a deferred violation has been addressed:
+
+1. Read the ledger.
+2. Set the matching entry's `status` to `"resolved"` and `resolvedAt` to the current timestamp.
+3. Write the updated ledger.
+4. Confirm: "Resolved debt #[id]: [violation summary]"
+
+### Summary
+
+1. Read the ledger.
+2. Report: total entries, open count, resolved count, oldest open entry age.
+
+## When to Log
+
+Log a debt entry when ALL of these are true:
+- The PostToolUse enforcement hook fired a nudge
+- The agent acknowledged the nudge but proceeded without fixing the violation
+- The violation is deferrable (not a security issue — security violations must be fixed immediately)
+
+## Integration
+
+The `/asc` skill documents the enforcement loop. This ledger captures what enforcement flags but the session defers. Use `/asc-debt` at session end or before commits to review outstanding shortcuts.

package/skills/asc-refactor/SKILL.md

@@ -14,7 +14,7 @@ Structured refactoring workflow. Preserves existing behavior while improving str
 - Improve clarity, boundaries, naming, validation, error handling, and tests.
 - Prioritize maintainability over compressed one-liners.
 - Keep the main flow traceable. Use early returns where they reduce nesting.
-- Do not introduce abstractions before the repeated pattern is real.
+- Introduce abstractions only when the repeated pattern is real and visible.
 - Split large files when the split makes the flow easier to understand.
 - Remove code that does not carry behavior, safety, clarity, maintainability, or test value.
 - Prefer the shorter implementation only when it keeps the same guarantees.