@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/schema-and-validation-patterns.md

@@ -0,0 +1,23 @@
+# Schema And Validation Patterns
+
+Use this for Pydantic, OpenAPI, Django serializers/forms, generated clients, and validation tests.
+
+## Rules
+
+- Public API request and response models should be explicit.
+- Keep persistence models separate from public schemas when fields, nullability, or exposure differ.
+- Validate syntax at the boundary and business rules in service/domain code.
+- Treat finite domain values as domain concepts, not scattered schema literals. Public schemas may expose `Enum`, `Literal`, or generated enum values, but handlers should convert them into the domain-owned symbol through one parser/canonicalization helper before service logic runs.
+- If a finite value crosses Python services, packages, storage, or generated clients, keep the canonical type/constants in the smallest shared domain or platform package already allowed by the repo. Do not create parallel enum sets with different casing, defaults, or unknown-value behavior. If no eligible shared package exists or creating one needs architecture approval, obtain architecture approval before merge, keep the local constants for this slice, add a same-line `finite-value-debt: <task-ref> <owner> <deadline> <reason>` comment at every temporary duplicate/raw use outside boundary conversion, and record a consolidation task. A debt marker does not constitute architecture approval. If architecture approval is not obtained before merge, the PR must not be approved; treat absent approval as a blocking finding. A debt marker without task reference, owner, and deadline is non-compliant.
+- When storage or existing domain models are string-based but OpenAPI/protobuf already has an enum, keep explicit enum/string conversion helpers and mark direct generated-enum or raw-string use outside boundary conversion with `finite-value-debt: <task-ref> <owner> <deadline> <reason>`. Do not depend on generated transport enums deep in domain code unless the whole layer is intentionally transport-coupled by a traceable architecture decision, recorded as an ADR path or inline usage-site comment formatted `architecture-approval: transport-coupled finite value <scope> <decision-ref> <reason>` where `<decision-ref>` is a full URL or numeric record id such as `ADR-123`; reviewers must confirm the referenced record exists and approves the specific value/scope before approval. A CI check, grep panel, or required review checklist item MUST exist and pass before any PR introducing `architecture-approval:` comments is merged; absence of that check is itself a blocking finding. The first PR that introduces `architecture-approval:` comments must include the enforcement check in the same PR or reference a prior merged check; "will add later" is not approval.
+- Architecture owns cross-boundary semantic consistency for finite values: approve the shared package or contract location, approve any transport-coupled exception through a traceable decision, and make sure every `finite-value-debt` marker has an exit owner, deadline, and consolidation task.
+- Do not return raw provider payloads directly from product APIs.
+- For shipped or externally consumed schemas, preserve backward-compatible request/response behavior by default. Add optional fields or versioned behavior first; do not remove fields, make optional fields required, rename keys, change enum meanings, or reject previously valid requests without explicit human approval of a breaking-change risk assessment.
+- Add tests for validation errors, default values, optional fields, enum handling, finite-value boundary conversion, unknown-value behavior, and compatibility-sensitive fields.
+- **Model library choice by boundary, not by author preference**: Pydantic at API request/response, config (Pydantic Settings), and any other untrusted-input parsing surface where validation + JSON-schema export + error messages are core; **`dataclass(slots=True, frozen=True)`** for internal shallow-immutable value objects with no validation need (smaller memory, no Pydantic overhead, no schema export — note `frozen=True` only prevents attribute reassignment, mutable fields like lists/dicts are still mutable in-place); **`msgspec`** when profiled hot-path evidence (high-rate serialization, low-allocation parsing) or an existing service / platform standard justifies it — Pydantic v2 (powered by `pydantic-core` in Rust) has narrowed the gap, so reach for msgspec on measured need, not by default. Mixing all three in one service is acceptable when each is at its right boundary; using one library for everything is the smell — Pydantic for internal pure data is overhead, dataclass for API input loses validation, msgspec everywhere makes the codebase non-standard for new contributors.
+
+## Generated Clients
+
+- Treat generated clients as output from OpenAPI/protobuf tools.
+- Update source contract first, regenerate, then test generated client behavior where the repo requires it.
+- For compatible changes, test old-client/new-server and new-client/old-server behavior when the repo has generated clients or consumer fixtures. For approved breaking changes, test that the removed compatibility path fails in the intended way and that the documented migration/cutover path works.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/source-evidence-map.md

