@ryuenn3123/agentic-senior-core 5.7.0 → 5.8.1

package/.openhands/microagents/agentic-senior-core.md

@@ -86,6 +86,13 @@ 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.
 
+## Workflow
+
+Starting a project from scratch, or adding a non-trivial feature to an
+existing codebase? Mention `/asc-new-project` or `/asc-add-feature` —
+they set up a research/plan gate before implementation. Let the user
+decide whether to invoke it. Skip this for trivial edits.
+
 ## Response Style
 
 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/.roo/rules/agentic-senior-core.md

@@ -86,6 +86,13 @@ 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.
 
+## Workflow
+
+Starting a project from scratch, or adding a non-trivial feature to an
+existing codebase? Mention `/asc-new-project` or `/asc-add-feature` —
+they set up a research/plan gate before implementation. Let the user
+decide whether to invoke it. Skip this for trivial edits.
+
 ## Response Style
 
 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/.windsurf/rules/agentic-senior-core.md

@@ -86,6 +86,13 @@ 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.
 
+## Workflow
+
+Starting a project from scratch, or adding a non-trivial feature to an
+existing codebase? Mention `/asc-new-project` or `/asc-add-feature` —
+they set up a research/plan gate before implementation. Let the user
+decide whether to invoke it. Skip this for trivial edits.
+
 ## Response Style
 
 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/.zed/rules/agentic-senior-core.md

@@ -86,6 +86,13 @@ 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.
 
+## Workflow
+
+Starting a project from scratch, or adding a non-trivial feature to an
+existing codebase? Mention `/asc-new-project` or `/asc-add-feature` —
+they set up a research/plan gate before implementation. Let the user
+decide whether to invoke it. Skip this for trivial edits.
+
 ## Response Style
 
 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

@@ -52,6 +52,13 @@ Before writing any code, stop at the first step that holds:
 
 For domain-specific rules (Testing, API Design, Database, Frontend, Infrastructure, Resilience), use `/asc-reference`.
 
+## Workflow
+
+Starting a project from scratch, or adding a non-trivial feature to an
+existing codebase? Mention `/asc-new-project` or `/asc-add-feature` —
+they set up a research/plan gate before implementation. Let the user
+decide whether to invoke it. Skip this for trivial edits.
+
 ## Response Style
 
 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.

package/CONVENTIONS.md

@@ -86,6 +86,13 @@ 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.
 
+## Workflow
+
+Starting a project from scratch, or adding a non-trivial feature to an
+existing codebase? Mention `/asc-new-project` or `/asc-add-feature` —
+they set up a research/plan gate before implementation. Let the user
+decide whether to invoke it. Skip this for trivial edits.
+
 ## Response Style
 
 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

@@ -7,6 +7,8 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 
+**Minimalism plugins cut the code. This plugin makes sure what remains is production-safe.**
+
 **Install once. Works across all projects. Supports 23+ AI coding agents.**
 
 </div>
@@ -330,7 +332,9 @@ Terminal agent plugins pick up the new version automatically on next session. Gl
 
 ## What It Does
 
-AI coding agents over-build by default. Ask for a date picker, the agent installs a library, writes a wrapper component, adds a stylesheet, and opens a timezone discussion.
+AI coding agents over-build by default. Ask for a date picker, the agent installs a library, writes a wrapper component, adds a stylesheet, and opens a timezone discussion. Worse — they silently skip input validation, concatenate SQL strings, commit secrets, and return stack traces to clients.
+
+Code reduction plugins solve the first problem. ASC solves both.
 
 This plugin loads universal engineering rules on every session. Before writing any code, the agent runs a decision ladder:
 
@@ -343,6 +347,56 @@ This plugin loads universal engineering rules on every session. Before writing a
 
 The rules also cover security, architecture, testing, error handling, API design, database safety, frontend accessibility, infrastructure, resilience, and async patterns. All universal invariants -- no project-specific configuration needed.
 
