@ryuenn3123/agentic-senior-core 6.16.2 → 6.16.5

package/.agents/plugins/agentic-senior-core/skills/asc-pentest/references/pentest-task-tree.md

@@ -0,0 +1,70 @@
+# The Pentesting Task Tree (PTT) Protocol
+
+Derived from the USENIX Security architecture of **PentestGPT**. Prevents conversational context drift and maintains rigorous state tracking across multi-turn security engagements.
+
+---
+
+## 1. Task Taxonomies
+
+Every security evaluation action must map to one of six explicit task kinds:
+
+| Task Kind | Intent & Scope | Entry Criteria | Exit Criteria |
+|---|---|---|---|
+| **`DISCOVER`** | Network and surface mapping. Extract routes, ports, endpoints, and authentication schemes from source or running app. | Target URL / source repository provided. | Exhaustive inventory of accessible routes and protocols documented in session ledger. |
+| **`ENUMERATE`** | Parameter and contract analysis. Identify parameter types, required fields, and boundary expectations per route. | Route inventory established. | Input vectors mapped (query parameters, body schema, headers, cookies). |
+| **`TEST`** | Dynamic vulnerability probing. Execute targeted fuzzing, payload injection, or authorization checks. | Target parameters identified. | Target behavior analyzed; anomalies (5xx errors, reflection, unauthorized data) logged. |
+| **`EXPLOIT`** | Proof-of-exploit verification. Formulate a minimal, non-destructive reproduction proving the vulnerability is real. | Anomaly confirmed under `TEST`. | Deterministic `curl` script or test assertion proving the vulnerability exists. |
+| **`VERIFY`** | Patch verification. Re-run the reproduction script after developer code remediation. | Code patch applied. | Reproduction script fails (vulnerability successfully mitigated). |
+| **`RECOVER`** | Environment restoration. Purge canary entities, tokens, or temporary records injected during testing. | Engagement complete or failed. | Database and filesystem confirmed clean of canary records. |
+
+---
+
+## 2. Task State Transitions
+
+Tasks progress through a deterministic state machine:
+
+```
+┌─────────┐      Dependencies Met      ┌─────────┐      Execution Start      ┌──────────┐
+│ BLOCKED │ ─────────────────────────► │  READY  │ ────────────────────────► │  ACTIVE  │
+└─────────┘                            └─────────┘                           └────┬─────┘
+                                                                                  │
+                                            ┌─────────────────────────────────────┴──────────┐
+                                            ▼                                                ▼
+                                       ┌─────────┐                                      ┌──────────┐
+                                       │  DONE   │                                      │  FAILED  │
+                                       └─────────┘                                      └──────────┘
+```
+
+- **`BLOCKED`**: Prerequisites (e.g. valid auth token, route discovery) not yet satisfied.
+- **`READY`**: All `depends_on` tasks have reached `DONE`.
+- **`ACTIVE`**: Currently executing under a single task lease.
+- **`DONE`**: Target objective fulfilled; basis artifacts recorded.
+- **`FAILED`**: Execution failed or payload rejected; requires recovery or strategy adaptation.
+
+---
+
+## 3. Session Ledger Format (`scratch/pentest-session.md`)
+
+When executing an engagement spanning more than 2 steps, initialize a session ledger in the scratch directory:
+
+```markdown
+# Pentest Session Ledger: [Target Name]
+Target URL: http://localhost:8000
+Session Started: YYYY-MM-DD HH:MM:SS
+
+## Active Task Tree
+- [x] T01 [DISCOVER]: Route inventory from src/routes/ (DONE)
+- [x] T02 [ENUMERATE]: Parameter mapping on /api/v1/invoices/:id (DONE)
+- [x] T03 [TEST]: BOLA check with secondary tenant token (DONE)
+- [ ] T04 [EXPLOIT]: Minimal curl proof demonstrating horizontal data leakage (ACTIVE)
+- [ ] T05 [VERIFY]: Re-check after authorization policy middleware applied (BLOCKED on T04)
+- [ ] T06 [RECOVER]: Purge canary tenant records from test database (BLOCKED on T05)
+
+## Findings Ledger
+### F01: BOLA on GET /api/v1/invoices/:id
+- Severity: CRITICAL
+- Location: routes/invoices.js:45
+- Finding: Route queries DB by `id` directly without filtering by `tenant_id` from auth context.
+- Evidence: Peer B token successfully retrieved Invoice #1042 owned by Tenant A.
+```
+