@@ -0,0 +1,56 @@
+# Python Dev Source Evidence Map (Methodology Template)
+
+This file describes the **shape** of source-evidence tracking for Python implementation extraction. Project-specific provenance (real repo names, branch state, dates, module counts, extraction logs) lives in the maintainer's private alias file at `~/.<host>/.private-aliases/<project>.yaml`, never in this shared skill tree — see `skill-extraction-workflow` Core Rule "Extraction lifecycle handoff".
+
+## Scope boundary
+
+This shared template contains reusable methodology only. Do not add concrete repository names, branch state, infrastructure details, owner maps, or internal package conventions.
+
+## Source coverage dimensions
+
+When extracting Python implementation guidance from a new source set, organize evidence by these dimensions in the private alias map:
+
+| Dimension | What to collect | What to extract |
+| --- | --- | --- |
+| Broad Python inventory | Module count by shape (service vs library vs notebook vs tool) | Implementation guidance must classify shape before recommending patterns |
+| Web service samples | FastAPI / Flask / Django app factory, routes, dependency injection, middleware order, lifespan handlers | App-factory pattern, thin handlers, explicit dependency assembly, lifespan startup/shutdown |
+| Async / sync isolation | Real call chains showing async + blocking I/O / CPU / GPU work | Reject async if blocking work hides inside; isolate via thread/process pool with explicit boundary |
+| Pydantic / OpenAPI samples | Schema files, validation rules, error responses | Typed contracts; additive evolution; never use untyped dicts for public API |
+| ORM / migrations | SQLAlchemy / Django ORM / SQLModel session, unit-of-work, Alembic migration history | Session-per-request, transaction boundary, reviewed migrations (autogen is draft) |
+| Worker samples | Celery / RQ / arq tasks, schedule, retry, idempotency, ack semantics | Tool-specific caveats (Celery ack/retry/visibility, RQ timeout/TTL, arq async retry/defer); transactional enqueue/outbox boundary |
+| AI / inference adapter | LLM client, streaming protocol, replay store, token-cost tracker | Reject new turn while prior in-flight; persist partial state on timer; explicit terminal/recoverable states; close stream readers; record cost after completion |
+| Redis / cache | Client wrapper, Lua/CAS scripts, lock/renew helpers, idempotency state | Atomic script + fallback, compare-and-delete unlock, compare-and-expire renewal, positive-only counter, pending/completed idempotency |
+| Object storage / migrations | Storage client, conflict policy, source tagging, replay logs | Constructor/DI paths, conflict policy, source tagging, bounded concurrency |
+| Dynamic config | Config center client (etcd / Apollo / equivalent), key namespace, listener registration | Typed accessors, key namespace, listener registration, fail-mode discipline (last-known-good vs fail-closed vs fail-open) |
+| Test layer | unit / integration / live-dependency separation, fixtures, mocks | Focused tests, live-dependency tests outside fast gate |
+| Packaging | uv / poetry / pip-tools, lockfile, dependency groups, container | Reproducible builds, pinned, documented entrypoint |
+| Official docs | Python language / framework / library official docs | Stable references for primitive behavior |
+
+## Sibling-generalization mini-map (template)
+
+For each Python extraction, record decisions across sibling skills:
+
+- `python-service-architecture` — does the rule belong at architecture level instead?
+- `go-microservice-dev` — does the same pattern apply to Go? mirror with evidence caveat.
+- `go-microservice-architecture` — cross-language architecture consequence?
+- `llm-inference-integration` — does the AI/inference-adjacent rule belong there?
+- `testing-strategy` — does this affect test-layer policy?
+- `defect-diagnosis` — does this prevent a class of defect?
+
+Decisions go in the private alias map alongside the per-batch extraction log.
+
+## Coverage discipline rules
+
+- Mark each dimension `pending` / `read` / `deep-read` / `excluded` / `unavailable` / `routed` with the actual artifacts inspected.
+- Distinguish targeted mechanism extraction from full coverage.
+- Re-read source artifacts when changing rules; use `wording cleanup` / `no new source read` labels honestly.
+
+## Where the live provenance lives
+
+For the maintainer's current Python extraction project, see:
+- Private alias map: `~/.<host>/.private-aliases/<project>.yaml`
+- Per-batch extraction logs: `~/.<host>/skills/.extraction-work/<batch>-completion.md`
+
+## Audit gate
+
+Before committing a change to this skill, run the private alias map's `audit_cmd` against the changed shared-skill files. Any hit on real repo names, branch states, dates, file counts, or business-domain nouns is either fixed or recorded as `known_debt` (pre-existing hits only — new/modified content must stay zero-hit per the R0 rule).

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/sqlalchemy-and-migrations-patterns.md