+### Before / After
+
+<details>
+<summary><b>Without ASC</b> — AI-generated endpoint (common output)</summary>
+
+```javascript
+app.post('/users', (req, res) => {
+  const { name, email, password } = req.body;
+  // No input validation
+  // SQL injection via string concatenation
+  const query = `INSERT INTO users (name, email, password)
+                 VALUES ('${name}', '${email}', '${password}')`;
+  db.run(query, (err) => {
+    if (err) {
+      // Stack trace leaked to client
+      res.status(500).json({ error: err.message, stack: err.stack });
+    } else {
+      // Password returned in response
+      res.json({ name, email, password, message: 'User created' });
+    }
+  });
+});
+```
+
+Issues: no input validation, SQL injection, plaintext password stored and returned, internal error details leaked, no auth check.
+
+</details>
+
+<details>
+<summary><b>With ASC</b> — same prompt, rules active</summary>
+
+```javascript
+app.post('/users', authenticate, async (req, res) => {
+  const { name, email, password } = req.body;
+  if (!name || !email || !password) {
+    return res.status(400).json({ error: 'Missing required fields' });
+  }
+  const hash = await bcrypt.hash(password, 12);
+  const stmt = db.prepare(
+    'INSERT INTO users (name, email, password) VALUES (?, ?, ?)'
+  );
+  stmt.run(name, email, hash);
+  res.status(201).json({ name, email });
+});
+```
+
+Validated input, parameterized query, hashed password, safe error response, auth middleware, no sensitive data in response.
+
+</details>
+
 ### Not lazy about
 
 Input validation at trust boundaries, parameterized queries, auth checks, error handling that prevents data loss, accessibility, anything explicitly requested. These are never skipped.
@@ -384,6 +438,8 @@ Available on plugin hosts (Claude Code, Codex, Gemini CLI):
 
 | Command | Purpose |
 |---------|---------|
+| `/asc-new-project` | Greenfield workflow (Define -> Spec -> Implement -> Validate) |
+| `/asc-add-feature` | Brownfield workflow (Research -> Plan -> Implement) |
 | `/asc-refactor` | Structured refactoring workflow |
 | `/asc-review` | Production-risk code review with severity-ordered findings |
 | `/asc-audit` | Security and architecture audit |
@@ -412,12 +468,9 @@ asc --help
 
 ## Works With Other Plugins
 
-ASC covers universal engineering standards (security, architecture, testing, API design, database safety). It is complementary to:
-
-- **ponytail** -- YAGNI minimalism and code reduction
-- **awesome-cursorrules** -- Framework-specific context and stack declarations
+ASC covers security, architecture, testing, API design, database safety, accessibility, infrastructure, and resilience — domains that code-reduction and minimalism plugins explicitly leave out of scope. They reduce volume; ASC enforces safety on what remains.
 
-Use them together. No conflicts.
+Use them together. No conflicts — ASC is designed to be complementary.
 
 ---
 
@@ -467,3 +520,24 @@ This removes `.agent-context/`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and other
 | Commands | 0 | Metadata only |
 
 Total always-on cost: ~1,200 tokens per session.
+
+---
+
+## Grounded In
+
+Every rule and skill workflow is derived from established engineering standards, not invented conventions.
+
+| Domain | Standards |
+|--------|-----------|
+| Security & audit | OWASP Top 10, OWASP ASVS v4, CWE classification, CVSS report structure |
+| Code review | OWASP Risk Rating Methodology, Google Engineering Practices |
+| Architecture | Clean Architecture, Hexagonal Architecture |
+| Workflows | RPI & QRSPI (Dex Horthy/HumanLayer), SDD (GitHub Spec Kit) |
+| Refactoring | Fowler's Refactoring, Rule of Three, YAGNI (XP/Kent Beck) |
+| Database | Fowler's Money Pattern, UTC timestamp convention, migration versioning |
+| Accessibility | WCAG 2.2 AA |
+| Resilience | Nygard's Release It!, AWS Well-Architected Reliability Pillar |
+| Technical debt | Cunningham's debt metaphor (1992) |
+| Instruction design | Low instruction density for higher LLM compliance — supported by IFScale (arXiv:2507.11538) and RECAST (arXiv:2505.19030) |
+
+The decision ladder (check before building) and debt ledger format are ASC-specific implementations grounded in these principles.

package/commands/asc-add-feature.md

@@ -0,0 +1 @@
+Run the brownfield feature workflow from skills/asc-add-feature/SKILL.md. Follow the Research -> Plan -> Implement phases with explicit human gates to prevent context rot.

package/commands/asc-add-feature.toml