package/.agents/plugins/agentic-senior-core/skills/asc-review/SKILL.md

@@ -32,12 +32,12 @@ Use when reviewing PRs, diffs, commits, or newly written feature code.
 ### Review Procedure
 1. **Scope Inspection**: Run `git diff --stat` (or `git status`) to inspect modified files and line deltas.
 2. **Test-Change Correlation**: For every modified application logic file, verify that a corresponding test was updated. If logic changed without tests, flag as missing test coverage.
-3. **Deterministic Verification**: Run project linter and test suite (`ascx test` / `npm test`). Confirm exit code 0 fresh.
+3. **Deterministic Verification**: Run project linter and test suite (`ascx npm test`). Confirm exit code 0 fresh.
 4. **Severity Priority Order**:
    - **Severity 1 (Critical)**: Correctness, data corruption, auth/permission bypass, security sinks, PII leakage.
    - **Severity 2 (High)**: Action feedback failures (hanging spinners, unhandled mutations, missing error boundaries), unhandled async rejections, missing remote timeouts.
    - **Severity 3 (Medium)**: Public contract drift, missing failure-path tests, architectural boundary violations.
-   - **Severity 4 (Low)**: Maintainability debt, performance micro-optimizations, code comment noise.
+   - **Severity 4 (Low)**: Maintainability debt, performance micro-optimizations, narrative code comment noise, AI prose cadence or buzzwords in user-facing copy or documentation.
 
 ---
 

package/.agents/plugins/agentic-senior-core/skills/asc-test/SKILL.md

@@ -33,6 +33,9 @@ Before writing tests, running suites, or claiming verification:
 1. **Mandatory Ingestion (BLOCKING GATE):** Call `read_file` on the tier reference matching your testing requirement BEFORE taking action:
    - Writing unit tests / TDD cycle ➔ `references/tdd-cycle.md`
    - Behavior testing, boundary isolation, mocks/fakes ➔ `references/test-design.md`
+   - Generative property invariants & fuzzing ➔ `references/property-testing.md`
+   - Mutation testing & assertion integrity ➔ `references/mutation-testing.md`
+   - Concurrency latency & performance budgets ➔ `references/performance-budgets.md`
    - Playwright browser tests, locators, page objects ➔ `references/e2e-playwright.md`
    - Acceptance criteria, UAT checklists, edge case quads ➔ `references/uat.md`
    - Bug reproduction, root-cause verification, regression proof ➔ `references/regression-proof.md`
@@ -104,6 +107,9 @@ Select the lowest testing tier that validates the requirement:
 |---|---|
 | Red-Green-Refactor mechanics & whole-suite checks | `references/tdd-cycle.md` |
 | Behavior testing, boundary isolation & mocking | `references/test-design.md` |
+| Generative property invariants & boundary fuzzing | `references/property-testing.md` |
+| Mutation integrity score (>= 80%) & mutant triage | `references/mutation-testing.md` |
+| Latency budgets (p95 <= 150ms) & concurrency benchmarking | `references/performance-budgets.md` |
 | Playwright E2E, reconnaissance & locator hierarchy | `references/e2e-playwright.md` |
 | Given/When/Then acceptance criteria & edge case quad | `references/uat.md` |
 | 3-step bugfix verification & regression proof | `references/regression-proof.md` |
@@ -118,5 +124,6 @@ Before declaring any coding or testing task complete:
 2. **Regression Proof:** For bugfixes, confirm the test failed without the fix and passes with it.
 3. **Whole-Suite Run:** Execute the full test suite (`ascx npm test` or project test runner); confirm exit code 0.
 4. **No Assertions Weakened:** Verify no existing test assertions were deleted or commented out to simulate success.
-5. **Hermetic State:** Ensure tests clean up temporary files, database records, and environment variables.
+5. **Mutation Sanity:** For critical authorization or business logic, verify tests catch condition inversion.
+6. **Hermetic State:** Ensure tests clean up temporary files, database records, and environment variables.
 