@@ -0,0 +1,99 @@
+# SQLAlchemy And Migrations Patterns
+
+Use this for SQLAlchemy, SQLModel, Django ORM, Alembic, repository code, and transactions.
+
+## Implementation
+
+- Use repository or data-access modules to keep SQL/ORM details out of routes.
+- Use explicit session ownership. The caller should know whether it owns commit/rollback.
+- Use `with session.begin()` or repo-standard unit-of-work helpers for multi-step writes.
+- New Python relational services use SQLAlchemy 2.x plus Alembic by default unless the service records a deliberate alternative data-access choice; use framework ORM and migrations when the chosen framework, such as Django, owns that boundary. For new MySQL async services, prefer `asyncmy`; `aiomysql` is allowed when deliberately chosen or already established. Do not replace an existing working `aiomysql` driver solely to comply with the default. Do not mix MySQL async drivers inside one service boundary.
+- Keep indexes, unique constraints, and query filters aligned with API access patterns.
+- If repository filters, query builders, or update builders are mutable or single-use, document that behavior and cover it with tests so callers do not accidentally reuse cleared conditions across reads, updates, or retries.
+
+## Index Safety
+
+Evidence boundary: these rules generalize backend index-risk mechanics to Python ORM and migration tooling. Before treating them as local convention, confirm the active repository's database, migration framework, repository patterns, and query-plan tooling.
+
+- Review SQLAlchemy, SQLModel, Django ORM, and raw SQL repository methods against the migration-defined indexes. For hot paths, compare `.filter()`/`.where()` predicates, joins, soft-delete filters, `order_by`, `limit`/`offset`, and pagination with the left-prefix order of composite indexes in Alembic or Django migrations.
+- Do not treat `index=True` on a model field as enough proof. Composite access paths, uniqueness, partial indexes, functional indexes, and sort order must be visible in reviewed migrations or schema metadata.
+- For SQLAlchemy, use compiled SQL, query logging, or database-specific `EXPLAIN` in integration tests when SQL shape matters. For Django, inspect `QuerySet.explain()` or the generated SQL for hot repository methods. Assert the expected index/key or a bounded plan/row estimate when the database target makes that stable.
+- Leading-wildcard `like`/`ilike`, broad `or_()`/`Q(... | ...)`, tuple or large `in_`, `distinct()` over joins, and offset pagination need a documented cardinality bound, a query-plan test, or a separate search/read-model/keyset path before they are treated as production hot paths.
+- If a repository uses dialect-specific index hints or raw SQL to force a plan, keep the hinted index in checked-in migrations and cover the method with an integration test. Hints without migration evidence are review findings.
+- Upsert or idempotent write paths that re-query to repair generated IDs or timestamps should re-query by the same unique/conflict key shape used by the write. Extra filters must be redundant, indexed, or explicitly justified as bounded narrowing conditions.
+
+## Migrations
+
+- Generate migrations when the tool supports it, then review and edit them.
+- Include indexes, constraints, data migration risks, downgrade/rollback expectations, and lock impact.
+- Keep migration files near model/repository changes in the same implementation slice.
+
+## Postgres Driver Choice (psycopg vs asyncpg)
+
+- **`psycopg` (v3, formerly psycopg3) is the recommended modern Postgres driver for new SQLAlchemy 2.x services that need both sync and async support** — per psycopg docs, it ships one library with both a PEP-249 sync API and an asyncio-native async API. **Per SQLAlchemy docs**, the `postgresql+psycopg://...` URL is the unified dialect for psycopg v3 and SQLAlchemy auto-selects the sync vs asyncio implementation based on which engine constructor is called (`create_engine()` vs `create_async_engine()`); this is a SQLAlchemy-dialect convenience, not a psycopg-only feature. Built-in support for pipeline mode, server-side parameter binding, and current Postgres features. Migration target for services on psycopg2 (which is in maintenance, not EOL but no new features). Choose psycopg when (a) the service has any sync code path (CLI, scripts, sync framework), (b) the team wants one driver for the whole codebase, (c) modern Postgres features (composite types, JSONB nuances, async pipeline) matter. **PgBouncer transaction-pooling footgun**: psycopg v3 uses server-side prepared statements by default for repeated queries — under PgBouncer in `pool_mode = transaction` (or RDS Proxy / similar transaction-pooled proxy), prepared statements registered on one backend connection will not exist on the next pooled connection and queries fail with `prepared statement "_pg3_N" does not exist`. Mitigations: disable psycopg server-side prepared statements via `prepare_threshold=None` on the connection (or per-cursor), switch PgBouncer to `session` pooling for that service (gives up connection multiplexing), or run psycopg against a direct Postgres connection / session-pooled endpoint. Same caution applies to other session-state operations (server-side cursors, `LISTEN/NOTIFY`, advisory locks held across statements) — these are not psycopg-specific but psycopg's prepared-statement default surfaces the problem faster than psycopg2 did.
+- **`asyncpg` is the alternative for pure-async high-throughput Postgres workloads** — independent of psycopg lineage, optimized for the async path; SQLAlchemy supports it as an async dialect. Per official docs, asyncpg often wins synthetic benchmarks vs psycopg async, but the gap has narrowed and the operational cost of "different sync and async drivers in one service" is real. Choose asyncpg only when: (a) the service is 100% async with no sync DB path anywhere, (b) profiled hot-path evidence shows measurable improvement over psycopg async, (c) team accepts that any future sync code (Alembic migration runner, batch script, admin CLI) will use psycopg2/psycopg, creating a two-driver setup. Mixing both is acceptable when migrations + sync admin paths legitimately stay on psycopg and the async serving path is asyncpg, but record the boundary explicitly.
+
+## Async Session Boundaries
+
+`AsyncSession` from SQLAlchemy 2.0 is bound to a single event loop and a single task at a time.
+
+- Do not share one `AsyncSession` across child tasks of `asyncio.gather`, `asyncio.TaskGroup`, or background-task launches. Each concurrent worker needs its own session from the same `async_sessionmaker` or its own `async with session.begin()` scope.
+- Do not pass an `AsyncSession` into a background coroutine that outlives the originating request, FastAPI dependency, or async-context block; the connection may already be returned to the pool by the time the background work runs.
+- Sync drivers in async paths: do not call `Session` (sync) or sync DB-API code from async handlers — wrap with `asyncio.to_thread` and an isolated sync engine if a sync-only library is unavoidable.
+- Use `async_sessionmaker(expire_on_commit=False)` when the request handler will read instance attributes after commit; otherwise expect detached-instance errors.
+- For request-scoped sessions in FastAPI, yield from a dependency that opens and closes the session; do not store sessions on `request.state` for later use after the dependency exits.
+
+## Connection Pool Sizing And Proxy Interaction
+
+Pool sizing is a contract between the application, the connection proxy (PgBouncer, RDS Proxy, Azure Database Proxy), and the database server.
+
+- Derive per-process `pool_size + max_overflow` from a global connection budget, not from a per-process demand multiplier. Compute the global budget as the smallest binding constraint among database `max_connections` (minus reserved superuser/admin slots), proxy client-connection limit, and any reserved capacity for other services. Divide that budget across (replicas × processes_per_replica) to get the per-process limit; pick `pool_size` and `max_overflow` so that `pool_size + max_overflow ≤ per-process limit`.
+- Async concurrency per worker is a **demand signal**, not the pool size. High in-flight concurrency tells you the pool is undersized for the workload (rising checkout latency, overflow exhaustion); the response is to grow workers/replicas, raise the global budget if the DB and proxy allow it, or shed load — not to set `pool_size = workers × concurrency` literally.
+- Under a transaction-pooling proxy (PgBouncer default, RDS Proxy in some modes), session-level state does not survive between transactions: avoid `SET LOCAL` outside an open transaction, server-side cursors that span statements, prepared statements cached client-side, `LISTEN/NOTIFY`, and advisory locks that expect session continuity. Configure SQLAlchemy with `pool_pre_ping=True`, disable statement caching where the proxy mode requires it, and reset session state explicitly when reuse is intentional.
+- Set `pool_recycle` shorter than the proxy or load balancer idle timeout to avoid stale connection errors.
+- Treat `QueuePool.overflow()` and checkout latency as observable metrics; sustained checkout latency means the pool is undersized for the current concurrency.
+
+## Outbox Pattern For Cross-Write Consistency
+
+Writing to the database and then writing to Redis or a message queue is not atomic. Use an outbox table when both must reflect the same business fact.
+
+- In the same DB transaction as the business write, insert a row into an `outbox` table with the payload, target topic/channel, and a status column.
+- A separate relay (sidecar, worker, or CDC consumer) reads pending outbox rows, publishes to MQ/Redis, and marks the row processed. Publishing is at-least-once; consumers must be idempotent.
+- Do not write to Redis or publish to MQ inside the DB transaction expecting both to succeed; either commit on the DB side and discover the external write failed, or fail the external write and leave the DB committed.
+- Outbox rows that are never published need an alarm path; failed-publish counts and oldest-pending-age are first-class metrics.
+- For high-throughput cases, consider logical replication / CDC (e.g., Debezium-style) to read the WAL/binlog instead of polling the outbox table.
+
+## Read Replica Routing
+
+When the deployment includes read replicas, application-layer routing decides which session factory each call uses.
+
+- Maintain a separate `async_sessionmaker` (or session factory) per role: writer (primary), reader (replica). Do not route inside repository methods on a per-statement basis unless the framework already provides safe routing.
+- Default writes and read-after-write within the same request to the writer; route only pure reads with no write dependency to the replica.
+- Replica lag is non-zero. For "read your own writes" within a session, hold a write-consistency window (request scope, causality token, or master-on-write flag stored on the session/context) and route to writer during that window.
+- Forced master read for diagnostics and admin paths should be an explicit option, not a default.
+- Never write through a replica session by accident: replica engines should be configured with read-only DB users when the database supports it.
+
+## Long-Running Transaction And Idle-In-Transaction Monitoring
+
+Hot connection on an open transaction blocks vacuum/autovacuum (PostgreSQL) and burns row locks; idle-in-transaction is a common production fire.
+
+- Configure database-side limits: PostgreSQL `statement_timeout` per role (short for OLTP roles, longer for batch roles) and `idle_in_transaction_session_timeout` to cap stuck transactions; MySQL `MAX_EXECUTION_TIME` hint or `max_execution_time` server var.
+- Instrument transaction duration as a histogram; alert on p95/p99 above the SLO for the path.
+- FastAPI dependency-scoped sessions implicitly tie the transaction to the request lifetime; do not extend the session into background tasks, streaming responses that do not commit promptly, or long-running websocket loops.
+- Do not run external HTTP calls, inference calls, or long object-storage uploads inside an open DB transaction; commit first or move the external call outside the transaction boundary.
+- Watch for implicit transactions opened by auto-begin behavior on first statement; commit or rollback explicitly at the request boundary.
+
+## Alembic CI Dry-Run And Drift Detection
+
+Migrations are reviewable source artifacts and should fail CI when they drift from models or when production schema cannot replay them.
+
+- Run `alembic upgrade --sql head` in CI against a known starting revision to render the SQL plan; review the rendered SQL in code review when the migration is data-sensitive.
+- Run `alembic check` (or `alembic revision --autogenerate --check` style) in CI to detect uncommitted model→schema drift; fail the build when autogenerate produces a non-empty diff and the PR did not include a corresponding revision.
+- Maintain a baseline-revision policy: CI applies all migrations against an empty database and a copy of the previous release schema; both must succeed.
+- Data migrations and irreversible operations (column drop, type change with implicit cast) must be split from schema migrations and reviewed separately; never let `autogenerate` produce destructive operations silently.
+- Do not let `alembic merge` resolve concurrent heads without a human reading the merge; merges hide ordering bugs.
+
+## Tests
+
+- Use fake repositories for pure service tests.
+- Use real DB integration tests only when SQL semantics, constraints, transactions, or migrations are under test.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/testing-and-quality-patterns.md

