@event4u/agent-config 8.9.0 → 8.11.0

package/dist/agent-src/skills/perf-feedback-craft/evals/evals.json

@@ -0,0 +1,16 @@
+{
+  "skill": "perf-feedback-craft",
+  "_calibration": "Behavioural fixture (road-to-skill-eval-coverage Phase 2, default-surface). Deterministic assertions on a real output property where reliable; rubric pins the qualitative core as a known-limit (pass ratified in PR review, not a hidden judge). finding_floor n is a conservative floor, not a calibrated per-host number.",
+  "scenarios": [
+    {
+      "id": "perf-review-feedback",
+      "prompt": "Give this engineer performance feedback: they ship fast but skip tests.",
+      "assertions": [
+        {
+          "kind": "rubric",
+          "criterion": "Names the specific behaviour + its impact with an example, is balanced (strength + growth), and gives an actionable next step — not vague praise/blame."
+        }
+      ]
+    }
+  ]
+}

package/dist/agent-src/skills/performance/SKILL.md

@@ -56,7 +56,7 @@ Re-measure after fix. Check that cache invalidation works correctly.
 
 - Cache invalidation bugs are worse than slow queries — don't add caching everywhere.
 - Eager loading N+1 is the #1 win — always check list endpoints.
-- Don't cache Eloquent collections with loaded relations — too large.
+- Don't cache ORM collections/entities with loaded relations (Eloquent, Doctrine, Prisma) — too large.
 - Always include tenant ID in cache keys (multi-tenant).
 
 ## Do NOT

package/dist/agent-src/skills/pest-testing/SKILL.md

@@ -56,6 +56,7 @@ discipline, mock-isolation gates, and the 12 process rationalizations
 - Keep setup minimal and relevant.
 - Favor confidence and maintainability over excessive mocking.
 - Cover happy path, validation failures, authorization failures, and important edge cases.
+- Enumerate the cases BEFORE writing — run the [`test-case-discovery`](../test-case-discovery/SKILL.md) funnel; floor per behavior: 1 happy + 1 boundary + 1 error (+1 abuse on security paths).
 
 ## TDD workflow (Red-Green-Refactor)
 
@@ -291,7 +292,6 @@ When generating Pest tests:
 - assert both response and side effects where relevant
 - keep tests readable, isolated, and maintainable
 
-
 ### Filter Pest output
 
 When triaging a verbose run, narrow the output with `--filter` (Pest)

package/dist/agent-src/skills/php-debugging/SKILL.md

@@ -214,9 +214,26 @@ docker compose logs php-xdebug | rg --color=never "$REQUEST_ID"
 - Do NOT use var_dump() or dd() — use Xdebug breakpoints.
 - Do NOT debug in the fast container — switch to the Xdebug container.
 
+## Clarification guard — ambiguous repro → ask
+
+If the bug repro is unclear (which request, which user, which env, which input shape?), do not start placing breakpoints at random. Ask the user for the failing payload, the exact route, or the Sentry trace. Setting breakpoints based on a guessed flow wastes a session.
+
 ## Auto-trigger keywords
 
 - Xdebug
 - PHP debugging
 - breakpoint
 - step debugging
+
+## Known Laravel bug patterns (from bug-analyzer)
+
+- N+1 queries hidden in loops or accessors
+- Missing `->fresh()` after update when using same instance
+- Eloquent lazy loading in queued jobs (serialization issues)
+- `now()` timezone mismatches
+- Missing FK constraints allowing orphaned records
+- `DB::transaction()` with external side effects (emails, API calls)
+- Model events firing during seeding or migration
+- Off-by-one errors in pagination or date ranges
+- Silent exception swallowing (`catch (\Exception $e) {}`)
+- Floating point comparison for money/quantities

package/dist/agent-src/skills/playwright-testing/SKILL.md

@@ -13,6 +13,11 @@ packs:
 
 ## When to use
 
