@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/incident-postmortem-extraction.md

@@ -0,0 +1,190 @@
+# Incident / Postmortem → Skill Extraction
+
+Layer on top of the main extraction flow when the source is an incident, outage, regression, security event, data corruption, deploy failure, or a postmortem document. The goal is to turn a single bad event into a **durable failure-class guardrail** owned by the right skill — not a procedural patch about that one incident.
+
+## When this layer applies
+
+Apply when at least one of:
+- A production incident happened (user-visible outage, error budget burn, data loss/corruption, security event, perf regression, deploy/rollback).
+- A near-miss was caught only because a human noticed (would have been an incident without that human).
+- A postmortem doc / RCA write-up exists or is being written.
+- A regression keeps recurring across services or repos.
+
+Do NOT apply when:
+- The fix is a code change with no systemic lesson — commit + move on, no skill edit.
+- The "incident" is just a user mis-using the product correctly. Route to product / UX skills if there is a UX gap; otherwise discard.
+- The lesson is fully owned by code/tests/CI/monitoring config and does not change how future agents decide — land it there, not as agent behavior.
+
+## Incident as a source class
+
+This pattern **extends** the standard source-register row defined in `source-register.md` (`source_id | source_type | class | path/file_key | status | min_depth | actual_depth | extracted_mechanisms | discarded_business_details | target_skill | evidence_link`). The columns below are the additions and conventions specific to incident sources; do not omit the required columns from the standard row.
+
+This pattern **specializes the standard singular `target_skill` field into plural `target_skills`** (see below), with an additional `coordination_owner` to hold the multi-owner invariant. The shared register schema remains singular until a parent rewrite lands plural ownership across all extraction classes; treat the plural variant as a documented per-pattern specialization, not a contradiction.
+
+| Column added or specialized | Convention |
+| --- | --- |
+| `source_id` | sanitized event handle (no real ticket id, no customer name, no date with year tied to a known event) |
+| `source_type` | `incident` |
+| `class` | `outage` / `data` / `security` / `perf` / `deploy` / `near-miss` / `recurring-regression` / `external-dependency` |
+| `severity` | placeholder severity tag — use generic tokens like `<severity-high>` / `<severity-medium>` / `<near-miss>` in the shared register; real severity labels live in the private alias map |
+| `evidence` | what is actually inspectable: timeline excerpts (sanitized), alert rule, dashboard panel, code diff that introduced it, code diff that fixed it, runbook snippet |
+| `min_depth` / `actual_depth` | per the standard rules — `summary-only` / `timeline-only` / `fix-diff-only` / `full-postmortem-read` |
+| `discarded_sensitive_details` | enumerate the PII / customer detail / dashboard URLs / auth material that was inspected and discarded; protects against the same detail leaking via a later mining pass |
+| `target_skills` | **plural — list every affected skill.** An incident commonly updates a stack/dev skill + a platform/ops skill + the extraction workflow itself + `testing-strategy`; never collapse to one target. Each owner gets its own target-output row downstream. |
+| `coordination_owner` | the single skill that holds the canonical cross-skill invariant for this incident. Other `target_skills` rows reference their slice of that invariant. Without this, a multi-owner landing fragments — each owner passes review while no skill owns the end-to-end guardrail. |
+| `canonical_guardrail` | one-sentence statement of the invariant the coordination owner holds (e.g. "stateful writes are idempotent at every entry point"). Each per-owner row implements a slice. |
+| `completion_evidence` | the counterfactual replay outcome + which gate the new rule installs |
+| `status` | `pending` / `mined` / `routed` / `excluded` |
+
+If the only evidence is a summary or chat scrollback, mark `actual_depth: summary-only` and downgrade extraction confidence accordingly. Do not promote a summary-only incident into a strong cross-skill rule.
+
+## The transform method (incident → durable rule)
+
+Five steps. Each must produce a recorded line; missing any line means the extraction is shallow.
+
+1. **Failure class** — generalize the specific event to a class. "Service X dropped writes during deploy Y on date Z" → class: *write loss during rolling restart of a stateful component*. The class is what future agents must recognize; the incident is just one instance.
+2. **Causal chain (earliest practical prevention point)** — this is the *deepening* branch within the Deep RCA five moves (see `source-to-skill-extraction.md`, Deep RCA For Extraction): you still **widen** to the multiple contributing factors first, split **active vs latent** conditions, and use **local rationality** (why it made sense at the time) rather than one linear chain — then deepen each material branch here. Record why each prior layer did not catch it. Do **not** stop at the first controllable layer; a test or a review is often controllable but only catches the symptom while the actual durable fix is upstream (contract definition, schema ownership, capability model, MR readiness, release process). Continue the chain until you identify the **earliest practical prevention point in the delivery chain**, then list each later layer that could *also* have caught it as a **secondary control** (defense in depth). "Engineer was tired" is not controllable; "the contract had no idempotency key requirement and the contract review skill did not enforce it" is the earliest practical prevention point, with "the integration test suite did not exercise duplicate delivery" as a secondary control. **"Earliest practical" is bounded by executable enforceability:** the earliest gate that has all four of (a) a named artifact (skill rule / contract field / test / review checklist item / launch gate item), (b) an owning skill or team that can change it today, (c) an observable check an agent or reviewer can run, and (d) a **reachable surface** (bootstrap / description / closeout / hook / CI) that makes the next agent actually hit it in time — a rule landed only in a deep reference nothing routes them to read does not fire (per the Core Rule firing-path proof). If a candidate upstream gate lacks any of the four, it is a context principle — record it, but the first executable downstream gate becomes primary, not the principle.
+3. **Missing gate** — name the specific gate at the earliest practical prevention point and any secondary gates. Pick from: design checkpoint / arch review / contract definition / schema ownership / capability model / unit test / integration/contract test / E2E / load/perf test / chaos test / security review / code review / launch checklist / canary / monitoring & reconciliation / runbook / on-call rotation / postmortem follow-through. If the gate already exists but did not fire, the bug is in the *gate's executable wording*, not in "we should add a gate."
+4. **Owning skill(s)** — map each gate to the skill(s) that own it (see routing table). Usually more than one skill; the `coordination_owner` field of the source-register row records which skill holds the canonical cross-skill invariant. Sibling-generalization mini-map still applies. Default owner resolver when no exact sibling exists: route by lifecycle, **stack-implementation last** — product-risk gates → architecture contract → testing strategy → release/rollout → observability → security → extraction workflow → stack-implementation. **Stack-first override:** when the prevention depends on language / framework / runtime / package-manager / build-tool semantics (e.g. Go `http.Response.Body` lifecycle, Python asyncio cancellation semantics, JVM classloader behavior, Rust borrow-checker pattern, Node event-loop starvation, Flutter rendering pipeline), route first to the affected stack `*-dev` or `*-architecture` skill — lifecycle owners (release/rollout, tests, observability) become secondary controls. Use lifecycle-first as the default, stack-first as the override; record which path was chosen and why.
+5. **Counterfactual replay** — write the new rule, then record in the provenance-to-target diff: incident class, the specific source signal the rule keys off, target file/line, gate name, the observable check an agent will run, and whether the new rule would have blocked the incident at that gate before the consequence. If any field is generic, the rule is not yet executable; tighten or downgrade to `working hypothesis` until a second incident or independent evidence confirms it.
+
+## Routing table — incident class → likely owning skills
+
+Owners are exact skill names. An incident with hybrid causes maps to a **coordinated owner set** (one extraction touches every owner in the row), not to multiple independent table rows.
+
+| Incident class | First-pass owners (coordinated set) | Common second owners |
+| --- | --- | --- |
+| Production outage from deploy | `platform-release-engineering` + `platform-observability` (detection lag) | the affected stack skill (`go-microservice-architecture` / `python-service-architecture` / `web-react-dev` / `app-cross-platform-dev`) only for service-internal architecture rules |
+| Data corruption / write loss | the affected `*-architecture` skill (contract / idempotency / ordering / schema ownership) + `testing-strategy` (contract & duplicate-delivery tests) | `platform-release-engineering` (migration & runbook); `platform-observability` (reconciliation) |
+| Security event | installed security owner (`cso` if present; no dedicated security skill exists in this repo — otherwise `feature-risk-router` security-review gate) + the affected `*-dev` skill (input validation / auth / capability model) + the affected `*-architecture` skill (trust boundary) | `platform-release-engineering` (secrets handling) |
+| Perf regression in prod — pure runtime/capacity | `platform-observability` (SLI/SLO) + the affected `*-architecture` skill (capacity / quota) | `testing-strategy` (load) |
+| Perf regression caused by deploy / config / build / asset change | `platform-release-engineering` + `web-react-dev` / `app-cross-platform-dev` (build & runtime assets) | `platform-observability` (detection); `testing-strategy` (deploy-bound perf checks) |
+| Schema / data migration or version-skew caused by deploy or config rollout | `platform-release-engineering` (rollout ordering & rollback) + the affected `*-architecture` skill (schema compatibility) + `testing-strategy` (migration & version-skew tests) | `platform-observability` (reconciliation & skew detection); the affected stack `*-dev` skill (implementation mechanics) |
+| Feature-flag default change / config rollout causing segmented failure | `platform-release-engineering` (flag rollout & default-change discipline) + the affected `*-architecture` skill (flag-gated invariant) | `platform-observability` (per-segment detection); `testing-strategy` (flag-state tests) |
+| Deploy / rollback failure | `platform-release-engineering` + `platform-service-connectivity` (traffic) | `platform-observability` (deploy markers); the affected stack skill if the failure was stack-specific |
+| External dependency / async callback / probabilistic failure | `platform-observability` + `platform-service-connectivity` (reconciliation & repair) | the affected `*-architecture` skill (boundary contract) |
+| Recurring regression across services | `skill-extraction-workflow` (the extraction or routing rule that allowed it) + the shared `*-architecture` skill that owns the contract | per-stack `*-dev` skill only if the rule is genuinely stack-specific |
+| Near-miss caught by human | the gate that should have been automatic at the earliest practical prevention point (route per the table above) | `platform-observability` if detection was the gap |
+| User error producing real harm | `product-ui-ux-design` (state design / confirmation / undo) + `web-react-dev` / `app-cross-platform-dev` (implementation) | `testing-strategy` (interaction & dangerous-action tests) |
+
+### No-owner decision rule
+
+If no owner in the table fits the candidate rule, apply this single decision rule (replacing earlier conflicting guidance):
+
+- The prevention is **runtime-enforceable only** (code / config / test / monitor / runbook with no agent-decision content) → land it there, not as a skill edit.
+- The prevention is an **extraction, review, routing, or agent-decision guardrail** (a future agent must remember to check or decide something) → route to `skill-extraction-workflow`.
+- Otherwise → **block landing until an owner is named.** Do not orphan the rule in a stack skill it does not belong to.
+
+## Anti-patterns
+
+Block these before landing:
+
+- **Overfit to the incident** — "always check column `foo` before deploy of service `bar`" is procedural; the rule should be "stateful components require an idempotency contract verified by a contract test before launch."
+- **Procedural patch as rule** — what the on-call did during the incident is not the durable rule. The durable rule is what the next agent must do BEFORE the incident can happen again.
+- **Single-incident threshold inflation** — one outage caused by a 99th-percentile event does not justify a guardrail that blocks the common path. Calibrate the rule's strictness to the failure class's likely recurrence and blast radius. **Carve-out (evidentiary, not categorical):** irreversible data loss, security boundary bypass, money movement, public or destructive admin action, or compliance exposure can override recurrence calibration — but only when the extraction records all of: (a) the specific category, (b) evidence that repair is impossible or hard (no clean rollback, no idempotent retry, no compensating action, regulator notification required), (c) blast radius (population affected, blast scope), (d) the **narrowest workflow** that triggers the gate (the strict rule applies only to that workflow, not to all admin/security/money paths), and (e) the gate scope (what action it actually blocks). Without that row, fall back to recurrence × blast-radius calibration. The carve-out is not a category badge; it is a contract.
+- **Missing-gate misattribution** — saying "we needed a code review" when the diff was reviewed; the real miss was that the reviewer did not have a checklist item for the failure class. Fix the checklist, not the abstract gate.
+- **Sibling miss** — landing the rule only in the stack/service where the incident happened, when the failure class clearly applies to siblings. Run the sibling-generalization mini-map and the default owner resolver (lifecycle first, stack last).
+- **Lessons-learned dump** — copying the postmortem's "lessons learned" section verbatim into a skill. Postmortem lessons are often advisory; skill rules must be executable. Translate each lesson into an observable checkpoint, decision rule, or acceptance criterion.
+- **Passive alerting as the only rule** — adding a dashboard or alert as the sole rule when a preventive gate is available. For incidents where preventive gates exist (contract / test / review / canary), monitoring is secondary. (See exception in the next bullet.)
+- **Skipping the counterfactual replay** — if the provenance-to-target diff cannot name a specific observable signal the rule keys off, do not land it.
+- **Naming the incident in the rule body** — rule text must not contain the customer name, real ticket id, real date, real service name, real on-call name. These go in provenance only.
+
+### When monitoring / reconciliation **is** the primary rule
+
+For failure classes where prevention is genuinely not available at gate time — external dependencies (vendor APIs, third-party webhooks), async / eventually-consistent callbacks, fraud and anomaly detection, data reconciliation against an external source of truth, probabilistic failures, failures only observable after the fact — monitoring or reconciliation may be the **primary** rule. "External dependency" alone is not the justification — many external failures (duplicate webhook delivery, payload-shape changes, vendor 5xx storms) can still be prevented at the **local boundary**.
+
+**Prevention-disqualification checklist (required before monitoring may be primary).** For each applicable local preventive gate, mark whether it is available; monitoring becomes primary only when every applicable gate is `unavailable` with evidence:
+
+- Boundary contract — can we constrain the request/response schema at our edge?
+- Idempotency / deduplication — can we dedupe inbound or outbound requests?
+- Timeout / retry / backoff policy — can we bound vendor latency and retries?
+- Capability / auth validation — can we verify the caller's authority before acting?
+- Contract / replay test — can we exercise the failure shape in CI?
+- Canary / staged rollout — can we ship the change to a slice first?
+
+If any gate is **available**, it is the primary rule; monitoring is a secondary control. When monitoring is primary:
+
+- Name the specific signal and the threshold (not "watch for errors").
+- Pair it with an **executable repair or escalation path** (compensating action, retry policy, rollback trigger, on-call runbook step). Detection without action is not a primary rule.
+- Record the disqualification checklist outcomes inline, so a future reviewer does not mistake this for a procedural patch.
+
+## Counterfactual verification (recorded in provenance-to-target diff)
+
+Before landing the rule, record in the provenance-to-target diff a row with these required fields:
+
+- `incident_class` — one phrase, sanitized.
+- `source_signal` — the specific observable feature an agent will look for (a code shape, a contract field, a test name, a release-gate item).
+- `target_file_line` — where the new rule lands.
+- `gate_name` — the gate from step 3 above.
+- `observable_check` — the executable check an agent following the skill will run.
+- `would_have_blocked` — `yes` / `no` / `partial`, with a one-line justification tracing source_signal → gate → consequence.
+
+These additional fields are **required when applicable** (omit only if the incident genuinely had no such dimension; under-specifying a real dimension makes the rule look executable while hiding where the signal must be checked):
+
+- `affected_surface` — the specific page, endpoint, queue, table, or interface the rule applies to.
+- `change_vector` — what introduced the bad state (code change, deploy, config flip, schema migration, data import, vendor change).
+- `scope_segment` — which population, tenant, locale, or device class is affected (when the failure is segmented).
+- `rollout_phase` — canary / partial / fully rolled out / post-release (when the failure depends on rollout stage).
+- `control_plane` — the surface where the rule actually gates (feature-flag system, IaC pipeline, deploy gate, contract schema, CI step).
+- `secondary_control_gap` — which secondary controls also failed to catch this (defense-in-depth audit).
+
+If any required field is generic, the rule is not executable; downgrade to `working hypothesis` and do not promote until confirmed.
+
+## Sanitization additions for incident sources
+
+Incident sources carry PII and sensitive operational detail beyond the standard sanitization set. These categories **extend** the main R0 audit categories defined in `SKILL.md`; they do not replace them. The shared file carries only the category list — the per-project scan patterns and allow-lists live in the project's private alias map (`audit_cmd`) per the parent R0 rule.
+
+Categories the incident-commit audit must zero out:
+
+- Severity / priority / response tier labels embedded as literals (sev-N, P0–P3, response-level tokens) — keep only sanitized placeholders in shared text.
+- Specific calendar dates tied to a known event (ISO date, deploy week / quarter labels with year).
+- Ticket / Jira / Linear / Asana / GitHub Issues incident ids; postmortem document handles or numbers.
+- Vendor and observability tooling hostnames and URLs (PagerDuty, Opsgenie, Datadog, Sentry, Grafana, Kibana, Splunk, New Relic, Honeycomb, plus internal mirrors).
+- Customer / tenant / org names and any customer-shaped or employee-shaped identifier (`user_id`, `employee_id`, `tenant_id`, `org_id`, `account_id`, `openid`, `unionid`).
+- On-call / responder / reviewer real names; team Slack / Lark / Teams channel names that carry product or domain identity.
+- Email addresses, phone numbers, IP addresses (v4 and v6), MAC addresses, postal addresses.
+- Auth material: `Authorization` / `Cookie` / `Set-Cookie` / `X-Api-Key` headers and their values; bearer JWTs (`eyJ…` shape); API key shapes; OAuth `access_token`/`refresh_token` query params; session ids.
+- Cloud storage locators: presigned URLs and their query parameters (`X-Amz-*`, `signature=`, `expires=`), real bucket / object names, container / blob names, GCS / S3 / OSS paths.
+- Internal hostnames, dashboard URLs with real paths, alert rule names, runbook paths.
+- Real error messages that embed identifiers / paths / tokens — quote only the generic shape (`"<resource> not found at <path>"`).
+- Structured-log PII field values — even when the *field name* is generic, the *value* may carry PII; strip the value.
+- Real CVE numbers when the rule is generic — link in provenance only, not in the rule body.
+- Regulated identifiers: payment card numbers (PAN, CVV, expiry), bank account / IBAN / routing numbers, government-issued ids (passport, national id, tax id, SSN-shape), driver license, vehicle id (VIN), insurance / policy numbers.
+- Health and legal content: medical record fragments, diagnosis codes (ICD/CPT), prescription / medication detail, legal case identifiers, contract-protected content.
+- Unstructured user-supplied content from the incident: free-form user messages, uploaded document text or OCR extractions, support transcripts, chat logs, call transcripts.
+- LLM / AI surfaces: prompts and responses captured from production, model debugging traces with user content, tool-call arguments containing user data, embedding-input dumps. Redact even when the model run is sanitized in product logs — incident artifacts often include the raw payload.
+
+The actual grep patterns, per-category regex, and per-project allow-lists for these categories live in the project's `audit_cmd` in the private alias map. Maintainers extending this audit set must add the corresponding patterns there.
+
+## Quickstart adaptation
+
+When the extraction is incident-driven, the main `extraction-quickstart.md` flow gets these per-step adjustments:
+
+- **Charter** — name the failure class and the future incident this extraction prevents (not "incident on date X"). Record blast radius and recurrence likelihood explicitly so a future reader can calibrate strictness; record carve-out applicability (irreversible / security / money / compliance) when relevant.
+- **Source register** — extended standard row above; include the postmortem doc, the fix diff, and the detection evidence as separate inspectable artifacts with `min_depth`/`actual_depth` set.
+- **Batch** — for multi-contributor postmortems, batch by failure class, not by section of the doc. One class can produce rules in multiple owning skills.
+- **Sibling mini-map** — required even for "single service" incidents; most failure classes generalize across stacks more than the incident narrative implies. Apply the default owner resolver above.
+- **Dual-track review** — the challenge pass must specifically attack the rule with: "what's the simplest variant of this incident that still slips past the new rule?" If it finds one, the rule is under-specified.
+- **Counterfactual** — recorded per landed rule in the provenance-to-target diff, before commit.
+
+## Failure modes (specific to this layer)
+
+- **Postmortem-as-novel** — extracting every paragraph as a rule. Postmortems are mostly narrative; only the controllable causal points become rules.
+- **One incident, many rules** — fine if each rule maps to a distinct failure class with its own counterfactual. Suspicious if all rules trace to the same root cause; consolidate.
+- **Long-tail incidents driving common-path rules** — heavy guardrails added because of a once-in-three-years event. Calibrate to recurrence × blast radius — except for the irreversible/security/money/compliance carve-outs, where one incident is enough.
+- **Detection-only fixes treated as primary when prevention exists** — adding alerts/dashboards as the rule when a real preventive gate (contract / test / review / canary) was available. Acceptable as a *secondary* rule (defense in depth). For external/async/probabilistic classes where prevention is unavailable, monitoring + repair path may be primary — see the carve-out above.
+- **Cross-team rule landing without owner** — incidents often span teams; apply the no-owner decision rule (runtime → code/config; agent-decision → `skill-extraction-workflow`; otherwise block). Do not orphan the rule in a stack skill it does not belong to.
+- **Stopping at the first controllable layer** — landing only the test or review rule when the contract / schema / capability owner is the real earliest practical prevention point. Continue the chain; list later layers as secondary controls.
+- **Re-extracting the same incident twice** — happens when the first extraction landed only the procedural patch. Treat the second pass as a failure-class extraction, supersede the procedural rule, and record why the first pass was insufficient.
+
+## What gets committed
+
+A successful incident extraction usually produces, in one commit or a tight series:
+
+- 1–3 new or sharpened lines in each owning skill's executable workflow (the coordinated owner set may produce small landings in multiple skills).
+- Optionally, a new entry in the `recurring-anti-patterns-checklist.md` if the failure class has now appeared in 2+ skills/services.
+- A provenance-to-target diff row (with the counterfactual fields above) recorded in the maintainer's working artifacts.
+- A provenance note in the private alias map linking the sanitized rule to the incident's real id/date/team and the per-category audit patterns — never in the shared skill tree.
+- Zero copies of the postmortem narrative in the skill files.
+
+If the commit contains no executable rule (only narrative or only passive alerting where prevention is available), do not land it as an extraction; route to runtime config or to a runbook instead.

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/l0-l1-l2-routing.md