package/.agents/plugins/agentic-senior-core/skills/asc-test/references/mutation-testing.md

@@ -0,0 +1,55 @@
+# Mutation Testing & Test Suite Integrity
+
+Staff-grade guidelines for mutation testing and eradicating false-positive test suites. Grounded in the principles of **Stryker Mutator**.
+
+---
+
+## 1. The Fallacy of Code Coverage
+
+Code coverage (line, branch, or statement coverage) measures only what code was executed; it does **not** measure whether assertions were made:
+```javascript
+// A test with 100% line coverage and ZERO verification value:
+it('calculates invoice total', () => {
+  const result = calculateTotal(mockCart);
+  // No assertions! Or weak assertion: assert.ok(result);
+});
+```
+Such tests give false confidence: business logic can break completely while 100% of tests continue to pass.
+
+**Mutation testing** tests the test suite: it introduces small synthetic defects (**mutants**) into the production code. If your tests fail, the mutant is **killed** (good). If your tests pass despite the corrupted logic, the mutant **survives** (flawed test coverage).
+
+---
+
+## 2. Standard Mutant Operators
+
+| Mutant Class | Original Code | Mutated Code | Verification Test Expectation |
+|---|---|---|---|
+| **Equality Operator** | `if (user.role === 'admin')` | `if (user.role !== 'admin')` | Test asserting admin access must fail immediately. |
+| **Relational Boundary** | `if (balance >= price)` | `if (balance > price)` | Boundary test where `balance === price` must fail. |
+| **Logical Connector** | `if (hasToken && isValid)` | `if (hasToken \|\| isValid)` | Test with valid token and invalid state must fail. |
+| **Return Constant** | `return totalAmount;` | `return 0;` or `return null;` | Result consumer assertion must fail. |
+| **Statement Deletion** | `await auditLog.record(event);` | `/* deleted */` | Audit persistence assertion must fail. |
+
+---
+
+## 3. The Mutation Integrity Score
+
+$$\text{Mutation Score} = \left( \frac{\text{Killed Mutants}}{\text{Total Mutants}} \right) \times 100\%$$
+
+- **Target Threshold**: Core business logic, pricing, authorization checks, and security boundaries must achieve a Mutation Score of $\ge 80\%$.
+- **Survived Mutant Triage**:
+  - Every survived mutant indicates an untested boundary or missing assertion.
+  - Fix: Do not modify production code; write a specific failure assertion that kills the surviving mutant.
+
+---
+
+## 4. The Agentic Mutant Sanity Check
+
+When introducing or refactoring a critical function (e.g. auth check, payment math, permissions):
+1. **Identify the core decision branch** (e.g. `if (isAuthorized) return allow();`).
+2. **Inject a manual mutant**: temporarily invert the condition (`if (!isAuthorized)`).
+3. **Run the test runner**:
+   - If tests still pass $\to$ **FLAG AS CRITICAL TEST DEFECT**. Your tests are not testing the logic.
+   - Add the missing negative test case until the mutant is killed.
+4. **Revert the mutant** and confirm the full test suite turns green.
+

package/.agents/plugins/agentic-senior-core/skills/asc-test/references/performance-budgets.md