@@ -0,0 +1,61 @@
+# Testing And Quality Patterns
+
+Use this for pytest, async tests, fixtures, fakes, ruff, mypy/pyright, and CI quality gates.
+
+## Scope
+
+- Use `testing-strategy` when deciding which test layer should own confidence.
+- Use this file for Python mechanics after the layer is chosen.
+
+## pytest
+
+- Prefer focused tests for changed modules.
+- Use fixtures for app, settings, fake clients, DB sessions, and sample payloads.
+- Use markers to separate unit, integration, API, contract, E2E, live-infra, failure-mode, and drill tests.
+- Use `pytest-asyncio` for async code according to repo configuration.
+- Avoid long sleeps and live credentials in default tests.
+- For scenario tests, use `testing-strategy` to build the scenario matrix first; in Python services, map scenarios to unit tests, API/contract tests, integration tests, workflow tests, or marked E2E/live-infra tests instead of putting every case into a slow end-to-end suite.
+
+## Test Target Split
+
+- Keep the default target fast, deterministic, and runnable without live DB, Redis, MQ, service discovery, cloud credentials, private-network endpoints, or external model servers.
+- Put infrastructure-dependent tests behind explicit markers, environment variables, separate pytest targets, or separate CI jobs.
+- Mark long-running tests clearly. Replace fixed sleeps with condition waits such as persisted state, emitted event, queue drain, HTTP response, or visible status.
+- Generated output tests should compare parsed structures or stable golden files, not require manual inspection.
+
+## Unit And Boundary Tests
+
+- Unit-test validation, domain rules, config parsing, cache-key builders, retry decisions, error mapping, idempotency decisions, and authorization/resource-scope resolution.
+- For finite domain values, tests should use the domain `Enum`/`Literal` alias/constants or boundary conversion helper instead of repeating raw strings. Raw strings are acceptable only inside boundary conversion tests that prove specific external wire/storage values map to domain symbols. Those tests must be machine-findable by BOTH a file/test name containing `boundary`, `conversion`, `wire`, or `storage` AND a sentinel comment/docstring `finite-value boundary conversion tests only`; there is no unmarked "dedicated converter file" exception. The sentinel comment is invalid unless the project's lint, grep panel, or required review checklist for import isolation is active and passing for that file; for a repo without that enforcement yet, the same PR must add the checklist/check or link a tracked enforcement task before claiming the sentinel exception. When the repo supports markers, add a `boundary_conversion` pytest marker or equivalent so the boundary-only set is easy to audit. Boundary conversion test files must contain no assertions on business-rule inputs or application state; shared fixtures/helpers are allowed only when they do not assert application state. Any mixed assertion file is non-compliant regardless of sentinel presence. A project lint, grep panel, or required review checklist MUST fail/block when sentinel boundary files import or call application service, repository, or workflow layers. Cover every known wire/storage value plus at least one unknown or invalid value and the converter-level default/empty output, such as returning the domain unknown/default symbol; do not assert downstream application state in these tests. When adding a finite-value boundary module, migrate existing test raw literals for that value in the same pull request or mark each remaining use with `finite-value-debt: <task-ref> <owner> <deadline> <reason>`. Pre-existing scattered raw literals in non-boundary tests are in scope only for the same touched file/module and finite value; flag them with the same debt marker even when the current slice does not introduce a new mapper. A PR containing an in-scope non-compliant `finite-value-debt` marker, or an in-scope unmarked raw literal in a non-boundary test, must not be approved; treat it as a blocking finding equivalent to a missing test. For out-of-scope occurrences found by grep, record the tracking issue instead of expanding the current PR indefinitely.
+- Exercise negative paths: missing required fields, malformed config, forbidden actor, tenant/resource-scope mismatch, duplicate idempotency key, dependency timeout, and malformed downstream response.
+- For async code, test cancellation, shorter parent deadlines, bounded worker count, duplicate starts, exception recovery, and final state.
+- API/contract tests should assert response shape, canonical error code, auth failure behavior, OpenAPI/Pydantic schema behavior, and backwards-compatible defaults.
+
+## Fakes And Integration Boundaries
+
+- Prefer small fakes or protocol-backed test doubles for external HTTP/RPC clients, object storage, repositories, queues, inference clients, and notification providers.
+- Fake clients should cover success, transport error, timeout, non-OK domain status, malformed response, slow response with cancellation, and duplicate delivery where relevant.
+- DB tests should cover transaction commit/rollback, migration shape, pagination, uniqueness/idempotency constraints, and query-safety expectations when the repo has hooks or review tooling.
+- Redis tests should cover TTL, cache miss vs infrastructure error, lock acquire failure, compare-and-delete unlock, lease expiry, and idempotency states.
+- Queue/worker tests should cover duplicate delivery, retry/drop/dead-letter behavior, ordering assumptions, worker concurrency, graceful shutdown, and replay visibility.
+
+## Real-Flow Evidence
+
+- Real dependency, E2E, and live-infra tests stay outside the default fast target, but they become release-blocking evidence for high-risk paths where fakes hide credential, runtime, network, callback, data-shape, queue/DB semantics, or deployment behavior.
+- A real-flow test should assert the user or caller outcome plus the durable backend result: response envelope, canonical error code, trace/log id, persisted state, emitted event, callback receipt, or generated artifact.
+- If a required real-flow gate is unavailable, record the remediation attempted, residual risk, and next unblock action. If a real-flow test fails, route through `defect-diagnosis`; do not replace it with a mock-only assertion unless the original scenario is invalid.
+- Keep screenshots, payload samples, log snippets, or trace ids as evidence pointers; the test still needs deterministic assertions.
+
+## Codegen And Migration Checks
+
+- When Pydantic/OpenAPI/protobuf clients, Alembic migrations, templates, or deployment manifests change, run the repo's generation/check command and verify generated output is either clean or intentionally reviewed.
+- Migration tests or review evidence should cover upgrade path, downgrade/rollback expectation when supported, data backfill order, and compatibility with old readers/writers when the change is contract-visible.
+
+## Quality Tools
+
+- Run ruff for lint/import/style when configured.
+- Run mypy or pyright when configured.
+- Keep generated or vendored code excluded according to repo policy.
+- Use coverage gates when the repo already enforces them or the change is high risk.
+- **`ruff` (Astral) is the current default-recommendation single tool for lint + format + import sort** — per Astral docs, replaces Flake8 (and dozens of plugins), Black, isort, pydocstyle, pyupgrade, autoflake with one Rust binary; ~900 lint rules (vs Pylint ~409, with ~209 rule overlap); ~tens to hundreds of times faster than the tools it replaces (e.g., the FAQ cites 250k-LOC codebase 2.5min on Pylint vs 0.4s on Ruff). Auto-fix for most violations. Use ruff for new projects by default; existing projects can migrate piecewise (linter and formatter are independent — adopt one without the other). **Pylint coverage gap to audit before retiring it**: ruff does NOT replicate Pylint's deeper semantic / data-flow analysis (Pylint's inference engine can catch e.g. argument-count mismatches across complex call chains, unreachable-after-mutation patterns, type-confusion in dynamically typed code that doesn't reach the type checker), Pylint's broader dead-code detection (beyond ruff's import-level checks — unused-method, unused-attribute, unused-private-member with project-aware reasoning), design smells (cyclomatic-complexity bands, too-many-arguments / too-many-locals / too-many-branches thresholds), duplicate-code detection (`similarities` checker), and any custom in-project Pylint plugin or rule. Strategy: ruff + a type checker (mypy / pyright / ty) replaces Pylint for ~80% of teams; teams relying on the specific Pylint capabilities above should keep Pylint as a slower secondary gate or migrate the equivalents (e.g., use `radon` for complexity, `vulture` for dead-code, a type-checker-level config for design smells) before retiring.
+- **`ty` (Astral, Beta announced 2025-12-16 per Astral's own announcement) is the current state of Rust-based type-checker work** — per the Astral announcement, on full check "consistently between 10x and 60x faster than mypy and Pyright" depending on workload, with editor incremental recompute on the order of ~80x faster than Pyright on a touched load-bearing file in benchmark workloads. Read these as Astral-published numbers on Astral-chosen benchmarks; actual speedup on a given codebase varies. Notable features: first-class intersection types, advanced narrowing, reachability analysis. Status: **Beta, not GA** — appropriate for piloting on a separate CI job alongside the existing mypy / pyright / basedpyright gate, NOT for replacing the production type-check gate on its own yet. **Dual-gate operational cost to size before adopting**: running ty plus mypy/pyright produces a "triage tax" — divergent type narrowing (one tool reports, the other doesn't), different stub-package assumptions (typeshed version skew), duplicated CI latency, and a "fix one, break the other" churn pattern that slows MRs. Make the pilot a non-blocking informational job and budget time for periodic finding-diff review rather than treating both as equal blocking gates. Watch for ty GA before flipping defaults. basedpyright remains a viable strict-mypy-like alternative if Pyright's strictness gaps matter and ty isn't ready.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/web-framework-patterns.md

@@ -0,0 +1,35 @@
+# Web Framework Patterns
+
+Use this for FastAPI, Flask, Django, Starlette, route handlers, app factories, middleware, and dependencies.
+
+## FastAPI
+
+- Use routers for feature boundaries.
+- Use Pydantic models for request/response contracts.
+- Use dependency functions for request-scoped dependencies, not for hidden heavy construction.
+- Use lifespan/startup assembly for shared clients and cleanup.
+- Test APIs through framework test clients or `httpx` ASGI clients when appropriate.
+
+## Litestar (FastAPI Alternative)
+
+- **Litestar (formerly Starlite) is the current batteries-included alternative to FastAPI** for typed ASGI services where the project wants more framework-level structure out of the box (built-in ORM integration, server-side sessions, caching, OpenTelemetry, plugin system) without assembling them per-project. Per Litestar benchmarks, performs at the front of the ASGI framework pack (does not extend Starlette — implements its own routing and significant ASGI layer; precomputes route requirements at bootstrap so per-request work is minimized). DI model differs from FastAPI: dependencies declared as `{key: Provide(callable)}` dicts at app/router/controller/route level rather than per-parameter `Depends()`, allowing transparent override at every nesting level. Choose Litestar over FastAPI when: (a) the team wants framework-owned ORM/cache/sessions/OTel rather than choosing each, (b) deeply nested DI override is common, (c) the OpenAPI schema is the dominant contract surface and Litestar's first-class controller pattern fits the team's mental model. Stay on FastAPI when: (a) the team already has FastAPI muscle memory and ecosystem pieces, (b) Pydantic + `Depends()` per-parameter is the team's preferred shape, (c) ecosystem maturity (third-party tutorials, hiring pool, vendor integrations) matters more than the framework-feature delta. Architecture-level framework choice belongs in `python-service-architecture/references/web-framework-boundaries.md`; this file owns the per-feature Litestar implementation details once chosen.
+- Treat identity, ownership, actor, tenant, creator, account, and permission fields in headers, query params, bodies, and downstream service calls as client claims until resolved from authenticated context or an authoritative service.
+- For write paths, use the resolved authenticated identity as the source of truth. Either overwrite client-supplied owner/creator fields or reject mismatches; never use authenticated identity only as a fallback after trusting a request field.
+- When fixing an auth or permission bug, search every ingress and propagation point for the same trust class: headers, body fields, query params, path params, generated client/server schemas, service defaults, and downstream repository inputs.
+- When fixing auth or permission behavior, test every input surface that could carry the same spoofing class, and assert downstream services receive the resolved identity or the request is rejected.
+- Add fail-closed tests for auth, permission, capability, and profile-resolution errors before side effects.
+
+## Flask
+
+- Prefer app factories for non-trivial apps.
+- Keep views thin and push business logic into services.
+- Use blueprints for modular routes.
+- Avoid process-global mutable state unless it is explicitly initialized and test-substitutable.
+- Do not trust request-provided ownership or actor fields for writes; resolve them from authenticated context and pass the resolved identity into services.
+
+## Django
+
+- Follow framework conventions for apps, settings, migrations, and admin when they serve the product.
+- Keep domain logic out of views/templates when it needs testing or reuse.
+- Use transactions for multi-write workflows.
+- Keep user/tenant/owner attribution authoritative from `request.user`, signed session/context, or a trusted service; reject or ignore conflicting request payload fields.

package/dist/assets/marketplace/plugins/ccl-skills/skills/release-coordination/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: release-coordination
+description: 发版 / 生产发布 / prod release / 上线范围确认 / 合并 main / 打 tag / 生产构建 / 发布后 reset / 按已确认的上线范围产出测试范围提示（提测范围、这次要回归哪些面）→ coordinate release scope, docs, MR/tag gates, pipeline evidence, rollout handoff, watchers, reset. 从已确认发布范围派生的测试范围提示归本技能——它是发布交接物；完整测试层级/矩阵/CI gate 设计 → testing-strategy。
+---
+
+# Release Coordination（生产发版协调）
+
+Use this as the **production release coordinator** for scope confirmation, production MR, merge authorization, tag/build gate, evidence closeout, or reset.
+
+Skip / route directly when the task is narrower:
+
+- Release / launch document substance → `release-doc-writer`.
+- Rollout/canary/rollback/control plane → `platform-release-engineering`.
+- Risk gates → `feature-risk-router`.
+- Verification strategy → `testing-strategy`.
+- Active post-release error → `defect-diagnosis`.
+- Wording polish → `tighten-doc`.
+
+This skill coordinates gates; it does **not** itself authorize merge, tag push, production mutation, manual job play, force-push reset, or destructive cleanup. Boundary: once the user authorizes a merge, post-merge closeout cleanup of the merged **temporary feature branch created for this delivery** (worktree + local branch + remote branch) is already covered by that merge authorization per `worktree-isolation` 收尾 — do not re-ask (eligibility evidence per the Authorization matrix cleanup row). Permanent/integration source branches (e.g. `dev`) are never cleaned up under this carve-out, and an unclear branch role means preserve and ask; cleanup mechanics and safety rails stay with `worktree-isolation`.
+
+## Owner routing
+
+| Concern | Owner |
+| --- | --- |
+| Release document evidence | `release-doc-writer` |
+| Rollout / rollback / production control plane | `platform-release-engineering` |
+| Risk labels and mandatory gates | `feature-risk-router` |
+| Verification strategy | `testing-strategy` |
+| Active incident / failed smoke | `defect-diagnosis` |
+| Release evidence signals | `platform-observability` |
+| Local branch/worktree safety | `worktree-isolation` |
+| MR/CI/tag commands | repo tooling (`glab`, `gh`, approved API/CLI) |
+| Feishu/Lark document operations | Feishu/Lark tooling |
+| Wording polish | `tighten-doc` |
+
+## Core lifecycle
+
+1. **Intake** — stated scope, production target, release source, tag rule, doc artifact, environments, and user decisions.
+2. **Scope-confirmation gate** — compare intended scope with first-hand `base...release-head` diff/log evidence; block on mismatch, over-broad source, target drift, or undocumented operational deltas.
+3. **Test-scope prompt** — emit test-scope handoff from confirmed diff; route full design to `testing-strategy`.
+4. **Release-doc gate** — invoke `release-doc-writer` to write confirmed scope/evidence depth before MR/merge authorization.
+5. **MR/PR gate** — duplicate check; read back URL, source/target, head SHA, CI, mergeability, discussions, auto-merge, and the remove-source-branch flag (the flag may stay set only if the cleanup row's source-eligibility conditions — temp branch created for this delivery, no other open or plan-declared consumer — still hold at merge time; otherwise read the flag back OFF before merging — asking may resolve classification, never waive this invariant).
+6. **Merge gate** — re-read immediately; single-form authorization names current object + head SHA, stale state means ask again; batch-form ("批量合并 N") authorization is scoped to the presented release plan — in-plan commits/MRs the agent itself creates while executing the plan stay authorized, out-of-plan objects and third-party changes still require asking again (canonical: `references/mr-merge-authorization.md` + `worktree-isolation` 合并执行协议).
+7. **Tag/pipeline gate** — verify tag absence/target; after push read back remote tag and pipeline/job behavior.
+8. **Rollout/config handoff** — live mutation goes to `platform-release-engineering`; this skill tracks evidence.
+9. **Watchers** — bounded read-only watchers; stop on terminal/manual/timeout and reconcile.
+10. **Closeout** — report only read-back facts and explicit gaps/deferred items.
+11. **Post-release reset** — remote ref maintenance with dry-run/before-after SHAs, `--force-with-lease`, and SHA equality proof.
+
+## Authorization matrix
+
+| Action | Auth? | Minimum evidence |
+| --- | --- | --- |
+| Create/update release document | No, if requested | Target section and comment-safe edit plan |
+| Create/update MR/PR | Usually no, if requested | Confirmed release scope, source/target, duplicate-check result |
+| Merge MR/PR | Yes | Current MR/PR, head SHA, CI/mergeability, discussions, auto-merge flag |
+| Create/push production tag | Yes if prod-triggering | Tag name, absence, target commit, expected pipeline behavior |
+| Play manual production job | Yes | Specific job id/name, pipeline, status, intended effect |
+| Modify production config/resource | Yes | Release-doc decision, read-only current state, planned delta |
+| Restart/rollout production workload | Yes | Affected workload, reason, expected state and rollback path |
+| Reset dev/test-like branches | Yes | Target/env refs, before SHAs, dry-run/plan, force-with-lease semantics |
+| Post-merge cleanup of the merged temp feature branch (worktree/local/remote) | No — covered by the user's merge authorization (`worktree-isolation` 收尾) | The authorized MR/PR read back as merged at the current head SHA and target; the live remote source ref is absent (already cleaned by the platform) or still equals the merged MR source head (moved → preserve and ask, remote path only — eligible local cleanup proceeds per `worktree-isolation`); no other open or plan-declared MR/PR still consumes the source branch; source branch is a temp feature branch (unclear role → preserve and ask); mechanics/safety rails per `worktree-isolation` |
+
+## Minimal checklist
+
+- [ ] Intended scope, base/head refs, and production target identified.
+- [ ] Diff/log scope matches intent; mismatch/broad source/target drift resolved with the user.
+- [ ] Operational deltas documented or intentionally deferred.
+- [ ] Test-scope prompt emitted or routed to `testing-strategy` for full design.
+- [ ] Release doc updated from confirmed first-hand evidence.
+- [ ] MR/PR read-back includes head SHA, CI, mergeability, discussions, auto-merge, remove-source-branch flag.
+- [ ] Merge authorization is current — for the exact object and head SHA (single form) or for the presented release plan (batch form, in-plan objects only).
+- [ ] Merge read-back confirms production target ref.
+- [ ] Tag target and remote tag read-back verified.
+- [ ] Manual jobs only observed unless explicitly authorized to play.
+- [ ] Production config/resource changes delegated and read back.
+- [ ] Watchers are bounded and reconciled.
+- [ ] Closeout states evidence gaps and deferred items honestly.
+- [ ] Post-release reset uses remote refspec + `--force-with-lease` + SHA equality proof.
+- [ ] Post-merge closeout cleanup of merged temp feature branches done per `worktree-isolation` 收尾 and the Authorization matrix cleanup row (or a defer/retention reason it sanctions recorded per path — e.g. 让位 pending external-side-effect task or squash non-ancestor retention, both local-path only, remote cleanup still follows the authorized merge when the matrix cleanup row's eligibility holds; never speculative keep-for-later).
+
+## References
+
+- `references/mr-merge-authorization.md`
+- `references/release-scope-confirmation.md`
+- `references/test-scope-prompt.md`
+- `references/tag-and-prod-pipeline-gate.md`
+- `references/config-runtime-readback.md`
+- `references/post-release-env-reset.md`
+- `references/watcher-discipline.md`
+- `references/release-closeout-evidence.md`

package/dist/assets/marketplace/plugins/ccl-skills/skills/release-coordination/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Release Coordination"
+  short_description: "Coordinate production release lifecycle gates"
+  default_prompt: "Use $release-coordination to coordinate release docs, MR authorization, tag gates, production pipeline evidence, watchers, and post-release reset."

package/dist/assets/marketplace/plugins/ccl-skills/skills/release-coordination/references/config-runtime-readback.md

@@ -0,0 +1,20 @@
+# Config and Runtime Read-back
+
+Production config/resource mutation belongs to `platform-release-engineering`; this coordinator only enforces the release-sequence and evidence gate.
+
+Before any live config/resource change:
+
+- Re-read the release document decision.
+- Inspect current state read-only first.
+- Identify only the intended key/resource/workload delta.
+- Never print Secret values.
+- Prefer key presence, value class, hash, revision, or effective-env proof over dumping full config.
+
+For file-mounted or env-injected config, distinguish evidence layers:
+
+1. Source key exists.
+2. Deployment/runtime surface receives it.
+3. Pod/container/process has the effective value or file.
+4. The application behavior/log/metric confirms the process consumed it.
+
+For worker decisions, keep multi-replica API pods separate from singleton/dedicated worker lanes, and read back replicas, image/digest, readiness, and relevant config key presence after rollout.

package/dist/assets/marketplace/plugins/ccl-skills/skills/release-coordination/references/mr-merge-authorization.md

@@ -0,0 +1,31 @@
+# MR/PR Merge Authorization Gate
+
+Merge authorization is plan-scoped, never blanket: a single directive
+("合并"/"merge") covers exactly the one MR/PR under discussion; a batch
+directive ("批量合并 N") covers at most N platform merges **within the
+release plan the agent has already presented** (wave order, per-repo MRs or
+how they will be created) — anything outside that plan needs fresh
+authorization. Batch is the right form for dependency-chain releases
+(core package → release → dependents bump → merge → tag) where dependent
+MRs do not exist yet at authorization time; semantics and the mechanical
+valve are canonical in `worktree-isolation` 「合并执行协议」.
+
+Before asking for or acting on authorization, read back the current MR/PR
+(single form), or present the release plan (batch form):
+
+- URL / number.
+- Source and target refs.
+- Current head SHA.
+- CI / pipeline status and URL.
+- Mergeability / conflict state.
+- Discussion / approval state when the platform exposes it.
+- Auto-merge / merge-when-pipeline-succeeds flag.
+
+Rules:
+
+- If head SHA changed after the last user-facing confirmation, authorization is stale. (Batch form: commits/MRs the agent itself creates while executing the presented plan are inside the authorization; third-party or out-of-plan changes still require re-presenting.)
+- If CI, mergeability, target branch head, or auto-merge state changed materially, re-present the object before merging.
+- Do not enable auto-merge, merge queue, or merge-when-pipeline-succeeds unless the user explicitly authorizes that behavior for the current object.
+- Prefer platform/CLI/API options that guard the expected source head SHA. If unavailable, fetch and verify immediately before action, then report the residual race.
+
+After merge, read back merged state, merge commit or equivalent result, and target branch head.

package/dist/assets/marketplace/plugins/ccl-skills/skills/release-coordination/references/post-release-env-reset.md

@@ -0,0 +1,31 @@
+# Post-release Environment Branch Reset
+
+Resetting integration environment branches after release is remote branch pointer maintenance, not local checkout development.
+
+Preflight:
+
+- Confirm the production release closeout is complete enough to use as the baseline.
+- Identify the target production ref and every environment branch to reset.
+- Fetch target and environment refs.
+- Record before SHAs.
+- Prefer a dry-run or equivalent before the mutating push.
+
+Safe implementation pattern:
+
+```bash
+git fetch origin <target> <env-branch-1> <env-branch-2>
+git push --force-with-lease origin \
+  origin/<target>:refs/heads/<env-branch-1> \
+  origin/<target>:refs/heads/<env-branch-2>
+git fetch origin <env-branch-1> <env-branch-2>
+```
+
+Completion proof:
+
+```bash
+git rev-parse origin/<target>
+git rev-parse origin/<env-branch-1>
+git rev-parse origin/<env-branch-2>
+```
+
+The reset is complete only when every reset environment branch equals the target SHA. Avoid scripts that checkout and hard-reset local branches; they mutate the working checkout and can leave local/remote refs inconsistent if hooks or pushes fail.

package/dist/assets/marketplace/plugins/ccl-skills/skills/release-coordination/references/release-closeout-evidence.md

@@ -0,0 +1,20 @@
+# Release Closeout Evidence
+
+Do not say “release complete” unless the required evidence surfaces for this release have been read back.
+
+Closeout report sections:
+
+- **Completed**: action → read-back evidence.
+- **Waiting / blocked**: object/status → next required action or authorization.
+- **Production state**: tags, pipelines/jobs, images/digests, deployments, config/runtime, worker state, and smoke/log/metric evidence actually inspected.
+- **Deferred / intentionally not done**: scripts, workers, queues, flags, migrations, or integrations not enabled or not run, with residual risk.
+- **Required user decisions**: exact MR/tag/job/config/resource plus current id/SHA/status.
+
+Evidence depth labels:
+
+- `read-back`: platform/API/CLI state was inspected.
+- `runtime-verified`: running workload or behavior was checked.
+- `documented-only`: release doc says so, but runtime/platform proof was not inspected.
+- `not-run`: explicitly not executed.
+
+Partial evidence is acceptable only when labeled honestly with the missing surfaces.

package/dist/assets/marketplace/plugins/ccl-skills/skills/release-coordination/references/release-scope-confirmation.md

@@ -0,0 +1,21 @@
+# Release Scope Confirmation Gate
+
+Before creating a production MR, asking for merge authorization, pushing a production tag, or playing a production deploy job, confirm the **actual release scope** against first-hand source-control evidence.
+
+Minimum evidence:
+
+1. Resolve the exact production target ref and release source ref.
+2. Fetch/re-read refs immediately before scope confirmation.
+3. Compare `base...release-head` using commit log, changed-file/status/stat, and line-level diff for high-risk or unclear areas.
+4. Classify user-visible capability changes and operational changes: config/defaults, migrations, scripts, jobs, workers, queues, dependencies, external integrations, feature flags, and manual steps.
+5. Compare the actual scope to the user's intended scope and the release document.
+
+Block and ask the user to re-confirm when:
+
+- The release source contains unrelated capabilities or a much broader commit/file set than intended.
+- The wrong source or target branch/ref appears to be selected.
+- The production target advanced after the scope was documented, changing the diff base.
+- Config, migration, script, worker, queue, dependency, or manual-job deltas are present but absent from the release document.
+- Evidence depth is only commit/file-level but the conclusion claims line-level or runtime verification.
+
+Do not infer scope from branch names, MR titles, prior memory, release notes, or another model's summary without checking source-control evidence. Once confirmed, route document substance to `release-doc-writer` and carry the exact scope evidence into MR/tag authorization prompts.

package/dist/assets/marketplace/plugins/ccl-skills/skills/release-coordination/references/tag-and-prod-pipeline-gate.md

@@ -0,0 +1,20 @@
+# Tag and Production Pipeline Gate
+
+Before creating or pushing a production tag:
+
+1. Resolve the exact target commit after merge.
+2. Verify the local and remote tag name does not already exist.
+3. Verify the target commit is the intended production target head.
+4. State whether the tag is expected to trigger build/deploy automatically, create manual jobs, or do nothing for each repository/service.
+
+Do not assume every repository uses the same tag rules.
+
+After pushing a tag, read back:
+
+- Remote tag target.
+- Tag pipeline existence or documented absence.
+- Pipeline/job state.
+- Manual jobs that require separate authorization.
+- Produced image/digest/version evidence when available.
+
+If the tag target is wrong after push, do not force-move a published production tag. Stop and escalate to the release owner for the corrective version/tag path.

package/dist/assets/marketplace/plugins/ccl-skills/skills/release-coordination/references/test-scope-prompt.md

@@ -0,0 +1,24 @@
+# Test Scope Prompt Handoff
+
+After release scope is confirmed, emit a test-scope prompt that helps reviewers and QA see what must be proved before release. This is a handoff, not a full test strategy.
+
+Build the prompt from the confirmed release diff:
+
+- **Capability scope**: user-visible behavior, API/contract changes, admin/operator workflows, compatibility paths.
+- **Operational scope**: config/defaults, migrations, scripts, jobs, workers, queues, dependencies, external integrations, deploy changes.
+- **Risk scope**: auth/permission, tenant/user isolation, data mutation, money/quota, async finality, irreversible actions, high-traffic or degraded-mode paths.
+- **Regression scope**: touched modules, direct consumers, known adjacent paths, frozen past failures, rollback-sensitive paths.
+- **Evidence gaps**: layers not yet run, live-only checks, unavailable environments, manual smoke owners.
+
+Output shape:
+
+```text
+Test-scope prompt:
+- Must-cover capabilities: ...
+- Operational checks: ...
+- Regression focus: ...
+- Suggested smoke: ...
+- Requires testing-strategy handoff: yes/no, because ...
+```
+
+Route to `testing-strategy` when the user needs test-layer selection, scenario matrix, fixture/mock policy, E2E versus integration decisions, executable test code, or CI gate design. Do not mark release verification complete from this prompt alone.

package/dist/assets/marketplace/plugins/ccl-skills/skills/release-coordination/references/watcher-discipline.md

@@ -0,0 +1,14 @@
+# Watcher Discipline
+
+Use watchers for long CI/build/deploy waits, but keep them bounded and read-only by default.
+
+Watcher rules:
+
+- Start only for a named object: MR/PR, pipeline, job, deploy, rollout, or health check.
+- Record object id/ref/SHA and expected stop states.
+- Poll with a timeout and a clear interval.
+- Stop on success, failure, canceled, manual/action-required, timeout, or object replacement.
+- Never play jobs, retry jobs, merge, push tags, mutate config, or delete branches from a watcher unless separately authorized for that exact action.
+- Reconcile watcher output in the main release report; do not claim completion from a stale background result without a fresh read-back when the action is sensitive.
+
+If a watcher times out, report the last observed state and the next safe action instead of continuing unbounded polling in the main thread.