@@ -0,0 +1,114 @@
+# L0 / L1 / L2 Routing — Risk-Tiered Extraction Paths
+
+Phase 1 material for the risk-tiered extraction model (design source: `docs/skill-extraction-optimization-design.md`). This reference defines the **five-step analysis front door** and the **three landing paths** (L0 / L1 / L2). It does NOT weaken any existing gate: R0, dual-track review, provenance isolation, the routing analyzer, and `check-ccl-skills.sh` stay exactly as the Core Rules define them. The tiers only decide *gate strength*, never *gate existence*.
+
+## L0 / L1 / L2 is a risk VIEW over the canonical gates, not a second gate set
+
+The tiers are a **risk-tier router** onto the canonical dual-track / shared-skill gates — a way to read "how strong must the gates be for this change", never a parallel or competing set of canonical rules. The canonical definitions (what `wording-only` means, when challenge may be skipped, what independent review and behavioral evidence require) live in `dual-track-review-gate.md`; this file points at them and must not restate or fork them.
+
+| Tier | Canonical classification it maps to | Canonical gate owner |
+|---|---|---|
+| L0 | Not a shared-skill landing (private scratch / route / backlog only); never lands skill content | n/a — leaves the shared tree, so no canonical gate runs |
+| L1 | Non-wording, non-routing shared-skill change | `dual-track-review-gate.md` (review required; challenge + behavioral evidence required for any non-wording change) |
+| L2 | High-risk shared-skill change (routing surface, R0, authorization, validation standard, user sovereignty, cross-owner gate, eval runner/task-bank) | `dual-track-review-gate.md` + routing analyzer (`eval-routing.md`); same mandatory gates plus behavioral regression |
+
+The wording-only / challenge-skip question is owned in ONE place — `dual-track-review-gate.md`'s canonical wording-only criterion + deterministic scope check. The tiers never define their own skip path.
+
+## Five-step analysis (五步分析法) — the prerequisite, not a substitute for the tiers
+
+L0 / L1 / L2 answer "which path", not "did I analyze". Run the five steps FIRST; the tier is the output of step 4, and step 5 must be written back to closeout.
+
+| Step | Question it must answer | Primary output | Link to the gates |
+|---|---|---|---|
+| 1. 定义问题 (define the problem) | What failure / drift / recurring friction must this prevent? Is it even a skill/process problem? | problem statement + explicit non-goals | Decides whether to extract at all; an ordinary bug routes to `defect-diagnosis`, pure wording routes to `tighten-doc` |
+| 2. 收集证据 (collect evidence) | What is first-hand evidence vs second-hand judgment or model inference? | evidence card / source register | No first-hand evidence ⇒ no RCA; even L0 records the evidence gap |
+| 3. 归因抽象 (attribute & abstract) | What is the root cause? Can it abstract into a reusable pattern? Does an existing owner already cover it? | RCA + reusable pattern + owner map | Default to merge/route; do not promote a one-off event into a hard rule |
+| 4. 分层决策 (tier decision) | discard, route, L0 capture, L1 standard change, or L2 high-risk change? | L0/L1/L2 verdict + gate checklist | Sets the strength of R0, dual-track, behavioral evidence, routing eval; a failure-class reusable lesson cannot be demoted to an L0 backlog |
+| 5. 验证闭环 (close the verification loop) | How do we prove no leakage, no drift, and that agent behavior improves? | R0 result, review/challenge, behavioral cases, rule-budget note, closeout | Both doc-compliance and behavioral effect must be re-checkable; "review ok" alone is not closure |
+
+The tiers sit downstream of this: L0 is the lightweight result of steps 1–4 (not a landing proof); L1 enters the standard shared-skill change gates from step 4; L2 enters the high-risk gates from step 4; step 5 writes verification evidence back to closeout for later audit.
+
+## Path selection at a glance
+
+```
+experience / failure / retro / external benchmark
+        │
+        ▼
+   five-step analysis
+        │
+ reusable AND a skill/process problem?
+   │no                       │yes
+   ▼                         ▼
+ discard / route        evidence card / source register
+ to original owner            │
+                       L0 / L1 / L2 tier decision
+```
+
+## L0 — Capture Card / 轻量经验卡
+
+Use L0 when ALL hold:
+
+- a single small process lesson;
+- not yet sure it is worth a shared-skill change;
+- does NOT touch `description`, triggers, Skip, redirect, or any owner gate;
+- adds NO new hard rule;
+- no sensitive source text or real project detail would enter a shared document.
+
+**L0 is not a bypass channel.** Two hard limits:
+
+- **Storage**: an L0 evidence card lives ONLY in per-host scratch / a private alias. The moment a card or its conclusion enters `skills/**`, a skill reference, a loading instruction, or this repo's plugin behavior surface, it is no longer L0 — it must take the shared-skill gates (L1 or L2).
+- **Failure-class escalation**: a reusable lesson exposed by a *failure class* — routing miss, shallow retro, validation gap, wrong-ownership, missed gate — does NOT go to L0 `backlog`/`discard`. It MUST upgrade to L1/L2 and land at least one durable prevention point in this workflow or the owning target.
+
+An L0 verdict is exactly one of: `discard` (not reusable), `route` (back to the original owner), `backlog` (revisit once a second piece of evidence appears), `upgrade-to-L1/L2` (enter formal extraction). L0 never claims "the skill is fixed" — it only captures and routes.
+
+## L1 — Standard Skill Change / 标准技能变更
+
+Use L1 for a non-routing, non-wording shared-skill change: add/modify a reference; add a template, checklist, or rubric; clarify one skill's internal process — without changing the routing surface or the user-authority boundary.
+
+Any shared-skill landing — L1 or L2 — must clear the **three mandatory gates the Core Rules own**. A tier is never a lighter version of them:
+
+- **R0 zero-hit leakage audit** — the automatic `audit_cmd`, zero hits across every leakage category (`references/r0-leakage-audit.md`). A sanitize/grep pass is *input* to R0, never a substitute for it; an informal sanitize does not satisfy R0.
+- **dual-track review** — independent review + adversarial challenge (`references/dual-track-review-gate.md`).
+- **provenance / lifecycle isolation** — project provenance stays in per-host scratch / private alias; the shared tree (incl. commit / branch / MR record) carries only label-based capability rules (`references/extraction-lifecycle-handoff.md`).
+
+L1 then adds:
+
+- charter;
+- an evidence card or a short source-register table;
+- sibling-map / owner-map (incl. the impact-chain row when an upstream-owner skill changes);
+- a **behavioral-evidence row** — defer the exact status model to `references/dual-track-review-gate.md`;
+- a closeout validation row recording each gate / track's command, result, and disposition;
+- `check-ccl-skills.sh` + `git diff --check`.
+
+**No-downgrade rule.** L1 is the path for non-wording shared-skill changes; it is NOT a shortcut that lowers existing gates. Every shared-skill landing keeps the **independent review row**, and a non-wording-only change always requires **challenge + the behavioral-evidence row** — those cannot be dropped. Whether an edit qualifies as `wording-only` (and may therefore skip challenge) is decided **only** by the canonical wording-only criterion + deterministic scope check in `references/dual-track-review-gate.md`; this file does not restate or fork those conditions. The author may not self-certify the classification, and an LLM independent review is hypothesis-grade, not a verdict (`references/review-rubric.md`), so review alone never downgrades a change to wording-only. The conclusion carried here: if the canonical deterministic scope check cannot prove the edit is purely typo / grammar / formatting / synonym with no meaning change, challenge stays required, and any reviewer-flagged or unconfirmed meaning / scope / trigger / routing / validation / acceptance change re-arms challenge + the behavioral-evidence row.
+
+Escalate L1 → L2 whenever the change touches a routing surface, R0, authorization, the validation standard, user sovereignty, a cross-owner gate, or the eval runner / task-bank.
+
+## L2 — High-Risk Route / 高风险变更
+
+Use L2 when the change touches any of:
+
+- `description`, triggers, `Use when`, `Skip`, redirects;
+- bootstrap / owner routing;
+- R0, sanitization, provenance, user authorization, merge policy, or a verification gate;
+- default development behavior or a cross-skill lifecycle gate;
+- the eval runner / task-bank / routing-decision logic.
+
+L2 inherits the **three mandatory gates** above (R0 zero-hit audit, dual-track review, provenance / lifecycle isolation) — automatic R0 is the landing gate for **any** shared-skill landing, not an L2-only step. When the automatic R0 command is unavailable, the landing records the result as `inconclusive` / `manual-only residual risk` and treats the manual fallback as NOT an R0 pass (`references/r0-leakage-audit.md`); L2 additionally records that residual risk explicitly at closeout. On top of the mandatory gates, L2 adds:
+
+- a full charter;
+- full provenance / source register;
+- sibling-map / impact-chain;
+- **behavioral regression** — at least one should-trigger AND one should-not-trigger case; this is the L2 routing / behavioral-regression minimum, and the exact status model is deferred to `references/dual-track-review-gate.md`;
+- the **Tier-1 routing analyzer** when a routing surface is touched (`references/eval-routing.md`);
+- closeout recording findings, disposition, and residual risk.
+
+For L2, a clean LLM review is not sufficient on its own — the mandatory gates, deterministic checks, and behavioral regression must also pass (see `references/review-rubric.md`).
+
+## Anti-misuse guardrails
+
+| Risk | Guardrail |
+|---|---|
+| Tiers misused to downgrade a gate | Touching routing / R0 / authorization / validation standard forces L2; L1's no-downgrade rule keeps challenge + behavioral evidence required on any meaning change |
+| L0 becomes an unverified conclusion | L0 may only `capture` / `route` / `backlog` / `upgrade`, never claim landed; failure-class lessons cannot stay at L0 |
+| Tiers replace analysis | The five-step analysis is the front door for every path; the tier only sets gate strength, it does not replace problem definition, evidence, RCA, or the verification loop |

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/online-skill-review.md