@@ -0,0 +1,67 @@
+# Performance Budgets & Concurrency Benchmarking
+
+Staff-grade guidelines for performance testing, latency budgets, and concurrency verification. Grounded in the principles of **Grafana k6**.
+
+---
+
+## 1. Latency Budgets & Percentiles
+
+Averages mask performance degradation. A service with an average response time of $50\text{ms}$ can still have $10\%$ of users waiting over $1,500\text{ms}$. Performance must be budgeted and measured using **percentiles**:
+
+| Metric | Target Standard | Operational Context |
+|---|---|---|
+| **Unit Logic Runtime** | $\le 5\text{ms}$ | Pure algorithms, mathematical transforms, string parsers. |
+| **$p_{50}$ (Median Latency)** | $\le 50\text{ms}$ | Standard read operations with warm database index. |
+| **$p_{95}$ (95th Percentile)** | $\le 150\text{ms}$ | 95 out of 100 requests must complete under this budget. |
+| **$p_{99}$ (Worst-case Tail)** | $\le 300\text{ms}$ | Tail latency under concurrency and database lock contention. |
+| **Error Rate Threshold** | Strictly $0.00\%$ | Zero 5xx errors or dropped socket connections under target load. |
+
+---
+
+## 2. Micro-Benchmark Concurrency Harness
+
+For critical endpoints, verify concurrency resilience using a native script before handoff:
+
+```javascript
+import assert from 'node:assert/strict';
+
+async function benchmarkEndpoint(url, concurrentRequests = 10, totalRequests = 50) {
+  const durations = [];
+  const runBatch = async () => {
+    const start = performance.now();
+    const res = await fetch(url);
+    const duration = performance.now() - start;
+    assert.equal(res.status, 200, `Expected 200, got ${res.status}`);
+    durations.push(duration);
+  };
+
+  // Run in chunks of `concurrentRequests`
+  for (let i = 0; i < totalRequests; i += concurrentRequests) {
+    await Promise.all(Array.from({ length: concurrentRequests }, runBatch));
+  }
+
+  durations.sort((a, b) => a - b);
+  const p50 = durations[Math.floor(durations.length * 0.50)];
+  const p95 = durations[Math.floor(durations.length * 0.95)];
+
+  console.log(`Benchmark: N=${totalRequests} | p50=${p50.toFixed(1)}ms | p95=${p95.toFixed(1)}ms`);
+  assert.ok(p95 <= 150, `p95 exceeded budget: ${p95.toFixed(1)}ms > 150ms`);
+}
+```
+
+---
+
+## 3. Memory Leak & Garbage Collection Invariants
+
+Under sustained request loops, memory footprint must reach a steady plateau rather than growing monotonically:
+
+1. **Heap Growth Check**:
+   - Record `process.memoryUsage().heapUsed` before iteration loop.
+   - Run $1,000$ iterations of the business operation.
+   - Trigger garbage collection (or sample at $N=1000$).
+   - Assert heap growth is bounded ($\le 10\%$ increase from baseline).
+2. **Common Culprits**:
+   - Global event listeners (`emitter.on()`) attached inside request handlers without removal.
+   - Unbounded in-memory caches or map accumulators without LRU eviction.
+   - Retained references inside closures of unresolved promises.
+

package/.agents/plugins/agentic-senior-core/skills/asc-test/references/property-testing.md

@@ -0,0 +1,72 @@
+# Generative Property-Based Testing & Invariant Fuzzing
+
+Staff-grade guidelines for property-based testing and generative fuzzing. Grounded in the principles of **Hypothesis** and **fast-check**.
+
+---
+
+## 1. Example-Based vs. Property-Based Testing
+
+Standard unit tests validate specific, hand-picked examples:
+```javascript
+// Example-based: tests 1 trivial scenario
+assert.equal(parsePrice("$19.99"), 1999);
+```
+Example-based tests suffer from confirmation bias: developers only test inputs they already anticipate.
+
+**Property-based testing** flips the testing paradigm: you define universal system **invariants** (truths that must hold for ALL possible inputs), and the engine executes hundreds or thousands of randomized boundary inputs to prove or disprove the property:
+```javascript
+import fc from 'fast-check';
+
+// Property-based: tests 100+ generated inputs across extreme boundaries
+fc.assert(
+  fc.property(fc.integer({ min: 0, max: 1000000 }), (cents) => {
+    const formatted = formatCurrency(cents);
+    return parseCurrency(formatted) === cents; // Invariant: round-trip fidelity
+  })
+);
+```
+
+---
+
+## 2. Core Invariant Archetypes
+
+Every complex business module should be tested against at least one of these four invariant patterns:
+
+| Invariant Pattern | Definition | Canonical Example |
+|---|---|---|
+| **Round-Trip (Serialization)** | Transforming $A \to B \to A$ preserves exact identity. | `deserialize(serialize(record)) === record`<br>`base64Decode(base64Encode(data)) === data` |
+| **Idempotence** | Applying an operation multiple times yields the same result as applying it once. | `format(format(input)) === format(input)`<br>`cleanHtml(cleanHtml(dirty)) === cleanHtml(dirty)` |
+| **Crash Invariance (No 5xx)** | No valid or invalid input shall trigger an unhandled exception or server crash. | For any generated string $s$, `parseAddress(s)` returns a parsed object OR a safe `ValidationFailure` without throwing uncaught errors. |
+| **Monotonicity & Invariance** | Mathematical or business logic ordering invariants. | Adding an item to a cart never decreases the cart subtotal (`subtotal(cart + item) >= subtotal(cart)`). |
+
+---
+
+## 3. Boundary Input Generators
+
+When testing pure functions or data transformations, generators must evaluate pathological boundary inputs:
+
+1. **Numeric Boundaries**:
+   - `0`, `-0`, `1`, `-1`
+   - `Number.MIN_SAFE_INTEGER`, `Number.MAX_SAFE_INTEGER`
+   - `Infinity`, `-Infinity`, `NaN`
+   - Floating-point precision traps (`0.1 + 0.2`)
+2. **String Boundaries**:
+   - Empty string `""`
+   - Strings with null bytes (`"canary\0danger"`)
+   - Unicode RTL override characters (`\u202E`) and emojis
+   - Extremely large strings ($10^5$ characters)
+   - Unpaired surrogate halves (`\uD800`)
+3. **Collection & Tree Boundaries**:
+   - Empty arrays `[]`, single-element `[x]`, arrays with duplicates `[x, x]`.
+   - Deeply nested objects (depth $> 30$).
+   - Objects with prototype poisoning keys (`__proto__`, `constructor`).
+
+---
+
+## 4. Failure Shrinking
+
+When a property test fails on a massive random input (e.g. an array of 500 items containing a string of 4,000 characters), the property testing runner automatically **shrinks** the failure down to the minimal counterexample that still reproduces the bug (e.g. `['\0']`).
+
+**Operational Rule**:
+When documenting a property test failure, always report the **minimal shrunk counterexample** rather than the full randomized run seed.
+