@@ -0,0 +1,6 @@
+name = "asc-add-feature"
+description = "Structured brownfield workflow. Research -> Plan -> Implement with human gates."
+
+[[instructions]]
+type = "context"
+content = "Run the brownfield feature workflow from skills/asc-add-feature/SKILL.md. Stop and wait for user approval at the end of each phase (Research, Plan) before proceeding. Update the gate state as instructed."

package/commands/asc-help.md

@@ -1,6 +1,8 @@
 Show available Agentic Senior Core commands and skills.
 
 Available commands:
+- /asc-new-project -- Greenfield workflow (Define -> Spec -> Implement -> Validate)
+- /asc-add-feature -- Brownfield workflow (Research -> Plan -> Implement)
 - /asc-refactor -- Structured refactoring workflow
 - /asc-review -- Production-risk code review
 - /asc-audit -- Security and architecture audit

package/commands/asc-help.toml

@@ -1,2 +1,12 @@
 description = "Show available Agentic Senior Core commands"
-prompt = "Show the Agentic Senior Core command reference: /asc-refactor (structured refactoring workflow), /asc-review (production-risk code review with severity-ordered findings), /asc-audit (security and architecture audit), /asc-help (this help). ASC loads universal engineering rules covering code quality, architecture, security, error handling, testing, API design, database, frontend, infrastructure, resilience, and async patterns."
+prompt = '''
+Show available Agentic Senior Core commands and skills.
+
+Available commands:
+- /asc-new-project -- Greenfield workflow (Define -> Spec -> Implement -> Validate)
+- /asc-add-feature -- Brownfield workflow (Research -> Plan -> Implement)
+- /asc-refactor -- Structured refactoring workflow
+- /asc-review -- Production-risk code review
+- /asc-audit -- Security and architecture audit
+- /asc-help -- This help. ASC loads universal engineering rules covering code quality, architecture, security, error handling, testing, API design, database, frontend, infrastructure, resilience, and async patterns.
+'''

package/commands/asc-new-project.md

@@ -0,0 +1 @@
+Run the greenfield project workflow from skills/asc-new-project/SKILL.md. Follow the Define -> Spec -> Implement -> Validate phases with explicit human gates before building.

package/commands/asc-new-project.toml

@@ -0,0 +1,6 @@
+name = "asc-new-project"
+description = "Structured greenfield workflow. Define -> Spec -> Implement -> Validate with human gates."
+
+[[instructions]]
+type = "context"
+content = "Run the greenfield project workflow from skills/asc-new-project/SKILL.md. Stop and wait for user approval at the end of each phase (Define, Spec) before proceeding. Update the gate state as instructed."

package/gemini-extension.json

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

package/hooks/path-util.cjs

@@ -0,0 +1,23 @@
+const crypto = require('crypto');
+const path = require('path');
+const os = require('os');
+
+/**
+ * Computes a stable path for the workflow gate file based on the project path.
+ * Normalizes the path (resolves absolute, lowercase, forward slashes, no trailing slash)
+ * to ensure identical hashes regardless of OS path separator or drive letter casing.
+ * Note: .toLowerCase() deliberately treats Linux/Mac paths case-insensitively, 
+ * accepting the negligible risk of collisions for the benefit of Windows stability.
+ * 
+ * @param {string} projectPath - The root path of the project.
+ * @returns {string} Absolute path to the global workflow gate JSON file.
+ */
+function getWorkflowGatePath(projectPath) {
+  const normalizedPath = path.resolve(projectPath).replace(/\\/g, '/').toLowerCase().replace(/\/$/, '');
+  const projectHash = crypto.createHash('sha256').update(normalizedPath).digest('hex').substring(0, 16);
+  return path.join(os.homedir(), '.config', 'agentic-senior-core', 'gates', `${projectHash}.json`);
+}
+
+module.exports = {
+  getWorkflowGatePath
+};

package/hooks/post-edit-enforce.js

@@ -3,6 +3,7 @@
 // Fires after Edit/Write. Checks for ladder violations and injects a nudge.
 // Supports Claude Code, Codex CLI, and GitHub Copilot CLI.
 