@@ -0,0 +1,47 @@
+# Online Skill Review
+
+Use this when borrowing methods from public skill repositories, registries, articles, or reports.
+
+## What To Borrow
+
+- Loading and structure methods: trigger-focused frontmatter, progressive disclosure, direct references, minimal root files.
+- Validation methods: pressure scenarios, independent review, YAML/schema validation, reference-link checks, trigger-boundary checks.
+- Quality methods: concise SKILL.md, lazy-loaded references, deterministic scripts, clear owner/routing boundaries, tiered validation profiles, and doc-contract tests that assert required trigger wording and forbidden leakage.
+- Safety methods: inspect before installing, avoid untrusted executable scripts, check for prompt injection, secrets, unexpected root files, and repo-context mismatch.
+
+## What Not To Borrow
+
+- Marketplace claims, install-count rankings, star counts, or marketing copy as quality evidence.
+- Tool-specific commands when a portable principle is enough.
+- Large copied reference dumps, raw benchmark logs, lockfiles, build artifacts, or root-level clutter.
+- Hidden business assumptions, credentials, personal paths, or source-specific role names.
+- Persona simulation, voice mimicry, personal-data collection, or identity reconstruction when the target skill is a workflow, design, product, engineering, or review skill.
+- Mandatory generated manifests, multi-artifact bundles, or auto-install defaults from generator-style repos unless the local skill is also generator-owned and the user explicitly wants that behavior.
+
+## Review Checklist
+
+- Does the skill description say when to use it, not merely what it does?
+- Does the skill entrypoint stay concise while references hold detailed variants?
+- Are responsibilities disjoint from sibling skills?
+- Are scripts optional, focused, and safe to inspect?
+- Would OpenCode, Codex, and Claude Code discover and use the skill from name/description?
+- Is the source reputable enough, or should the idea be treated as inspiration only?
+- Does the source distinguish real inspected evidence from marketing claims, search results, placeholder links, or fabricated examples?
+
+## Public-Method Triage (Coverage-First + Bounded Change)
+
+Use this when the user asks to "extract / check / borrow industry best practices for X" — a different shape from local-source extraction. The recurring failure is to absorb every named idea found online and bloat the target skill into a literature catalog.
+
+- **Coverage-first grep before reading**: build a candidate-term list for the target domain (frameworks, methodologies, vendors, named patterns) and grep across the target skill + its references. For each candidate, classify as `new gap`, `hidden coverage` (already covered under different wording), `wrong owner` (route to another skill), or `discard` (not in scope). Do not read public sources deeply on hits classified `hidden coverage` / `wrong owner`.
+- **Five-bucket triage of remaining candidates**: `mature mainstream` (industry-default, executable, add if missing) / `niche-but-recommendable` (real value in a narrow context, add with adoption condition) / `overhyped` (cite-on-blog ≠ change-execution-judgment, do not add) / `wrong-skill` (real but owned elsewhere, route) / `hidden coverage` (already in target under different wording, do not add). Land only `mature` and qualified `niche` buckets.
+- **Adversarial framing for the triage consult**: when consulting a second model for the triage, explicitly ask it to challenge what is hype vs what is industry-standard the target skill is missing — symmetric framing produces back-patting; adversarial framing produces sharper buckets.
+- **Diff budget by extraction shape**: a literature-triage update normally lands ≤10–15 executable lines across existing references; a target skill already classified as thick (entrypoint ≥150 lines, refs ≥10) tightens to ≤10 lines and routes overflow to a `prune` task instead of new content. **Track the prune task durably, not in commit-body prose**: record it as a `pending` row in the current commit's target-output map AND append a one-line entry to the per-host scratch backlog (`~/.<host>/skills/.extraction-work/pending-prunes.md` or equivalent) naming the target file, the structural finding (e.g. "SKILL.md entrypoint exceeds its own thinness rule"), and the proposing reviewer. Findings buried in commit-message paragraphs disappear by the next session.
+- **Zero new files unless trigger/owner/workflow differs**: per the existing core rule, fold into the smallest existing reference; resist the "new ref per topic" instinct that turns each public-method scan into a parallel knowledge base.
+- **Fact-precision adversarial round on landed text**: industry literature carries version numbers, API names, enforcement strength, and dated deprecations — the dual-track adversarial review for a literature-triage commit MUST verify these explicitly (per-platform version cutoffs, exact API surface, "MUST vs SHOULD" enforcement, regulatory effective dates) before convergence; this is a higher bar than internal-evidence extractions, where the source artifact carries the facts. **Primary-source verification is agent-side**: "verify" means the agent runs `WebFetch` / `WebSearch` (or equivalent direct retrieval tool) on the official docs / standards page / API reference URL and reads the actual text — NOT just trusting a consultant model's (codex / external review LLM) URL citation. Consultant-LLM URL citations are second-tier evidence: they may be hallucinated, stale, or paraphrased inaccurately. For load-bearing facts (version cutoffs, current-vs-deprecated status, exact API behavior, regulatory effective dates, MUST/SHOULD enforcement strength, panel / API name spellings), the agent MUST hit the primary source directly during the fact-precision round, even when the consult round provided URLs. Recording "codex cited X" without independent fetch is insufficient — per the attribution-verification rule's source-quality bar, two independent sources are required, and codex + (codex's cited URL unverified) is only ONE source.
+- **Skill description / references / scripts / validator output are public API**: changes to trigger semantics, sibling routing, named rules, or validator output break callers in the same way a public API change does — record breaking changes explicitly and verify no sibling skill silently depends on the prior surface.
+
+## Source Handling
+
+Record links in analysis or commit notes when public sources influenced a change. Do not paste long external text into skills. Rephrase into local rules and keep the final skill independent of the source site.
+
+Never invent URLs, quotes, install results, test output, or source coverage just to make a borrowed method look validated. Keep the honest gap visible.

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/parallel-stack-references-pattern.md

@@ -0,0 +1,164 @@
+# Parallel Stack-Specific References (Sibling-Sync Pattern)
+
+Use when extracting a body of architecture knowledge that has a substantial **stack-agnostic core** but renders differently in each stack (Go vs Python service architecture, web vs mobile client work, etc.). Two parallel references — one under each stack-skill — with an explicit sibling-sync invariant and an enforceable grep gate.
+
+This pattern was developed across two extractions with complementary coverage, and a third (data-platform) was authored from scratch using the pattern. The event-driven architecture extraction (`<arch>/references/event-driven-architecture.md` Go + Python pair) ran 2 rounds of dual-track, P0 dropping 5 → 0 by R2, and validated the parallel-file layout, H2 parity, and sibling-mirroring discipline; it was originally landed without an in-file gate and subsequently retrofitted (ops checklist moved to mirrored core, mirrored stack-syntax genericized, embedded grep-gate added at end of stack-glue). The multi-tenant isolation extraction (`<arch>/references/multi-tenant-isolation.md` Go + Python pair) ran 4 rounds and validated the full R1 → R4 trajectory (R1 = missing gates → R2 = composition → R3 = propagation → R4 = scope/degradation) plus the embedded grep-gate, the `## Topic-extension backlog` H2, and the convergence-on-non-zero-floor signal — its P0 stabilized at a non-zero floor of 2 (a historical trajectory from before the current three-round Agent budget; residual findings now route through `dual-track-review-gate.md`'s post-budget human checkpoint). The data-platform extraction (`<arch>/references/data-platform-architecture.md` Go + Python pair) was authored fresh using the multi-tenant template shape; dual-track history begins at its first R1 round. All three pairs now have embedded grep-gate subsections.
+
+## When this pattern applies
+
+Apply when:
+- the knowledge body has 10+ stack-agnostic concepts (delivery semantics, idempotency design, schema evolution, etc.) plus stack-specific implementation glue,
+- both stack skills (Go arch, Python arch) have callers who will route in from their own skill, and forcing one stack to route to the other's reference creates an awkward Go-first or Python-first asymmetry,
+- the stack-glue is genuinely distinct (different library choices, different runtime mechanics) and meaningful in its own right — not just a thin wrapper.
+
+Skip when:
+- the knowledge is purely architectural with no stack-specific glue worth writing twice (route to a single shared file under one skill; the other stack routes to it),
+- the body is small enough (< 80 lines) that one file with a "Go" and a "Python" subsection works.
+
+For 3+ stacks (Go + Python + Java + Node + ...), the choice is a real decision, not a categorical skip:
+- *Per-stack siblings still apply* when each stack has substantial distinct glue (Go context propagation vs Python contextvars vs Java thread-local-with-reactor-context vs Node async-hooks) AND each stack has its own callers who route in from their own skill. Three or four sibling files with the same mirrored core and the same grep gate are sustainable; the sibling-sync invariant scales linearly.
+- *A separate shared skill* makes more sense when stack glue is thin (the architecture is mostly stack-agnostic with brief library notes per stack) OR callers do not naturally route from a single-stack skill (an architect designing a polyglot system reads one shared reference and follows links into stack skills for implementation).
+- Choose by the same criteria as 2-stack: each stack having real callers + substantial glue → siblings; thin glue or non-stack-specific callers → shared skill. Do not skip parallel siblings just because N is larger.
+
+## File layout
+
+Each stack skill gets its own reference:
+
+```
+<stack-1>/references/<topic>.md       # e.g., go-microservice-architecture/references/event-driven-architecture.md
+<stack-2>/references/<topic>.md       # e.g., python-service-architecture/references/event-driven-architecture.md
+```
+
+Routing line in each stack's `SKILL.md` points to its own reference and **names the sibling-sync invariant explicitly** ("Stack-agnostic core sections mirror the sibling `<other-stack>/references/<topic>.md`; maintainers updating those sections must update both files in the same change").
+
+## File structure (each file mirrors)
+
+Each file has the same H2 structure. The **stack-specific implementation patterns** H2 is the last divergent section (it differs by stack). The **only allowed mirrored H2 after stack-glue** is an optional `## Topic-extension backlog` — both files include it with identical or near-identical wording, and it is part of mirrored content even though it sits after the stack-glue H2. **No other mirrored H2 is allowed in the post-stack-glue region**: any new mirrored content (validation, extension evidence, follow-up rules) must be placed BEFORE the stack-glue H2 so the grep gate's awk command scans it. If a future maintainer needs a post-stack-glue mirrored section other than Topic-extension backlog, the gate's awk command must be extended to cover it (and the methodology updated to allow that new section), not silently bypassed by placing arbitrary mirrored content after stack-glue. The grep gate's awk command stops at the stack-glue H2 and therefore does not scan the backlog section, which is what lets the backlog name specific external vendors / workflow engines / regulator regimes that mirrored-core content cannot. H2 count parity in the mirrored-core region is the first validation (a maintainer adding a mirrored-core section to one file must add it to the other).
+
+**H2 parity is scoped to the mirrored core, not to the whole file.** A stack may legitimately need a concept H2 that has no sibling equivalent — a Python file's "async cancellation and background-task lifetime" section captures architecture-level failure modes Go does not share; a Java file's "JVM-classloader-aware schema evolution" section captures runtime constraints absent from Go/Python. For those: place the stack-only concept as an H2 inside the *stack-specific implementation patterns* section (not in mirrored core), and have the sibling explicitly record a one-line "not applicable to this stack — <reason>" entry at the corresponding section, so the asymmetry is intentional and reviewable rather than a sync drift.
+
+1. **Header — sibling-sync invariant + sanitization boundary.**
+   - Sibling-sync: names the partner file, the rule that mirrored sections must update together, and points to the mirrored-section grep gate by section name. **Crucially: the header itself must NOT name the forbidden tokens** (doing so makes the gate's own regex match the header — review caught this in round 2 of the multi-tenant extraction). Refer to category classes only: "DB-engine-specific syntax, runtime/concurrency-mechanic names, library/framework API names." The concrete tokens live in the grep-gate subsection.
+   - Sanitization boundary: a positive audience list, not a negative one. "Internal" is not safety — internal documents get forwarded. The boundary covers: external/client-facing, customer-specific, regulator/auditor evidence, SOC/compliance reports, procurement responses, internal compliance reviews, sales-engineering or security-questionnaire appendices, partner architecture drafts, and anything that could be forwarded to those audiences.
+2. **When this applies / does not apply.** Same in both files.
+3. **Concept sections (10–15 H2s).** Stack-agnostic. Same content, same wording where possible (intentional duplication; the cost of duplication is less than the cost of cross-file routing for callers).
+4. **Anti-patterns.** Same in both files.
+5. **Operations checklist.** Same in both files. Each item is a verifiable action ("synthetic over-quota test for each quota," not "quotas tested"), not an acceptance statement.
+6. **Stack-specific implementation patterns.** Diverges. Same H2 heading shape; same number of bullet items per stack where possible; only the body content is stack-localized.
+7. **Mirrored-section grep gate (subsection of stack-glue).** Defined below.
+
+## The sibling-sync invariant — what mirrors, what diverges
+
+Mirrored sections must match in **meaning**, not necessarily in punctuation. The acceptable divergences, enumerated:
+
+- **Routing references** — Go's "route to `api-security-boundaries.md`" vs Python's "route to `web-framework-boundaries.md`" is fine; each stack's reference tree differs. This is the **one allowed mirrored-section divergence** and is explicitly stated in the sibling-sync header.
+- **Examples that name the stack** — when a mirrored section names a generic example, it can use a stack-neutral placeholder ("the session-level tenant variable") and let the stack-glue section name the specific syntax.
+- **Length differences from stack-neutral phrasing** — Go-rendered and Python-rendered phrasings of the same concept can differ in length by a few words.
+
+Hard constraints that must NOT diverge:
+- **Concept set** — every rule, every gate, every carve-out present in one mirrored section is present in the other.
+- **Anti-pattern list** — same list, same ordering.
+- **Operations checklist items** — same items, same verification criteria.
+- **Decision-rule conditions** — when one side says "do X if A and B and C", the other side says the same.
+
+## The mirrored-section grep gate (the meta-rule that prevents drift)
+
+The hardest rule to keep is: *stack-specific syntax must stay in stack-glue, not creep into mirrored sections*. Dual-track caught this regression in three separate rounds across two extractions. The fix is a physical gate in the file itself, not a verbal promise.
+
+Each file ends its stack-glue with a `### Mirrored-section grep gate` subsection that contains:
+
+- The **forbidden token categories** named: DB-engine syntax, runtime/concurrency mechanics, library/framework API names.
+- The **concrete token list** (typically 30–50 tokens covering the file's stack ecosystem). The list is the source of truth.
+- The **run command** (an `awk` to extract the mirrored region by stopping at the stack-glue H2, piped to `grep -nE` with the token list as the regex). The regex is generated *from* the token list and must match it exactly — token list changes require regenerating the regex. Word boundaries (`\b…\b`) are preserved to prevent false positives on substrings.
+- **The expected output:** zero hits. Any hit means a mirrored section has been polluted with stack syntax and must be moved to stack-glue.
+- **Allowed exceptions** — the *sibling sync* header itself names the category classes (without tokens, so the gate does not match its own description); the *sanitization boundary* header does not contain any tokens. No other exceptions; the gate runs on every commit.
+
+## The dual-track trajectory expected by this pattern
+
+Each parallel-stack extraction follows a predictable trajectory across dual-track rounds. Use it to calibrate: if your round-over-round results match this shape, you are converging; if they do not, something is wrong.
+
+| Round | What the round catches | Typical P0 count | Typical total |
+|---|---|---|---|
+| R1 | Missing primary gates (no schema-evolution rule, no idempotency design, no DLQ semantics, no tenant-context discipline). Big concept misses. | 3–5 | 15–20 |
+| R2 | Composition gaps between R1 gates (R1 added gates A and B; R2 catches that A bypasses B, or that B's failure mode invalidates A). | 3–5 | 10–15 |
+| R3 | Propagation gaps (the R1+R2 gates exist and compose, but information doesn't flow between them: a denylist that isn't ack'd, a generation that doesn't guarantee snapshot completeness). | 1–3 | 8–12 |
+| R4 | Scope/degradation gaps (the gates work as designed but don't handle edge audiences: external/runtime sources missed in dependency declarations, single-operator orgs that can't separate planes, runtime-created relations missed by enumeration). | 0–2 | 5–11 |
+
+If R3 still has P0 = 5 or R4 P0 > R3 P0, the topic is wider than this loop can close in the standard 4 rounds; route to topic-extension via the convergence rule in `dual-track-review-gate.md`. Don't try to brute-force more rounds.
+
+## Sibling-sync verification checklist (run before every commit that touches mirrored content)
+
+- H2 parity in the mirrored core: `grep -c '^## '` from start of file to the `## <Stack>-specific implementation patterns` heading returns the same number on both files. Stack-only concept H2s under stack-glue are exempt; the sibling records a "not applicable — <reason>" entry for each.
+- Mirrored-section grep gate: `awk` + `grep -nE` from the stack-glue gate subsection returns zero hits on both files.
+- Grep-gate token-list parity, by subset:
+  - *Shared-DB tokens* (PostgreSQL keywords like `SET LOCAL`, `BYPASSRLS`, `FORCE ROW LEVEL SECURITY`, `set_config(`, etc., when both stacks use PostgreSQL) **must be identical** between siblings; a divergence is the bug. If the stacks use different DBs (Go on PostgreSQL, Python on MySQL), this subset's contents differ legitimately but the divergence must be documented in each file's gate-subsection preamble.
+  - *Foreign-stack leakage tokens* (Python tokens in the Go file's forbidden list, Go tokens in the Python file's forbidden list — the cross-stack tokens whose presence in mirrored sections would be the leakage) **must be symmetric**: the Go file forbids the Python-side leakage tokens and vice versa. A token forbidden in only one direction is a sync gap.
+  - *Own-stack implementation tokens* (each stack's own library / framework / runtime tokens — Go's `GORM`/`Hertz`/`Kitex`; Python's `SQLAlchemy`/`FastAPI`/`Pydantic`) **may diverge by stack** and need not match between siblings. Each file's reviewer verifies its own-stack token list is comprehensive; cross-file diffing is not required for this subset.
+  When adding a new token during a dual-track round, classify it into one of the three subsets and apply the corresponding rule.
+- Grep-gate regex matches its token list: extract every token from the list, build the regex line from those tokens with declared word boundaries preserved, and verify it equals the regex in the `Run` command block of that file. A token declared in the list but absent from the regex (or vice versa) is the bug.
+- Anti-pattern count parity: count of `- **<bold-anti-pattern>**` rows match.
+- Operations checklist count parity: count of checklist items match.
+- The header's sanitization boundary list matches between files; the audience list is positive (procurement / compliance / regulator / etc.), not negative ("not for external").
+- The routing-reference divergence is recorded in the sibling-sync invariant; no other divergences allowed.
+- **Semantic-parity gate** (manual; no regex substitute exists). The H2 count, anti-pattern count, checklist count, grep gate, and token-list parity checks all measure *structure and stack-syntax*; they do NOT catch semantic divergence within mirrored content. Two siblings can pass every measurable gate while one says "retry happens after commit" and the other says "retry happens inside the transaction" — no stack token is involved, so the gate is silent. Before commit, do a meaning-diff review of:
+  - **Mirrored core** — extract the same region from both siblings (e.g., `awk` to slice through the `## *-specific implementation patterns` H2), read side-by-side, focus on decision conditions, checklist criteria, ordering / sequencing words, carve-outs, and failure semantics.
+  - **Semantically-coupled stack-glue rows** — stack-glue is allowed to diverge by stack syntactically, but bullets that describe the same shared engine, protocol, or domain concept (DB engine advisory-lock primitives, broker-wire semantics, OS-level rate-limit primitives, etc.) must be semantically aligned across siblings. A Go-side bullet says "TiDB supports GET_LOCK cluster-wide" while the Python sibling silently says "GET_LOCK not available on TiDB" is the exact class of drift that all measurable gates miss but the topic does not allow.
+  Record the result in the commit note as a scoped, per-pair line: `semantic parity: pair=<fileA>↔<fileB>; mirrored-core reviewed; coupled stack-glue candidates=<changed-bullets-or-shared-concepts>; reviewed=<bullets-or-none>; none_reason=<why no changed stack-glue row maps to a sibling concept>; findings=<n>`. Required fields:
+  - `pair=...` — names the two parallel-stack sibling files reviewed. Mixed commits that touch a parallel pair AND a methodology-only file get one `semantic parity` line per pair plus an explicit `non-parallel files=<paths reviewed under separate rule>` line for the single-file changes (those have no sibling to mirror and cannot satisfy this gate; they are not silently rolled into the pair's `findings`).
+  - `coupled stack-glue candidates=...` — the inventory of changed stack-glue bullets in this commit OR the shared concepts they touch (DB engine, broker/protocol, external system, quota, lock, ordering, delivery semantics, idempotency, failure mode). `none` is invalid when any changed stack-glue row names a shared engine / protocol / external system / quota / lock / ordering / delivery / idempotency / failure-mode concept; in that case list the candidate even if you concluded after review that the bullets do not couple semantically.
+  - `reviewed=...` — the subset of candidates actually meaning-diffed; `none` is valid only when `candidates=none` is also true. `none_reason=...` is required when `reviewed=none` and is invalid as "no time" or "trivial change" — it must name why no changed bullet maps to a sibling concept.
+  - `findings=<n>` — zero is a valid record; the record is an assertion about the review, not a license to skip it.
+  This gate exists because a real failure of this exact class shipped in R7 — a TiDB clause was fixed in Go stack-glue but the Python sibling silently retained the old wording, passing all measurable gates while the meaning had drifted. R7's incident specifically involved stack-glue rows (not mirrored core); R8's first version of this gate covered only mirrored core, so the gate would not have caught the incident that motivated it; R9 extended it to coupled stack-glue rows; R10 added the candidate-inventory and `none_reason` requirements to prevent the gate's claim of `reviewed=none` from becoming a false-clean signal. The accumulating discipline is itself the evidence that "rule-added-in-round-N-incomplete-in-round-N+1" is a recurring class — see the methodology's own anti-pattern catalog.
+
+## Anti-patterns specific to this pattern
+
+- **Header self-violation** — the sibling-sync header lists the forbidden tokens by name, defeating the grep gate (the gate's own regex matches the header). The header names category classes only; tokens live in the grep-gate subsection.
+- **Stack-syntax creep into mirrored sections** — `SET LOCAL`, `BYPASSRLS`, `FORCE ROW LEVEL SECURITY`, `context.Context`, `contextvars`, `asyncio`, `GORM`, `SQLAlchemy`, `FastAPI`, `run_in_executor`, etc. in mirrored content. The grep gate catches this; treat any hit as a structural failure, not a wording polish.
+- **Mirrored-section regression after body strengthening** — strengthening the body without updating the operations checklist. The checklist must track every body strengthening; review catches this in 3+ findings on the round after a major body update. Build the checklist update into the same commit as the body change.
+- **One file edits, sibling doesn't** — even a sentence-level edit to a mirrored section must be applied to both files in the same commit. The sibling-sync invariant is a discipline, not a tool — git pre-commit hooks can grep for `^## ` count match but cannot enforce semantic parity.
+- **Stack-glue concepts hidden in mirrored sections** — saying "use the stack-glue section for the engine-specific syntax" in mirrored content is fine; saying "in PostgreSQL, use `pg_try_advisory_xact_lock`" in mirrored content is not. The first names the routing; the second is the syntax itself.
+- **Grep gate run command doesn't match declared token list** — review caught this on round 4 of multi-tenant: the gate declared 30+ tokens but the regex omitted half of them and dropped word boundaries declared as `\b…\b`. The regex must be **generated from** the token list and visibly match it; token list edits require regenerating the regex.
+- **Routing-reference forced to be identical** — Go's route to a Go-stack reference (`api-security-boundaries.md`) cannot be identical to Python's route to a Python-stack reference (`web-framework-boundaries.md`). Carve this out explicitly in the sibling-sync invariant; do not treat it as a sync failure.
+- **Cross-stack token leakage in stack-glue** — Python stack-glue mentioning `goroutine`, or Go stack-glue mentioning `contextvars`. The stack-glue is single-stack; the grep gate for each file forbids the OTHER stack's tokens in its own mirrored sections, not in its own stack-glue (where they would obviously belong if accurate). Cross-stack token in same-stack glue is a separate bug — usually a copy-paste from the wrong sibling.
+- **New gate landed without retroactive self-test against its motivating incident.** When adding a gate or rule to prevent class X, the gate's first version frequently misses class X's actual scope — observed across R8 (added Semantic-parity gate covering only mirrored core; missed R7's stack-glue incident), R9 (extended the gate but the first commit using it missed a coupled-row drift R10 then caught), and the general recurring pattern of "rule added in round N is incomplete in round N+1, gets fixed in round N+2, then introduces a new gap in round N+3." Mitigation: every new gate must record a **retroactive self-test** in its landing commit note, with `incident=<id-or-class>; expected_catch=<what the gate would flag>; result=<pass/fail>; gap=<if fail>` fields. A gate that records `result=fail` does not land until extended; a gate that lands without the self-test is treated as untested and the next round must add the self-test as part of its first finding.
+
+## When the pattern does NOT apply (audit findings from existing arch-reference pairs)
+
+The pattern targets parallel-stack references with a substantial stack-agnostic core. An audit of the existing Go-arch + Python-arch reference pairs (same-name files in both `go-microservice-architecture/references/` and `python-service-architecture/references/`) found three other shapes that look like sibling pairs but are NOT:
+
+- **One-sided stubs**: one stack's file is substantially more complete than the other (e.g., one is 130 lines / 7 H2 while the sibling is 35 lines / 3 H2). The thin side is not a mirror; it is an incomplete file. Treat as future work — either elevate the thin side to match, or document the asymmetry honestly in the file headers.
+- **Stack-specific architecture content with shared topic**: both files cover the same meta-topic (data modeling, redis usage, etc.) but the H2 sets diverge because the stack-specific architectural concerns genuinely differ (Go has GORM / sharding / migration-strategy concerns; Python has connection-pool / proxy-topology / read-replica / long-running-tx concerns). These are not mirrored pairs; they are stack-architectural views of the same domain. Do NOT force them into the gate shape; the content divergence is principled.
+- **Methodology templates with per-row stack divergence**: a file whose H2 structure is identical between stacks but whose content (typically a dimension table or a checklist) has stack-specific rows by design (e.g., a source-evidence-map where the dimensions table includes IDL/protobuf for Go and Pydantic/asyncio/AI-hosting/Packaging for Python). The H2 mirror is real; the gate is not, because the divergence is at the row level inside an H2, by design, and the gate would force the table to omit half its useful content. Skip the gate here.
+
+The pattern's grep gate applies only to files whose mirrored sections carry the same content with stack-specific *implementation tokens* relegated to a single stack-glue H2. Files with intentional per-row stack divergence inside mirrored H2s, or files where the stacks legitimately need different H2 sets, are out of scope.
+
+## Worked examples
+
+Two extractions used this pattern with complementary coverage; the artifacts live in the shared skill tree:
+
+- `go-microservice-architecture/references/event-driven-architecture.md` + `python-service-architecture/references/event-driven-architecture.md` — delivery semantics taxonomy, transactional outbox, schema evolution, saga, end-to-end exactly-once illusion. 15 H2 sections per file (14 mirrored-core + 1 stack-glue); **2 rounds of dual-track; final P0 = 0**. Originally landed without an in-file grep gate; subsequently retrofitted (operations checklist moved before stack-glue; mirrored-section stack-syntax genericized; `### Mirrored-section grep gate` added at the end of the stack-glue section). Now conforms to the pattern and may be used as a template for new parallel-stack extractions — preferred when the topic does not need a `## Topic-extension backlog` (i.e., expected to converge by R2 with P0 = 0).
+- `go-microservice-architecture/references/multi-tenant-isolation.md` + `python-service-architecture/references/multi-tenant-isolation.md` — placement decision tree (data × compute), engine-policy bypass governance, denylist propagation barriers, deletion modes, crypto-erasure conditions. 15 H2 sections per file (13 mirrored-core + 1 stack-glue + 1 topic-extension backlog); **4 rounds of dual-track (historical, pre-dating the current three-round Agent budget); final P0 = 2 (topic-wider-than-loop signal — residual findings now route through `dual-track-review-gate.md`'s post-budget human checkpoint)**. Demonstrates the full R1 → R4 trajectory, the embedded grep-gate subsection, and the convergence-on-non-zero-floor case. **This is the reference shape for non-zero-floor extractions** (topics expected to plateau with residual extension vectors after dual-track converges). Both files include the embedded grep-gate at the end of their stack-glue section followed by a `## Topic-extension backlog` H2 (mirrored between siblings) that names the residual extension vectors (their prior-round severity if relevant), the general-level rule that the final round put in place, the residual gap that remained, and the specific incident-driven evidence a future extension would need. The backlog is for vectors that the final round fixed at the general level but left as per-integration / per-store-class residuals; it does not name unresolved P0s (which are either fixed in-round or block the file from landing). **Do not add a convergence-derived Topic-extension backlog preemptively** — it is added only after a dual-track round leaves the file with accepted/deferred residuals; fresh extractions that have not yet converged have no convergence-derived backlog to write.
+
+**Exception — known design-deferred extension candidates may be recorded preemptively when the charter accepts them.** Some topics (security boundaries, compliance regimes, regulatory residency, RFP-sensitive vendor naming, jurisdiction-specific erasure acceptance) have residuals the team already knows cannot be closed generically at design time. Forcing dual-track to "discover" them is process distortion. For these, the file may include a `## Topic-extension backlog` H2 from the first commit. Each preemptive entry **must** include all five of the following fields (vague entries are not accepted; they would let "design-deferred" hide unresolved current-scope P0/P1 work):
+
+1. **Label** — the entry is explicitly tagged `not convergence-derived` (the methodology distinguishes this from convergence-derived entries that arrive later in the same backlog).
+2. **Charter anchor** — the specific charter section / decision id where the deferral was accepted (so a future maintainer can re-read the rationale at its source).
+3. **Exact deferred residual** — the named gap that is being deferred (not "vendor-specific behavior" but "regulator X's interpretation of erasure on cold storage in jurisdiction Y").
+4. **Why outside generic closure** — explicit statement of why the residual cannot be addressed at the generic level (per-integration / per-jurisdiction / per-regulator / per-vendor-contract / etc).
+5. **Owner + revisit trigger** — who owns the deferral and what concrete event (charter revisit, regulator clarification, vendor RFP outcome, etc.) would unblock extension.
+
+The carve-out is for genuine design-time acceptance, not a hatch to defer unresolved current-scope work. An entry missing any of the five fields is not a valid preemptive backlog entry; the work either belongs in current-scope (fix in the round) or has not been deferred (do not list).
+
+Normal dual-track still runs to validate the rest of the file. Convergence-derived residuals are appended to the same backlog when later rounds surface them, with the distinct `convergence-derived` label. The label distinction matters for future maintainers: convergence-derived residuals invite incident-driven extension when evidence appears; design-deferred residuals invite charter revisit when the deferral assumption changes.
+
+For a new parallel-stack extraction, choose the template by expected complexity: event-driven for topics expected to converge by R2 (no topic-extension backlog needed); multi-tenant for topics expected to retain residual extension vectors at convergence (the historical non-zero-floor case, now resolved at the post-budget human checkpoint). All three templates (event-driven, multi-tenant, data-platform) now adopt the grep gate; the gate cost is small (~30 lines per file) and the cost of skipping it is the residual drift seen in the pre-retrofit event-driven version. The `## Topic-extension backlog` H2 is added later for **convergence-derived** entries (only after dual-track convergence leaves residual extension vectors) — fresh extractions do not preemptively include convergence-derived backlog entries; preemptive **design-deferred** entries are allowed only under the charter exception above with all five required fields.
+
+## How to bootstrap a new parallel-stack extraction
+
+1. **Charter** — name both stacks in scope; declare the sibling-sync invariant and the grep-gate placement; declare the H2 structure and which H2 is the stack-glue.
+2. **Draft one stack first** — usually the more familiar one. Write all mirrored H2s + the stack-glue + the grep-gate subsection at the end.
+3. **Mirror to sibling** — copy the file; rewrite the stack-glue section for the other stack; rewrite the grep-gate token list for the other stack's tokens.
+4. **First grep-gate run** — typically catches 2–5 cross-stack tokens that snuck into mirrored sections during the copy. Fix and re-run until zero hits.
+5. **Dual-track R1** — proceed per `dual-track-review-gate.md`. Expect the R1 → R4 trajectory above; budget 4 rounds, **but the stopping condition is not P0=0 alone**. Stop early only when review AND challenge produce no new P0/P1 in the latest round, every existing P0/P1 is either fixed or explicitly accepted/deferred, and the gate prompt's read scope still covers the latest fix-up. A round that reports P0=0 but still has open P1 correctness bugs from the previous round's fixes has not converged.
+6. **Commit each round's fixes as one commit, both files together.** Do not let a sibling commit lag; the second file is always one round behind otherwise.
+7. **Grep-gate parity between siblings.** When a stack-glue grep-gate's token list is updated on one file (after a review finding adds, say, `databases` or `pgvector` to the Python file's forbidden-token list), the sibling file's token list must be updated in the same commit unless the new token is genuinely stack-local. Without this check, both files' gates stay locally green while drifting away from each other. The sibling-sync verification checklist below includes a token-list parity comparison.