package/.agents/plugins/agentic-senior-core/skills/asc-ui/SKILL.md

@@ -30,6 +30,9 @@ Every UI edit must satisfy these 15 rules without exception:
 14. **Single-language purity:** Never mix languages on one surface; ban hybrid neologisms (`di-submit`, `meng-generate`).
 15. **Icon semantics:** Never use raw unicode or emojis as icons. Use dedicated SVG icons; mark decorative icons `aria-hidden="true"`.
 16. **Substance over restraint:** Stripping slop is only half the job. Replace removed ornaments with real substance: strong typographic scale contrast, full-field color anchors, and authentic interface fragments. Never leave an empty, sterile wireframe void.
+17. **Product over skill (No geek cosplay):** The real-world domain dictates aesthetics. Never inject terminal windows, ASCII art, or pseudo-telemetry consoles into civic, educational, or commercial products (`references/modes/genre-calibration.md`).
+18. **The Purpose-Gate:** Every component, widget, or scorecard must enable an actual user task. Never invent unearned widgets, sliders, or simulated feeds without real business data.
+19. **Anti-card-soup invariant:** Never wrap structural layout sections (header, nav, rails, tables) into floating rounded card islands. Use a Unified Spatial Canvas with hairline dividers (`divide-y`, `border-r`). Cards are strictly for discrete, interchangeable items (`references/divergence.md`).
 
 ---
 
@@ -42,13 +45,10 @@ Before declaring markup, drafting redesign plans, or inspecting user code:
    `<skill_directory>/references/<category>/<file>.md`
    Identify the path of this `SKILL.md` file (provided by host/tooling) and resolve all reference paths relative to it.
 