+const fs = require('fs');
 const path = require('path');
 
 const STDLIB_DUPLICATES = new Set([
@@ -50,6 +51,10 @@ process.stdin.on('end', function () {
       }
     }
 
+    if (ext !== 'md') {
+      checkWorkflowGate(toolName, filePath, ext, findings);
+    }
+
     if (findings.length === 0) return;
 
     const nudge = '[ASC enforcement] ' + findings.join(' ') + ' Review the decision ladder before continuing.';
@@ -115,6 +120,35 @@ function checkNewFileSize(toolInput, filePath, findings) {
   }
 }
 
+function checkWorkflowGate(toolName, filePath, ext, findings) {
+  try {
+    var pathUtil = require('./path-util.cjs');
+    var gatePath = pathUtil.getWorkflowGatePath(process.cwd());
+    if (!fs.existsSync(gatePath)) return;
+    
+    var gateStr = fs.readFileSync(gatePath, 'utf8');
+    var gate = JSON.parse(gateStr);
+    
+    if (gate.updatedAt) {
+      var ageHours = (Date.now() - new Date(gate.updatedAt).getTime()) / (1000 * 60 * 60);
+      if (ageHours > 4) {
+        fs.unlinkSync(gatePath);
+        findings.push('Cleared stale workflow gate (' + gate.workflow + ').');
+        return;
+      }
+    }
+    
+    if (gate.phase === 'research' || gate.phase === 'plan') {
+      findings.push(
+        'Workflow gate bypass: ' + gate.workflow + ' is in ' + gate.phase + ' phase but source code was edited. '
+        + 'Stop and wait for phase approval. If you must proceed, log this bypass to the debt ledger.'
+      );
+    }
+  } catch (_) {
+    // Silent fail
+  }
+}
+
 function emit(nudge) {
   try {
     var isCopilot = Boolean(process.env.COPILOT_PLUGIN_DATA);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "5.7.0",
+  "version": "5.8.1",
   "type": "module",
   "description": "Universal AI coding rules. Write code like a staff engineer, not a junior.",
   "bin": {
@@ -88,6 +88,6 @@
     "agentic"
   ],
   "scripts": {
-    "test": "node --test ./tests/adapter.test.mjs"
+    "test": "node --test ./tests/adapter.test.mjs ./tests/path-hash.test.mjs"
   }
 }

package/plugin.yaml

@@ -1,5 +1,5 @@
 name: agentic-senior-core
-version: 5.7.0
+version: 5.8.1
 description: Universal AI coding rules. Write code like a staff engineer.
 author: fatidaprilian
 provides_hooks:

package/scripts/mcp-server/tools.mjs

@@ -5,6 +5,9 @@ import { existsSync } from 'node:fs';
 import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import { dirname, resolve, sep } from 'node:path';
+import { createRequire } from 'node:module';
+const requireCJS = createRequire(import.meta.url);
+const pathUtil = requireCJS('../../hooks/path-util.cjs');
 import {
   AVAILABLE_TEST_SUITES,
   DEFAULT_FETCH_MAX_CHARS,
@@ -377,6 +380,13 @@ function resolveStatePath(relativeStatePath) {
     throw new Error('path is required and must be relative to .agent-context/state');
   }
 
+  if (normalizedRelativePath === 'workflow-gate.json') {
+    return {
+      normalizedRelativePath,
+      resolvedStatePath: pathUtil.getWorkflowGatePath(REPOSITORY_ROOT),
+    };
+  }
+
   const resolvedStatePath = resolve(STATE_DIRECTORY, normalizedRelativePath);
   const stateRootPrefix = `${STATE_DIRECTORY}${sep}`;
   if (resolvedStatePath !== STATE_DIRECTORY && !resolvedStatePath.startsWith(stateRootPrefix)) {

package/skills/asc/SKILL.md

@@ -4,6 +4,8 @@ Universal AI coding rules. Write code like a staff engineer.
 
 ## Available Commands
 
+- `/asc-new-project` -- Greenfield workflow (Define -> Spec -> Implement -> Validate)
+- `/asc-add-feature` -- Brownfield workflow (Research -> Plan -> Implement)
 - `/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
@@ -17,8 +19,9 @@ On plugin-tier hosts (Claude Code, Codex CLI, Copilot CLI), a PostToolUse hook f
 - New dependencies against stdlib duplicates (decision ladder step 3)
 - LOC delta > 30 lines on edits (step 5)
 - New files > 50 lines (steps 1–2)
+- Workflow gate violations: source/config edits during research or plan phases
 
-Violations inject a nudge referencing the specific ladder step. The hook is silent when no issues are found.
+Violations inject a nudge referencing the specific ladder step or workflow phase. The hook is silent when no issues are found. All enforcement is advisory — nudges, not hard blocks.
 
 ## What It Does
 

package/skills/asc-add-feature/SKILL.md

@@ -0,0 +1,46 @@
+# Add Feature Workflow
+
+Structured brownfield workflow. Adapted from QRSPI to prevent context rot and ensure alignment before building.
+
+Grounded in: RPI (Dex Horthy, HumanLayer 2025) with corrections from QRSPI 8-stage evolution (Coding Agents Conference, March 2026). Plan-reading illusion fix and instruction budget constraint applied. Stages 2/5/7 adapted; stages 1/3/4/6/8 skipped as too heavyweight for individual-developer workflow.
+
+## Gate Mechanism
+
+This workflow nudges the agent to stop at each phase boundary, same enforcement tier as the existing decision ladder — not a hard block. Bypasses are logged to the debt ledger.
+
+**Known limitation:** Bypass-to-debt-ledger logging is self-reported by the agent, not enforced by the hook. The PostToolUse hook has no MCP access — it nudges the agent to log, but cannot write the debt entry itself.
+
+To track phase, write to `workflow-gate.json` via the `state_write` MCP tool.
+Format:
+```json
+{
+  "workflow": "asc-add-feature",
+  "phase": "<current_phase>",
+  "updatedAt": "<ISO-timestamp>"
+}
+```
+
+## Phase 1: Research (No Code Changes)
+
+1. Write `workflow-gate.json` with phase `research`.
+2. Map existing code: patterns, utilities, dependencies already in use.
+3. Identify what must NOT be rebuilt (e.g., existing validation helpers).
+4. Output a factual research summary.
+5. **STOP and wait for user approval.** Do not plan or implement.
+
+## Phase 2: Plan
+
+1. On approval of Phase 1, update `workflow-gate.json` phase to `plan`.
+2. Create a numbered, step-by-step implementation plan with specific files, functions, and line references.
+3. Include a "Don't Build" list from the research phase.
+4. **Callout: Plan-Reading Illusion.** Ask the user to explicitly verify the plan against the codebase, not just skim it.
+5. Output the plan.
+6. **STOP and wait for user approval.** Do not implement.
+
+## Phase 3: Implement
+
+1. On approval of Phase 2, update `workflow-gate.json` phase to `implement`.
+2. Recommend a fresh context (intentional compaction) if the context window is getting full.
+3. Execute the approved plan.
+4. Validate: tests pass, no duplicate code introduced, plan items checked off.
+5. On completion, clear the state in `workflow-gate.json` by overwriting it with `{}`.

package/skills/asc-audit/SKILL.md

@@ -2,6 +2,8 @@
 
 Security and architecture audit. Deeper than review, focused on finding vulnerabilities and structural anti-patterns.
 
+Grounded in: OWASP Top 10 (2021), OWASP ASVS v4, CVSS vulnerability report structure, CWE classification.
+
 ## Audit Scope
 
 1. **Trust boundaries**: Every point where external input enters the system. Validate that inputs are sanitized, normalized, and rejected when invalid.

package/skills/asc-debt/SKILL.md

@@ -2,6 +2,8 @@
 
 Track deferred enforcement violations. When an ASC ladder nudge fires and the shortcut is accepted rather than fixed, log it here for later resolution.
 
+Grounded in: Cunningham's technical debt metaphor (1992). Entry format (ladder step + violation + status lifecycle) is an ASC-specific implementation.
+
 ## 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.

package/skills/asc-new-project/SKILL.md

@@ -0,0 +1,49 @@
+# New Project Workflow
+
+Structured greenfield workflow. Prevents building before alignment on what to build.
+
+Grounded in: Spec-Driven Development (SDD) with scaffolding-spec approach. Specs guide implementation, then the code becomes the source of truth — specs are not maintained as living documents unless the team explicitly opts in.
+
+## Gate Mechanism
+
+This workflow nudges the agent to stop at each phase boundary, same enforcement tier as the existing decision ladder — not a hard block. Bypasses are logged to the debt ledger.
+
+**Known limitation:** Bypass-to-debt-ledger logging is self-reported by the agent, not enforced by the hook. The PostToolUse hook has no MCP access — it nudges the agent to log, but cannot write the debt entry itself.
+
+To track phase, write to `workflow-gate.json` via the `state_write` MCP tool.
+Format:
+```json
+{
+  "workflow": "asc-new-project",
+  "phase": "<current_phase>",
+  "updatedAt": "<ISO-timestamp>"
+}
+```
+
+## Phase 1: Define (No Code)
+
+1. Write `workflow-gate.json` with phase `research`.
+2. Clarify with the user: tech stack, target platform, constraints, non-goals.
+3. Propose a directory structure and module boundaries.
+4. Output a project brief summarizing decisions.
+5. **STOP and wait for user approval.** Do not write specs or code.
+
+## Phase 2: Spec (No Implementation Code)
+
+1. On approval of Phase 1, update `workflow-gate.json` phase to `plan`.
+2. Write per-feature specs with acceptance criteria and edge cases.
+3. Specs are scaffolding — they guide the build, then the code is the source of truth.
+4. Output specs for review.
+5. **STOP and wait for user approval.** Do not implement.
+
+## Phase 3: Implement
+
+1. On approval of Phase 2, update `workflow-gate.json` phase to `implement`.
+2. Build against the approved specs. Apply the ASC decision ladder on every file.
+3. Run the decision ladder: does this need to exist? Does stdlib cover it? One function or full module?
+
+## Phase 4: Validate
+
+1. Run tests. Check each spec's acceptance criteria.
+2. Confirm nothing was over-built beyond what the specs required.
+3. On completion, clear the state in `workflow-gate.json` by overwriting it with `{}`.

package/skills/asc-refactor/SKILL.md

@@ -2,12 +2,33 @@
 
 Structured refactoring workflow. Preserves existing behavior while improving structure.
 
+Grounded in: Fowler's Refactoring (read-understand-smallest scope-preserve behavior), Rule of Three (abstraction threshold), YAGNI principle (XP/Kent Beck). Empirical evidence: agents dominate low-level refactors (rename, extract, type changes) but struggle with multi-file architectural changes (arXiv, 15k+ instance study).
+
+## YAGNI Scan (Before Any Restructuring)
+
+Before changing structure, scan for speculative code to remove:
+- "Just in case" logic, unused feature flags, dead branches behind config toggles.
+- Abstractions wrapping a single implementation with no second consumer.
+- Premature extension points (plugin hooks, strategy patterns) with one concrete path.
+
+Removing speculative code is the highest-value, lowest-risk refactor type.
+
+## Classify Before Proceeding
+
+After reading the target code, classify the refactor:
+
+- **Low-level** (rename, extract method, type safety, dead code removal): proceed after explaining the change. No approval gate needed.
+- **High-level** (move module, change architecture, redesign abstractions, multi-file structural changes): output a plan with specific files and rationale, then **stop and wait for user approval** before implementing.
+
+**Known limitation:** The high-level refactor gate is a skill-text instruction — the agent self-classifies and self-stops. Unlike `/asc-add-feature` and `/asc-new-project`, this gate is not backed by the PostToolUse hook or workflow-gate.json. If the agent bypasses the gate, there is no automated nudge.
+
 ## Before Editing
 
 1. Read the target code and understand existing patterns.
 2. Identify the smallest relevant scope for the refactor.
-3. If the change touches UI, check accessibility and responsive behavior.
-4. If the change touches dependencies, verify current official docs.
+3. Classify the refactor (see above). If high-level, stop and present a plan.
+4. If the change touches UI, check accessibility and responsive behavior.
+5. If the change touches dependencies, verify current official docs.
 
 ## Refactor Rules
 

package/skills/asc-reference/SKILL.md

@@ -2,6 +2,8 @@
 
 Domain-specific coding rules for testing, API design, database queries, frontend components, infrastructure configs, and service resilience. Load this skill when working on any of these domains.
 
+Grounded in: WCAG 2.2 AA (accessibility), Fowler's Money Pattern (monetary types), Nygard's Release It! (resilience patterns), AWS Well-Architected Reliability Pillar (backoff/circuit breakers), OWASP Secure Coding Practices (input validation, logging).
+
 ## Testing
 
 - Write tests for business logic and boundary failures, not implementation details.

package/skills/asc-review/SKILL.md

@@ -2,6 +2,8 @@
 
 Production-risk code review. Prioritize findings by severity.
 
+Grounded in: OWASP Risk Rating Methodology, Google Engineering Practices (code review guide), Clean Architecture (transport vs business layer separation).
+
 ## Before Reviewing
 
 1. Read the changed files and understand the scope.