+> **Design verification.** When exercising a UI artifact, run the
+> [design-artifact verification checklist](../../../docs/contracts/design-artifact-verification.md#verification-checklist)
+> (open → console/load → viewport → text-fit → assets → interaction) and capture
+> evidence; a design task with browser capability present is not "done" without it.
+
 Use this skill when:
 - Writing end-to-end tests with Playwright
 - Automating browser interactions for testing
@@ -31,6 +36,7 @@ Use this skill when:
 3. **Check existing tests** — match patterns in `tests/e2e/` or `e2e/`.
 4. **Check test utilities** — look for page objects, fixtures, helpers.
 5. **Check CI setup** — how are E2E tests run in the pipeline?
+6. **Enumerate the cases** — run the [`test-case-discovery`](../test-case-discovery/SKILL.md) funnel per user flow before writing specs; cover the happy flow AND at least one boundary (empty state, max input) and one error path (failed request, validation rejection) per flow — never the happy flow alone.
 
 ## Test structure
 
@@ -183,6 +189,12 @@ jq '.suites[].specs[] | select(.tests[].results[].status=="failed")' pw.json
 rg --color=never 'getByRole.*Submit' test-results/
 ```
 
+**Run verification.** The test run's **exit code** is the pass/fail signal — `0`
+means every spec passed, non-zero means at least one failed. Read the **command
+output** (or the `--reporter=json` above) to **diagnose** the failing spec's
+**root cause**; do not blindly re-run hoping it turns green — a retry-until-pass
+is not a fix, and a flaky green hides the real defect.
+
 ## Avoiding flaky tests
 
 | Problem | Solution |
@@ -263,3 +275,7 @@ await page.route('**/api/users', route =>
 - Do NOT test implementation details — test user-visible behavior.
 - Do NOT put assertions in Page Objects — assertions belong in test files.
 - Do NOT commit `.only` — enforce via `forbidOnly: !!process.env.CI`.
+
+## Anti-bruteforce — diagnose before retry
+
+When a spec fails, do not retry blindly by re-running, swapping locators at random, or bumping timeouts until green. Diagnose the root cause first: open the trace viewer, inspect the failing locator's `aria` tree, identify the real reason (timing, locator, app state), then apply a targeted fix. Trial-and-error locator swaps mask flaky test design.

package/dist/agent-src/skills/prompt-engineering-patterns/evals/evals.json

@@ -0,0 +1,16 @@
+{
+  "skill": "prompt-engineering-patterns",
+  "_calibration": "Behavioural fixture (road-to-skill-eval-coverage Phase 2, default-surface). Deterministic assertions on a real output property where reliable; rubric pins the qualitative core as a known-limit (pass ratified in PR review, not a hidden judge). finding_floor n is a conservative floor, not a calibrated per-host number.",
+  "scenarios": [
+    {
+      "id": "apply-prompt-pattern",
+      "prompt": "Which prompting pattern should I use to get structured extraction from messy text, and why?",
+      "assertions": [
+        {
+          "kind": "rubric",
+          "criterion": "Names a concrete pattern (e.g. schema-constrained/structured-output, few-shot) matched to the extraction task, with the trade-off — not a generic tips list."
+        }
+      ]
+    }
+  ]
+}

package/dist/agent-src/skills/readme-writing/SKILL.md

@@ -238,3 +238,5 @@ to every README you author.
 - Do NOT skip repository inspection before writing
 - Do NOT preserve weak structure from an existing README just because it exists
 - Do NOT add marketing language ("blazing fast", "revolutionary", "next-gen")
+
+→ Final prose pass for audience-facing output: [`humanizer`](../humanizer/SKILL.md) — remove AI-writing tells before delivery.

package/dist/agent-src/skills/readme-writing-package/SKILL.md

@@ -348,3 +348,5 @@ to every package README you author.
 - Do NOT hide requirements or version constraints
 - Do NOT write a giant example when a 10-line one would do
 - Do NOT overload README with reference material — link to /docs
+
+→ Final prose pass for audience-facing output: [`humanizer`](../humanizer/SKILL.md) — remove AI-writing tells before delivery.

package/dist/agent-src/skills/refine-prompt/evals/evals.json

@@ -0,0 +1,16 @@
+{
+  "skill": "refine-prompt",
+  "_calibration": "Behavioural fixture (road-to-skill-eval-coverage Phase 2, default-surface). Deterministic assertions on a real output property where reliable; rubric pins the qualitative core as a known-limit (pass ratified in PR review, not a hidden judge). finding_floor n is a conservative floor, not a calibrated per-host number.",
+  "scenarios": [
+    {
+      "id": "refine-a-prompt",
+      "prompt": "Improve this prompt: 'write good marketing copy'.",
+      "assertions": [
+        {
+          "kind": "rubric",
+          "criterion": "Adds role, concrete task, constraints, and success criteria; removes vague adjectives — a measurably tighter prompt, not a paraphrase."
+        }
+      ]
+    }
+  ]
+}

package/dist/agent-src/skills/refine-ticket/evals/evals.json

@@ -0,0 +1,16 @@
+{
+  "skill": "refine-ticket",
+  "_calibration": "Behavioural fixture (road-to-skill-eval-coverage Phase 2, default-surface). Deterministic assertions on a real output property where reliable; rubric pins the qualitative core as a known-limit (pass ratified in PR review, not a hidden judge). finding_floor n is a conservative floor, not a calibrated per-host number.",
+  "scenarios": [
+    {
+      "id": "refine-ticket-dor",
+      "prompt": "Refine this ticket: 'make search better'.",
+      "assertions": [
+        {
+          "kind": "rubric",
+          "criterion": "Tightens to a bounded scope with acceptance criteria + a definition-of-ready; asks the one blocking question rather than guessing scope."
+        }
+      ]
+    }
+  ]
+}

package/dist/agent-src/skills/release-comms/SKILL.md

@@ -131,3 +131,5 @@ Sprint 47 ships a one-click monthly export and three small bug fixes:
 - "After this release, you can pull a board-ready monthly report in one click." (active, at-risk — same sentence ⇒ collapse to one).
 - Surfaces: changelog (full), in-app prompt to active users on next month-end, email to at-risk cohort with the same sentence and one CTA. No social.
 - Truth-check: claim links to the export PR; "one click" is literal — verified against the shipped UI.
+
+→ Final prose pass for audience-facing output: [`humanizer`](../humanizer/SKILL.md) — remove AI-writing tells before delivery.

package/dist/agent-src/skills/release-comms/evals/evals.json

@@ -0,0 +1,16 @@
+{
+  "skill": "release-comms",
+  "_calibration": "Behavioural fixture (road-to-skill-eval-coverage Phase 2, default-surface). Deterministic assertions on a real output property where reliable; rubric pins the qualitative core as a known-limit (pass ratified in PR review, not a hidden judge). finding_floor n is a conservative floor, not a calibrated per-host number.",
+  "scenarios": [
+    {
+      "id": "write-release-note",
+      "prompt": "Write the release announcement for our v-next dashboard redesign.",
+      "assertions": [
+        {
+          "kind": "rubric",
+          "criterion": "Leads with user value + what changed, notes any migration/breaking step, and matches the product voice — not a raw changelog dump."
+        }
+      ]
+    }
+  ]
+}

package/dist/agent-src/skills/rice-prioritization/evals/evals.json

@@ -0,0 +1,20 @@
+{
+  "skill": "rice-prioritization",
+  "_calibration": "Behavioural fixture (road-to-skill-eval-coverage Phase 2, default-surface). Deterministic assertions on a real output property where reliable; rubric pins the qualitative core as a known-limit (pass ratified in PR review, not a hidden judge). finding_floor n is a conservative floor, not a calibrated per-host number.",
+  "scenarios": [
+    {
+      "id": "rice-rank-three",
+      "prompt": "Prioritize these three features with RICE: A (reach 5000, impact 2, conf 80%, effort 3), B (reach 1000, impact 3, conf 100%, effort 1), C (reach 8000, impact 1, conf 50%, effort 5).",
+      "assertions": [
+        {
+          "kind": "contains",
+          "value": "RICE"
+        },
+        {
+          "kind": "rubric",
+          "criterion": "Computes RICE = Reach×Impact×Confidence/Effort per item (A≈2667, B=3000, C=800) and ranks by the score, not by gut feel."
+        }
+      ]
+    }
+  ]
+}

package/dist/agent-src/skills/roadmap-writing/SKILL.md

@@ -91,6 +91,16 @@ and council-pass notes capture the *why*; checkboxes capture the
 [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)
 Iron Law #2.
 
+**Bind a `verify:` on behavior-changing steps.** A step that changes
+behavior (a new guard, migration, wired endpoint, mechanism edit) SHOULD
+carry a narrow `verify:` command in an inline annotation —
+`- [ ] Wire the guard <!-- verify: task test -- --filter=GuardTest -->` —
+so its `[x]` flip is machine-checkable, not just agent-asserted (template
+rule 23; enforced by the flip-guard). Bind it only where a single narrow
+command (targeted test / grep / build of the touched surface) proves the
+step; leave it off doc-only / prose steps, never the full CI suite
+(`roadmap-ci-steps-policy`).
+
 ### 4b. Declare the execution mode (frontmatter)
 
 Every new roadmap declares how a later `/roadmap:process-*` run should
@@ -220,57 +230,18 @@ originally wrote it.
 
 ### 8. Source-derived & capability-adoption roadmaps (conditional)
 
-Fires **only** when roadmap originates from external input or adopts
-capabilities into the suite:
-
-- competitive / capability harvest, external suggestion, or external
-  LLM ideation thread, **or**
-- decision to integrate/adopt new skills, commands, or a pack, **or**
-- plan whose design has genuinely contested, unresolved trade-offs.
-
-Ordinary internally-originated roadmap → **skip this section**; §§ 0–7
-are the whole job. Don't bolt a Provenance block or gap-table onto a
-plan needing neither (template rule 19).
-
-When it fires, add four moves to §§ 0–7:
-
-**A. Gap-table before drafting (don't adopt — integrate).** Audit each
-proposed item against the *existing* skill / command / rule surface;
-classify `KEEP` (verified gap), `FOLD` (into a named existing artefact),
-`CUT` (already covered). Only `KEEP` items become scope; `FOLD`/`CUT`
-recorded so the cut is auditable. Negative grep ≠ proof — open the
-nearest existing artefacts (per
-[`think-before-action`](../../rules/think-before-action.md); for an
-external source,
-[`external-reference-deep-dive`](../../rules/external-reference-deep-dive.md)).
-
-**B. Resolve contested design in council *first*, then author.** Default
-council flow (`/roadmap:ai-council`) *challenges a finished roadmap*. For
-a contested/source-derived plan, run council **up front** on the design
-questions (`/council:design`, or the
-[`ai-council`](../ai-council/SKILL.md) skill), converge, **then** write
-the roadmap encoding the verdicts — ships already-decided, not as open
-questions in prose. One run, converge; don't relitigate.
-
-**C. Encode the decision so it survives.**
-- Inline council convergence under `## Council notes (<date>, <depth>)`
-  — members + date, **never** a session filepath
-  ([`no-roadmap-references`](../../rules/no-roadmap-references.md)).
-- Add `## Provenance` — source by **neutral descriptor** (never the raw
-  competitor/tool name,
-  [`source-confidentiality`](../../rules/source-confidentiality.md));
-  retain the real link as an `ENC1:` token via
-  `src/scripts/_lib/link_crypto.ts encrypt --value <url>`.
-- Save the locked decision to memory (project type, "don't relitigate")
-  so a future session does not re-derive it.
-
-**D. Make "integration, not dump" a testable acceptance criterion.** AC
-encodes the anti-dump litmus, decidably: visible commands within the
-pack's `size_class` budget; each new visible command reuses ≥ 2 existing
-skills; no new artefact duplicates an existing one; governance preflight
-recorded — `domain-adoption-policy` (new domain?), `persona-governance`
-(new personas?), `framework-neutrality`, `size-enforcement` —
-disposition stated in the roadmap.
+Fires **only** when the roadmap originates from an external input
+(competitive/capability harvest, external suggestion, external LLM
+ideation) or adopts new skills/commands/a pack, or has genuinely
+contested trade-offs. For an ordinary internally-originated roadmap,
+**skip this section** — §§ 0–7 are the whole job.
+
+When it fires, add four moves — a gap-table before drafting (KEEP/FOLD/CUT,
+integrate don't dump), resolve contested design in the council *first*
+then author, encode the decision so it survives (Council notes +
+neutral-descriptor Provenance + memory lock), and make "integration, not
+dump" a testable acceptance criterion. Full four-move detail →
+[`roadmap-writing-source-derived`](../../agent-src/contexts/execution/roadmap-writing-source-derived.md).
 
 ## Output format
 

package/dist/agent-src/skills/runway-cognition/evals/evals.json

@@ -0,0 +1,20 @@
+{
+  "skill": "runway-cognition",
+  "_calibration": "Behavioural fixture (road-to-skill-eval-coverage Phase 2, default-surface). Deterministic assertions on a real output property where reliable; rubric pins the qualitative core as a known-limit (pass ratified in PR review, not a hidden judge). finding_floor n is a conservative floor, not a calibrated per-host number.",
+  "scenarios": [
+    {
+      "id": "runway-shape-and-decision",
+      "prompt": "We have $4.2M cash and burn $560k/month. How long do we have and what should we do?",
+      "assertions": [
+        {
+          "kind": "contains",
+          "value": "runway"
+        },
+        {
+          "kind": "rubric",
+          "criterion": "Computes months-of-runway = cash/burn (≈7.5) AND frames raise/hold/cut-vs-grow as a shape against the org-stage band, not a single number."
+        }
+      ]
+    }
+  ]
+}

package/dist/agent-src/skills/scenario-modeling/evals/evals.json

@@ -0,0 +1,20 @@
+{
+  "skill": "scenario-modeling",
+  "_calibration": "Behavioural fixture (road-to-skill-eval-coverage Phase 2, default-surface). Deterministic assertions on a real output property where reliable; rubric pins the qualitative core as a known-limit (pass ratified in PR review, not a hidden judge). finding_floor n is a conservative floor, not a calibrated per-host number.",
+  "scenarios": [
+    {
+      "id": "base-upside-downside",
+      "prompt": "Model base / upside / downside for our annual plan off a $6.3M commit.",
+      "assertions": [
+        {
+          "kind": "contains",
+          "value": "downside"
+        },
+        {
+          "kind": "rubric",
+          "criterion": "Downside names a concrete HEADWIND (not base×0.8), upside names a tailwind, and reads optionality — not just ±20% on base."
+        }
+      ]
+    }
+  ]
+}

package/dist/agent-src/skills/security-audit/SKILL.md

@@ -67,7 +67,7 @@ User Input → Controller → Validation → Service → DB/File/External
 | Category | What to look for |
 |---|---|
 | **SQL Injection** | Raw queries with concatenation, missing parameter binding |
-| **XSS** | Unescaped output in Blade (`{!! !!}`), JSON responses with HTML |
+| **XSS** | Unescaped template output (Blade `{!! !!}`, JSX `dangerouslySetInnerHTML`, Jinja `|safe`), JSON responses with HTML |
 | **CSRF** | Missing middleware, API endpoints without token verification |
 | **Auth bypass** | Missing policy checks, broken gate logic, `withoutMiddleware()` |
 | **IDOR** | Direct object access without ownership verification |
@@ -81,14 +81,7 @@ User Input → Controller → Validation → Service → DB/File/External
 
 ### 4. Framework-specific checks
 
-**Laravel:**
-- `env()` in non-config files (leaks in debug mode)
-- Debug mode (`APP_DEBUG=true`) in production
-- Missing `$fillable` on models used with `request()->all()`
-- `Route::any()` exposing unintended HTTP methods
-- Missing rate limiting on login/register/password-reset
-- Broadcast channels without proper authorization
-- Missing encryption on sensitive cookie/session data
+→ Laravel-specific checks: see [`laravel`](../laravel/SKILL.md) § Security audit checks.
 
 ### 5. Dependency audit
 
@@ -99,6 +92,10 @@ User Input → Controller → Validation → Service → DB/File/External
 
 ## Output format
 
+1. Emit one entry per vulnerability using the field list below; one finding = one block, never merge.
+2. Category must map to an OWASP Top 10 (or LLM Top 10) bucket; Severity must use Low / Medium / High / Critical with a single Exploitability tag.
+3. Close with a *Recommended Fix Order* ranked by exploitability × blast radius and tag each line with Confidence.
+
 For each vulnerability:
 
 - **Vulnerability:** concise title

package/dist/agent-src/skills/sentry-integration/SKILL.md

@@ -147,7 +147,7 @@ search_events(organizationSlug='my-org', naturalLanguageQuery='count of database
 - **Skill:** `logging-monitoring` — full monitoring stack (Sentry + Grafana + Loki)
 - **Skill:** `bug-analyzer` — uses Sentry as input for bug investigation
 - **Command:** `/bug-investigate` — fetches Sentry details automatically
-- **Config:** `config/sentry.php` — Sentry DSN and configuration
+- **Config:** the SDK's config surface (`config/sentry.php` in Laravel, `sentry.client.config.ts` in Next.js) — Sentry DSN and configuration
 
 
 ## Output format
@@ -157,7 +157,7 @@ search_events(organizationSlug='my-org', naturalLanguageQuery='count of database
 
 ## Gotcha
 
-- Sentry groups errors by stacktrace — different root → may appear as the same issue. Check multiple events.
+- Sentry groups errors by stacktrace — different root causes may appear as the same issue. Check multiple events.
 - The model tends to analyze only the latest event — check the "Events" tab for patterns across time.
 - Don't use Sentry MCP tools for simple lookups — use the Sentry web UI link instead (saves tokens).
 

package/dist/agent-src/skills/skill-improvement-pipeline/SKILL.md

@@ -107,6 +107,14 @@ Decide what to create:
 
 ### Step 4: Create or Update
 
+> **Anchor exact commands to the transcript, not the journal.** A session
+> journal is a *lossy summary*; a command, path, or flag reconstructed from it
+> can be subtly wrong. Before writing a concrete step (a command, a file path, a
+> config key) into a rule or skill, confirm it against the anchored source
+> transcript — carry a `transcript:` / session anchor on the mined learning so
+> the exact wording is recoverable, and verify against it rather than trusting
+> the summary.
+
 - **New rule** → create in `.agent-src.uncondensed/rules/`, follow rule conventions
 - **New skill** → use `skill-writing` skill, create in `.agent-src.uncondensed/skills/`
 - **Update existing** → use `skill-management` skill

package/dist/agent-src/skills/source-discovery/SKILL.md

@@ -92,7 +92,7 @@ distinct methods/fields *intended* to be used, OR the source exposes >50 methods
 and ≥1 is used, OR a prior hallucination on it, OR local types/README are
 insufficient)** — judged on *intended* use at discovery (still built **before**
 coding). For a card-worthy dependency named in the task: **local-first**
-(`node_modules` / `vendor` README + type defs; the **installed version is ground
+(`node_modules` / `vendor/` README + type defs; the **installed version is ground
 truth**), then the net (registry → repo host → homepage). **Pin the remote ref to
 the installed version — never blind `main`.** Reuse
 [`external-reference-deep-dive`](../../rules/external-reference-deep-dive.md) +
@@ -106,19 +106,21 @@ Resolve and read the actual class fresh (Step 0). In-codebase → local, no card
 
 ### E. Global cards — leads only (v2, ADR-100)
 
-When `knowledge.global_sharing.enabled` (user-global, **default off until cross-project reuse measured** — ADR-103), a matching
+When `knowledge.global_sharing.enabled` (user-global, default on), a matching
 card may exist in the per-user file-first store
-(`~/.event4u/agent-config/knowledge/`), promoted from another project. **Lead,
-never a build input**:
-
-- Load **negative facts + pointers** as leads (`trust: durable`).
-- Load **positive structure** under **"Assumed (from card · GLOBAL,
-  unverified)"** — record via `evidence_report.ts add --bucket assumed --origin
-  global …` and **re-confirm vs the live source this session** before use
-  (version skew / schema drift). Never "Verified" on the global card alone.
-- `public`/`vendor` seen in ≥ `auto_promote_threshold` distinct repos → one-tap
-  promotion **suggestion** (never silent); `proprietary` is manual-only. Record
-  sightings via `_lib/knowledge_global_promote.ts record-seen`.
+(`~/.event4u/agent-config/knowledge/`), promoted from another project. It is a
+**lead, never a build input**:
+
+- Load its **negative facts + pointers** as usable leads (`trust: durable`).
+- Load any **positive structure** into the Evidence Report under **"Assumed
+  (from card · GLOBAL, unverified)"** — record it with
+  `evidence_report.ts add --bucket assumed --origin global …` and **re-confirm it
+  against the live source this session** before use (version skew / schema drift
+  across projects). Never "Verified" on the global card alone.
+- A `public`/`vendor` card seen in ≥ `auto_promote_threshold` distinct repos
+  triggers a one-tap promotion **suggestion** (never silent). `proprietary` cards
+  are manual-only and never auto-shared. Record sightings via
+  `_lib/knowledge_global_promote.ts record-seen`.
 
 ## Missing structure → fixed extension workflow
 
@@ -156,21 +158,21 @@ threshold is met, a thin committed card.
 
 ## Evidence v2 — self-building context (heuristics only, never a bypass)
 
-Curated project-intelligence (Class A config digests, Class B observed conventions,
-Class C learned lessons) may be loaded to inform *where to look* and *what convention
-to expect* — but read **for heuristics only** and **never** bypasses a fresh structural
-read. A field/endpoint/column/value is still confirmed against a live source this
-session. v2 capture is **write-only into gitignored intake** (agent may *suggest* a
-signal, never silently commit); trust and commit are always human-gated. Full model +
-the three classes + memory tiers:
+Curated project-intelligence (Class A config digests, Class B observed
+conventions, Class C learned lessons) may be loaded to inform *where to look* and
+*what convention to expect* — but it is read **for heuristics only** and **never**
+bypasses a fresh structural read. A field/endpoint/column/value is still confirmed
+against a live source this session. v2 capture is **write-only into gitignored
+intake** (the agent may *suggest* a signal, never silently commit); trust and
+commit are always human-gated. Full model + the three classes + memory tiers:
 [`project-intelligence`](../../agent-src/contexts/execution/project-intelligence.md).
 
 ## Knowledge capture (`api_shape_learned` / `convention_detected` events)
 
 A confirmed API/GraphQL shape (§B) or an observed coding convention with
-≥ 2 supporting locations is worth persisting for the team, distinct
-from the per-session Evidence Report above. Append to the knowledge
-intake — never write a tracked page mid-task:
+≥ 2 supporting locations is worth persisting for the team, distinct from
+the per-session Evidence Report above. Append to the knowledge intake —
+never write a tracked page mid-task:
 
 ```bash
 ./scripts-run src/scripts/emit_knowledge_event --type api_shape_learned \
@@ -182,7 +184,7 @@ intake — never write a tracked page mid-task:
 
 `/team-knowledge consolidate` turns accumulated events into
 `agents/knowledge/concepts/` pages as a reviewed batch — see
-[`knowledge-pages`](../../templates/contexts/knowledge-pages.md).
+[`knowledge-pages`](../../agent-src/templates/contexts/knowledge-pages.md).
 
 ## Gotchas
 

package/dist/agent-src/skills/spreadsheet-authoring/SKILL.md

@@ -0,0 +1,98 @@
+---
+model_tier: high
+name: spreadsheet-authoring
+description: "Use when building or editing a spreadsheet or model — formulas over hardcoded values, read-back after writes, official-source data, pivot-first charts. Triggers on 'spreadsheet', 'build a model'."
+domain: process
+workspaces:
+  - finance
+packs:
+  - finance-basic
+trust:
+  level: professional
+install:
+  removable: true
+execution:
+  type: manual
+---
+
+# spreadsheet-authoring
+
+> The spreadsheet surface's correctness floor (per
+> [`surface-agent-contracts`](../../../docs/contracts/surface-agent-contracts.md)):
+> a spreadsheet's **truth source is the formula read-back**, not a plausible
+> table of numbers. A cell that holds a hardcoded computed value is a latent
+> lie — it silently goes stale the moment an input changes.
+
+## When to use
+
+- Building or editing a spreadsheet / financial model (SaaS, ops, budget, forecast).
+- Charting raw tabular data.
+- Entering web-sourced or financial figures into cells.
+
+Do NOT use for: per-customer unit-economics *reasoning* (route to
+`unit-economics-modeling`), runway *shape* (route to `runway-cognition`), or a
+prose document/table (that is the document surface, `doc-coauthoring`).
+
+## Procedure
+
+1. **Detect the surface + capability.** Confirm a spreadsheet is the right
+   surface (not a prose table). Confirm native spreadsheet tooling is available;
+   if not, see § Capability-aware degradation.
+2. **Formulas over hardcoded values.** Any computed cell holds a **formula**
+   (`=SUM(...)`, `=B2*C2`), never the typed-in result. Hardcoding a computed
+   value is the cardinal spreadsheet defect — it does not recalculate.
+3. **Read back after every write.** After writing a formula, read the cell back
+   and confirm no formula error (`#REF!`, `#DIV/0!`, `#VALUE!`). The read-back is
+   the spreadsheet's verification truth source.
+4. **Source-comment web-sourced cells.** Any figure taken from the web carries a
+   cell comment with its source. Financial figures follow the
+   [`spreadsheet-source-quality`](../../rules/spreadsheet-source-quality.md) rule
+   (official sources first; aggregators need permission + unofficial marking).
+5. **Expand ranges on structural edits.** After inserting a row/column inside a
+   formula's range, expand the range (or use a whole-column / table reference) so
+   the new data is included — verified by read-back.
+6. **Pivot-first charting.** Chart from a pivot/aggregate of raw data, not
+   directly from hundreds of raw transactional rows.
+7. **Bulk range operations over manual cell loops.** Prefer a single range
+   formula / fill over hand-editing cells one by one.
+
+## Capability-aware degradation
+
+- **Native tooling present** → write + read back formulas directly.
+- **Only exported files + a parser present** → operate on the exported file;
+  state that formulas were written into the export, and what the target app will
+  recompute on open.
+- **Neither** → do NOT pretend formulas were written or read back. Say plainly
+  what cannot be verified on this host, and deliver the formula definitions +
+  the layout as a durable plan the user applies in their spreadsheet app.
+
+## Output format
+
+1. **The spreadsheet / model** — cells carrying formulas (not baked values),
+   source comments on sourced cells, pivots feeding charts.
+2. **`assumptions.md`** — every input value, sourced or marked `assumption`;
+   the official-vs-unofficial status of each financial figure.
+3. **`verification-note.md`** — which cells were read back, any formula errors
+   found + fixed, and — on a degraded host — exactly what could not be verified.
+
+## Gotcha
+
+- Hardcoding a computed value instead of a formula is the #1 spreadsheet defect:
+  it looks right today and is silently wrong after the next input change.
+- A formula range not expanded after a row insert silently drops the new row
+  from every downstream total.
+- Charting straight off a raw transactional table (no pivot) produces an
+  unreadable chart and hides the data's real shape.
+- An aggregator/news figure entered as if it were official financial data is a
+  sourcing defect even when the number happens to be right — see
+  `spreadsheet-source-quality`.
+- On a host without spreadsheet tooling, claiming "formulas written + verified"
+  is a fabricated verification (never do it — degrade honestly).
+
+## Do NOT
+
+- Do NOT write a computed value where a formula belongs.
+- Do NOT enter a financial figure from an aggregator/news/social source as
+  official without the user's explicit permission + a cell-level unofficial mark.
+- Do NOT claim a formula was read back / verified on a host that cannot open the
+  spreadsheet — say what could not be verified instead.