-2. **Step 1 — Surface Mode Ingestion (MANDATORY GATE):**
-   Classify the surface and execute `read_file` on the corresponding mode reference BEFORE inspecting files or writing code:
-   - Dashboards, settings, data tables, developer tools ➔ `references/modes/operate.md`
-   - Landing pages, pricing tiers, conversion flows ➔ `references/modes/persuade.md`
-   - Documentation, changelogs, knowledge bases ➔ `references/modes/read.md`
-   - Showcases, portfolios, interactive galleries ➔ `references/modes/experience.md`
-   *Do NOT proceed until you have read the mode reference into context.*
+2. **Step 1 — Two-Phase Enforcement Gate (MANDATORY GATE):**
+   - **Phase A (Structure & Hierarchy First):** Lock project domain genre (Civic, Enterprise, SaaS, DevTools) and read `references/modes/genre-calibration.md` + target mode reference (`references/modes/<mode>.md`). Lock the primary focal anchor and spatial posture before writing code.
+   - **Phase B (Visual System & Themes):** Read `references/craft/themes-catalog.md` and lock one of the 16 curated themes across 8 real-world domains (e.g., Sovereign Slate, Almanac Index, Editorial Ledger, Pharmacy Calm, Ink & Signal, Graphite Instrument) to prevent probabilistic palette slop.
+   *Do NOT proceed until you have read the genre, mode, and theme references into context.*
 
 3. **Step 2 — Secondary Craft Ingestion:**
    Execute `read_file` on at least one relevant craft reference for your task from Section 5 (e.g. `references/craft/typography.md`, `references/craft/color-surfaces.md`, or `references/divergence.md`).
@@ -79,7 +79,7 @@ Visual posture is governed by the surface type, not product branding. Every surf
 Never split the difference into cosmetic polish on a discarded look:
 - **Polish / Refinement:** Preserves layout structure, DOM hierarchy, and design tokens. Resolves contrast, missing state quad, microcopy, and lint issues.
 - **Restyle:** Preserves layout geometry. Replaces color tokens, typographic scales, corner radiuses, and elevation shadows.
-- **Full Redesign:** Replaces entire spatial geometry and posture. Mandatory decoupled protocol: extract data/contracts first, discard old DOM, author standalone preview (`asc preview <path>`), build fresh geometry, re-bind dynamic data.
+- **Full Redesign:** Replaces entire spatial geometry and posture. Mandatory decoupled protocol: extract data/contracts first, discard old DOM, establish clear spatial posture and theme tokens, and compile directly to production files with complete layout coherence.
 
 ---
 
@@ -90,6 +90,8 @@ Never split the difference into cosmetic polish on a discarded look:
 
 | Target Domain / Task Requirement | Mandatory Reference Path |
 |---|---|
+| Domain & genre calibration (Anti-geek cosplay) | `references/modes/genre-calibration.md` |
+| Curated material themes & locked art direction | `references/craft/themes-catalog.md` |
 | Waivable defaults & waiver syntax | `references/reflexes.md` |
 | Typography, line-height & tabular numbers | `references/craft/typography.md` |
 | Color tokens, 60-30-10 & elevation | `references/craft/color-surfaces.md` |
@@ -99,7 +101,7 @@ Never split the difference into cosmetic polish on a discarded look:
 | Responsive reflow, dvh & touch targets | `references/mobile-responsive.md` |
 | WCAG 2.2 AA contrast & keyboard operability | `references/accessibility.md` |
 | The Data State Quad & mutation feedback | `references/states-feedback.md` |
-| Anti-convergence, 3 Waves of Tells & Mirror Test | `references/divergence.md` |
+| Anti-convergence, 4 Waves of Tells & Mirror Test | `references/divergence.md` |
 | Structured UI audit matrix | `references/redesign-audit.md` |
 
 ---
@@ -107,8 +109,9 @@ Never split the difference into cosmetic polish on a discarded look:
 ## 6. Verification & Handoff Sweep
 
 Before completing any UI task, run this mechanical check:
-1. **Reference Compliance:** Confirm constraints from the loaded `references/modes/<mode>.md` and craft references were strictly applied.
-2. **State Quad:** Loading skeleton, empty state, error with retry, and populated data are all handled.
-3. **Pending Feedback:** Buttons disable and display feedback during ongoing mutations.
-4. **Contrast & Focus:** Verify keyboard tab flow and high-contrast `:focus-visible` styling.
-5. **Lint Check:** Verify changes against `hooks/lib/known-ui-slop-patterns.json`.
+1. **Reference Compliance:** Confirm constraints from `references/modes/genre-calibration.md`, `references/craft/themes-catalog.md`, and target mode were strictly applied.
+2. **Finish Gate Sweep:** Verify zero text clipping (+30% expansion buffer), zero awkward text wraps, and 4px/8px spacing grid consistency.
+3. **State Quad:** Loading skeleton, empty state, error with retry, and populated data are all handled.
+4. **Pending Feedback:** Buttons disable and display feedback during ongoing mutations.
+5. **Contrast & Focus:** Verify keyboard tab flow and high-contrast `:focus-visible` styling.
+6. **Lint Check:** Verify changes against `hooks/lib/known-ui-slop-patterns.json`.

package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/copy-i18n.md

@@ -29,11 +29,44 @@ Exception: Standard multi-step navigation controls in fixed wizards (`Back`, `Ne
 
 ---
 
-## 3. Marketing Buzzword Blacklist
+## 3. Arithmetic Copy Budgets & The Argument-First Protocol
+
+### 3.1 Arithmetic Budgets
+Constraint is arithmetic; enforce before falling in love with a sentence:
+- **Hero Headline Budget:** Must fit in **two lines or fewer** across all viewports.
+  - Mobile (390px): $\le 32$ characters ($\sim 4$–$5$ words).
+  - Desktop (1280px): $\le 42$ characters ($\sim 5$–$6$ words).
+  - Use `text-wrap: balance` and intentional `<br>` tags to avoid single-word orphans.
+- **Supporting Line Budget:** Exactly **1 sentence**, at most **22 words**.
+  - Directly states concrete function and audience.
+  - Never repeats or paraphrases headline words.
+- **First-Viewport Word Budget:** Maximum **80 words** total across the first screen.
+
+### 3.2 The Argument-First Protocol
+Before writing any HTML/JSX markup, outline the page as a sequence of claims with verifiable proofs:
+```text
+1. Claim: Three-legged oak stool, made to order.      → Proof: High-res macro photography of stool.
+2. Claim: Each seat cut from single solid board.      → Proof: 3 close-ups of continuous wood grain.
+3. Claim: Shipped in 6 weeks with tracking.           → Proof: Verifiable production stages schedule.
+4. Claim: Costs $240, delivered by the maker.         → Proof: Exact price figure + Order button.
+```
+*Rule:* Any section that lacks a factual claim or verifiable proof is filler—delete it immediately.
 
-The following words are banned in operational interfaces:
+---
+
+## 4. AI Cadences & Marketing Buzzword Blacklist
+
+### 4.1 Banned AI Cadence Formulas
+Language models fall into statistical average patterns; recognize and refuse them:
+1. **The Mad-Lib:** *"The [AI-powered/next-gen] platform for modern teams."*
+2. **The Tricolon:** *"Fast. Simple. Secure."* or *"Plan. Build. Ship."*
+3. **The Rebuttal:** *"It’s not just a tool, it’s a workflow."* / *"More than a framework."*
+4. **The Preamble Throat-Clearing:** *"In today’s fast-paced digital world..."* / *"Built for modern teams..."*
+5. **The Em-Dash Habit:** Using multiple em-dashes (`—`) in a single paragraph. Use a full stop.
 
-`seamless`, `seamlessly`, `empower`, `empowering`, `robust`, `effortless`, `effortlessly`, `cutting-edge`, `game-changing`, `elevate`, `unlock`, `dive in`, `delightful`, `next-generation`, `supercharge`, `blazing-fast`.
+### 4.2 Banned Marketing Buzzwords
+The following adjectives and verbs are banned across all surfaces:
+`seamless`, `seamlessly`, `empower`, `empowering`, `robust`, `effortless`, `effortlessly`, `cutting-edge`, `game-changing`, `elevate`, `unlock`, `unleash`, `dive in`, `delightful`, `next-generation`, `supercharge`, `blazing-fast`.
 
 When tempted to write an adjective, state the measurable property instead:
 - Instead of: *"A robust, blazing-fast pipeline."*
@@ -41,16 +74,31 @@ When tempted to write an adjective, state the measurable property instead:
 
 ---
 
-## 4. Single-Language Purity & Anti-Gado-Gado
+## 5. Actionable Error Messages & Recovery
+
+An operational error message must never produce a dead end or display raw internal stack traces. Every error must answer three questions:
+1. **What failed:** Direct statement of the blocked action.
+2. **Why:** Factual cause (if actionable and known).
+3. **How to recover:** Concrete button or path to unblock the user.
+
+| Raw / Unhelpful Error | Actionable Engineering Copy | Recovery Path |
+|---|---|---|
+| "Error 413: Payload too large." | "File exceeds the 25MB limit." | "Choose a smaller file" CTA |
+| "Failed to connect to server." | "Unable to reach database. Changes saved locally." | "Retry connection" button |
+| "Invalid credentials." | "Incorrect password for user@example.com." | "Reset password →" link |
+
+---
+
+## 6. Single-Language Purity & Anti-Gado-Gado
 
 Interfaces must maintain strict language purity. Mixing two languages within the same surface causes cognitive friction and feels unpolished.
 
-### 4.1 Strict Monolingual Surface
+### 6.1 Strict Monolingual Surface
 Choose one language for the entire surface and enforce it across headings, labels, errors, and tooltips:
 - **English UI:** All copy, actions, and timestamps in English.
 - **Indonesian UI:** All copy, actions, and timestamps in standard Indonesian (KBBI/PUEBI).
 
-### 4.2 Ban Hybrid Neologisms (Indonesian Context)
+### 6.2 Ban Hybrid Neologisms (Indonesian Context)
 Never prefix Indonesian grammatical affixes (`di-`, `meng-`, `ter-`, `pe-`) onto raw English stems:
 
 | Hybrid Neologism (Banned) | Standard Indonesian | Pure English Alternative |
@@ -66,14 +114,14 @@ Never prefix Indonesian grammatical affixes (`di-`, `meng-`, `ter-`, `pe-`) onto
 
 ---
 
-## 5. Dynamic Text Expansion & Internationalization Layout
+## 7. Dynamic Text Expansion & Internationalization Layout
 
 Text length varies drastically between languages:
 - German and Dutch expand +20% to +35% compared to English.
 - Indonesian expands +15% to +30% for verb-rich phrases.
 - Japanese and Chinese are visually dense and vertically taller.
 
-### 5.1 Layout Rules for Expanding Strings
+### 7.1 Layout Rules for Expanding Strings
 1. **Never set fixed widths on action buttons:**
    ```html
    <!-- BANNED: clips or overflows in German/Indonesian -->

package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/craft/color-surfaces.md

@@ -47,3 +47,28 @@ Grounded in: Apple HIG, Google Material Design 3, and Refactoring UI Color Strat
   - When placing secondary text on a colored or dark surface, tint the text using the parent background hue or foreground token (`text-primary-foreground/70`).
   - **Never use neutral gray text (`text-slate-400`) on a saturated or colored background.** It produces a muddy, dirty optical illusion.
 
+---
+
+## 4. Integrated Scorecards & Metric Blocks (Anti-Sticker Invariant)
+
+- **Ban The Sticker Box:** Never place an isolated white box with a thin border floating inside an already white or light header canvas. This creates an optical "detached sticker" artifact.
+- **Anchor Into Layout Chrome:**
+  - Integrate scorecards directly into the identity header rail or stage banner using a unified divider (`border-l border-border/80 pl-6`) or structural inset well (`bg-muted/40`).
+- **Semantic Tinting for Evaluation Scores:**
+  - When communicating aggregate grades (e.g. `84,20 / 100`, Predikat B):
+    - Background: subtle semantic tint (`bg-emerald-500/10` or `bg-slate-500/10`).
+    - Border: matching tinted hairline (`border border-emerald-500/20`).
+    - Typography: tabular numbers (`font-mono tabular-nums`) with clear contrast ($Display \ge 3.5\times Body$).
+  - Always position the grading scale key (e.g. `A > 85, B 71-85`) in immediate secondary proximity as muted metadata.
+
+---
+
+## 5. Contextual Inline Alerts & Callouts (The Callout Invariant)
+
+- **Never Float Warning Text Adrift:** Warning notes, disclaimers, or temporary state alerts must NEVER be dumped as raw floating text between layout sections.
+- **The Callout Invariant:** Every alert must reside in a structured callout container:
+  - Container: 1px hairline border with matching light background tint (e.g. `border border-amber-500/30 bg-amber-500/10 rounded-md p-3`).
+  - Icon Anchor: Dedicated semantic SVG icon (alert circle, triangle) aligned with first line of text.
+  - Placement: Positioned immediately above or inside the data table/form it modifies, establishing unmistakable contextual binding.
+
+