@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/test-artifact-management/references/tc-review-and-prioritization.md

@@ -0,0 +1,145 @@
+# 用例评审与优先级评定
+
+写完一批 TC 之后 / release 之前的两道质量门：
+- §1 **评审**：写完 TC 怎么知道写好了（review checklist）
+- §2 **定优先级**：P0 / P1 / P2 怎么从经验判断改成可执行方法
+
+不替代 `classical-test-design-techniques.md` / `source-to-case-workflows.md` — 那两份是"怎么写"，这份是"写完之后"。
+
+## 外部来源（按名引用）
+
+- **IEEE 829** / **ISO/IEC/IEEE 29119-3:2021** test documentation lineage — TC 应含字段
+- **ISTQB CTFL** v4 syllabus — test documentation + 评审术语
+- **George Dinwiddie**（2009）— Three Amigos meeting origin
+- **Lisa Crispin & Janet Gregory** — *Agile Testing* / *More Agile Testing*（Power of Three / 全团队协作）
+- **Hans Schaefer** — *Risk Based Testing*（实务派 risk-based testing）
+- **Erik van Veenendaal** / **TMAP** — Product Risk Analysis（PRISMA 实际归属）
+- **ISTQB Advanced Test Manager** syllabus — Risk-Based Testing 章节
+- **James Bach & Michael Bolton** — Heuristic Test Strategy Model（HTSM quality criteria 作打分补充维度）
+
+---
+
+## §1 TC Review Checklist
+
+### 1.1 谁 review
+
+**第二人原则**：自己写自己看不算 review。每批 TC 必须有 1+ 第二人过：
+- **同伴 review**（任一：dev / tester / PM）：必须
+- **PO review**：当 TC 来自需求文档（Source A），PO 必须扫一遍确认"这就是我要的"
+- **架构 review**：当 TC 涉及钱 / 权限 / 数据一致性 / 跨服务关键流程
+
+### 1.2 七要素 review checklist
+
+（条目源自 IEEE 829 / ISO 29119-3 test documentation 字段 + ISTQB CTFL 静态评审术语 + 业内通用经验。review 时按 7 项打勾，任一不过 → 改完再 review。）
+
+1. **意图明确**：1 句话能说出"这条测的是什么"。说不出 → fail
+2. **操作可复现**：另一个人按步骤跑得同样结果，不依赖测者经验
+3. **预期可观察**：预期结果是外部可见输出（return value / DB 行 / 视觉变化 / 日志 / metric），不是"程序应正常运行"
+4. **数据明确**：前置条件枚举具体数据（"用户 A 已登录，角色 = admin" 而非"用户登录"）
+5. **隔离性**：TC 不依赖其他 TC 的执行顺序 / 残留状态
+6. **覆盖必要边界**：相邻有 boundary / negative / error 同伴 TC，不能 happy-only
+7. **可维护**：模块拆得清楚，重命名 / 重构后只改一处
+
+### 1.3 Three Amigos 轻量评审（Dinwiddie 2009 + Crispin/Gregory "Power of Three"）
+
+**理想**：PM（business）+ dev + tester 围一张桌子 / 视频会，每条 TC 念出来，三人都点头 → 入库。注意这是**轻量评审**用途，不是 `source-to-case-workflows.md` 故意不借鉴段所指的"全套 Spec Workshop"（那是产品过程，归 `product-rd-workflow`）。
+
+**退化**（凑不齐三人时）：tester 写完 → dev review（"按这条 TC 我开发吗？"）+ PM 异步 review（"这就是我要的？"）。两个独立角色至少各过一次。
+
+### 1.4 Review 流转
+
+- 不通过 → 评论留 Bitable 信息流转：`[reviewer 日期] review 不通过：操作步骤第 3 步歧义，请明确 X 值`
+- 改完作者主动 ping reviewer，不要让 reviewer 反复追
+- 通过 → reviewer 在 信息流转 留 `[reviewer 日期] review 通过`
+- **review 状态与执行状态分开追踪**：信息流转里用 `[作者 日期] review pending @reviewer 期待 X 月 Y 日前回复` 让 release 计划能区分"未 review"和"未执行"，避免 review 卡周级别时也混进"已就绪"统计
+
+---
+
+## §2 Risk-Based Prioritization
+
+SKILL.md 现状 P0 / P1 / P2 是经验判断（"blocking / important / nice"）。本节给可执行方法。
+
+### 2.1 风险公式（最通用）
+
+**Risk = Probability × Impact**（业内 30 年共识，ISTQB / ISO 29119 同源）
+
+**Probability**（发生概率，1-5 分）：
+- 1 = 罕见（新代码 + 简单逻辑 + 测试覆盖好）
+- 3 = 中等（已上线但近期改过 / 跨服务调用 / 复杂条件）
+- 5 = 高频（用户每天碰 / 历史多次 incident / 复杂分支 / 时间敏感）
+
+**Impact**（影响，1-5 分）：
+- 1 = 用户体感差但不丢数据 / 可解释
+- 3 = 部分用户阻塞 / 单点数据错（可改 / 可补）
+- 5 = 全量阻塞 / 钱算错 / 数据丢失 / 安全 / 合规事故
+
+**得分 → 优先级**：
+
+| Score | 优先级 |
+| --- | --- |
+| 15-25 | **P0**（必须 release 前过）|
+| 6-14 | **P1**（应当 release 前过；可豁免须 owner + 理由）|
+| 1-5 | **P2**（可 post-release）|
+
+> 分段是本团队 release-gate 校准（非公认标准）；跑 1-2 个 release 后按 incident 复盘调阈值。
+
+### 2.2 内部三因子产品风险 shortcut（启发自 PRISMA / TMAP）
+
+PRISMA / TMAP 的产品风险分析（van Veenendaal）比较深；这里取一个轻量三因子作业内日常评分用：
+
+- **业务关键性**：用户多频 / 钱 / 监管 → 高
+- **技术复杂度**：新框架 / 多线程 / 重写 / cross-cutting → 高
+- **变更程度**：本次改了多少 / 是否影响 hot path → 高
+
+三维都高 → P0；任一极高 → P1；都低 → P2。和 2.1 公式互校（不一致时讨论再定）。
+
+**当 Prob × Impact 评分太窄**（典型：架构稳定性 / 可观察性 / 可维护性 / 可恢复性 这种 horizontal 风险）：用 HTSM (Bach/Bolton) 的 quality criteria 作 prompt 补维度（**完整列表见 Bach HTSM PDF；以下是常用子集**）— capability / reliability / usability / charisma / security / scalability / performance / installability / compatibility / development（含 supportability / testability / maintainability / portability / localizability）。
+
+### 2.3 触发升级的规则
+
+默认按公式打分；以下情况无论得分都升级：
+
+| 触发 | 处理 |
+| --- | --- |
+| 历史上同模块出过 P0 incident | 该模块全部 TC 在公式得分基础上 + 1 级 |
+| 监管 / 合规要求强制覆盖 | 强制 P0 |
+| `[回归]` TC（Source E） | 自动 P0（SKILL.md 已规则） |
+| `[soap-opera]` / `[charter]` | 按真实业务风险评，**不强制 P0**（classical-techniques.md 已规则） |
+
+### 2.4 例
+
+某报告导出模块 TC list：
+```
+TC-EXPORT-001 报告导出请求成功
+  Prob 5（每天用） × Impact 5（导出失败 = 主流程断） = 25 → P0
+
+TC-AUTH-007 token 过期自动续期幂等
+  Prob 3（每天少量碰） × Impact 5（重复发起验证 / session 错位） = 15 → P0
+
+TC-DOC-020 文档预览页 footer 排版
+  Prob 5（每天看） × Impact 1（不丢数据） = 5 → P2
+```
+
+---
+
+## §3 整体落地
+
+| 阶段 | 谁 | 做 |
+| --- | --- | --- |
+| 写 TC 时 | 作者 | 按 §2 给每条打分评 P0 / P1 / P2；分数写 Bitable 信息流转 `[作者 日期] risk=4×4=16 → P0` |
+| 提 review 时 | 作者 | 按 §1.2 七要素自查；自查不过别提 review |
+| Review 时 | reviewer | 按 §1.2 七要素扫；不过留 信息流转 |
+| Review 通过 | reviewer | 信息流转留 `[reviewer 日期] review 通过`，状态可改"未测试" |
+| Release 决策 | 发布人 | P0 全过 才能 release；P1 可豁免须有 owner + 理由；P2 post-release |
+
+---
+
+## 故意不借鉴
+
+| 方法 | 原因 |
+| --- | --- |
+| ISO 29119 完整 risk catalog（含资源 / 进度 / 合规等 ~20 维） | 太重；产品风险三维够用 |
+| FMEA RPN（Severity × Occurrence × Detection） | 制造业用法，detection 在软件里难量化；用 Prob × Impact 二维 |
+| Test prioritization regression algorithms（如 history-based ML 排序） | 是 CI 自动化层面的题，归 `testing-strategy` / CI 工具 |
+| TestRail-style approval state machine | 我们 Bitable `信息流转` append-only + 状态 字段已等价 |
+| Heuristic-only review（凭感觉过） | 不可执行；用 §1.2 七要素作清单 |

package/dist/assets/marketplace/plugins/ccl-skills/skills/test-artifact-management/references/tc_helpers/AGENTS.md

@@ -0,0 +1,16 @@
+# skills/test-artifact-management/references/tc_helpers Agent Contract
+
+Helpers here map automated test results to testcase IDs and report artifacts.
+
+Rules:
+
+- Preserve collection-time testcase mapping so skipped/blocked/fixture-failed
+  tests still report to the right case.
+- Do not collapse failed, skipped, blocked, unlinked, and deprecated cases into
+  one status.
+- Keep helpers dependency-light and portable across target repos.
+- Add focused tests for marker parsing or report-shape changes.
+
+Validation:
+
+- `python3 -m pytest -q skills/test-artifact-management/references/test_gen_report.py`

package/dist/assets/marketplace/plugins/ccl-skills/skills/test-artifact-management/references/tc_helpers/tc.dart

@@ -0,0 +1,129 @@
+/// TC ID helper for Dart `test` and Flutter `flutter_test`.
+///
+/// Dart's `test()` runs the body inside a callback and does not expose the
+/// currently-running test name to the body. We solve this by wrapping
+/// `test()` and `testWidgets()` so the TC IDs are recorded at registration
+/// time (keyed by the test description).
+///
+/// Usage (pure Dart / dart test):
+/// ```dart
+/// import 'tc.dart';
+///
+/// void main() {
+///   tcTest(['TC-SY-001'], 'login success', () {
+///     // ... assertions
+///   });
+/// }
+/// ```
+///
+/// Usage (Flutter widget tests):
+/// ```dart
+/// import 'package:flutter_test/flutter_test.dart';
+/// import 'tc.dart';
+///
+/// void main() {
+///   tcTestWidgets(['TC-SY-001'], 'login form renders', (tester) async {
+///     // ... pump + expect
+///   });
+/// }
+/// ```
+///
+/// Sidecar path: `test/results/tc-map.jsonl` (override via TC_SIDECAR env).
+/// The Makefile `test` target truncates the sidecar before each run.
+
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:test/test.dart';
+
+String _sidecarPath() =>
+    Platform.environment['TC_SIDECAR'] ?? 'test/results/tc-map.jsonl';
+
+/// Parse StackTrace.current to find the caller test file path.
+/// Returns empty string when not derivable.
+String _callerTestFile() {
+  final lines = StackTrace.current.toString().split('\n');
+  final cwd = Directory.current.path + Platform.pathSeparator;
+  for (final raw in lines) {
+    final line = raw.trim();
+    // Skip own frames + dart sdk + package frames
+    if (line.contains('tc.dart:') ||
+        line.contains('tcTest ') ||
+        line.contains('_record ') ||
+        line.contains('_callerTestFile') ||
+        line.contains('(dart:') ||      // SDK frames: "(dart:async/..."
+        line.contains('(package:')) continue; // package frames
+    // Match "<...> (FILE:line:col)" or "<...> FILE:line:col"
+    final m = RegExp(r'(?:[(\s]|^)(?:file:\/\/)?([^():\s]+_test\.dart):\d+:\d+\)?').firstMatch(line);
+    if (m != null) {
+      var f = m.group(1)!;
+      if (f.startsWith(cwd)) f = f.substring(cwd.length);
+      return f;
+    }
+  }
+  return '';
+}
+
+void _record(String description, List<String> ids) {
+  if (ids.isEmpty) return;
+  final strict = const ['1', 'true', 'yes']
+      .contains((Platform.environment['TC_SIDECAR_STRICT'] ?? '').toLowerCase());
+  try {
+    final file = File(_sidecarPath());
+    file.parent.createSync(recursive: true);
+    final f = _callerTestFile();
+    final testKey = f.isNotEmpty ? '$f::$description' : description;
+    final line = jsonEncode({'test': testKey, 'tc_ids': ids});
+    file.writeAsStringSync('$line\n',
+        mode: FileMode.append, flush: true);
+  } catch (e) {
+    if (strict) rethrow;
+    // best-effort fallback (default)
+  }
+}
+
+/// Wrapper around `test()` that links the test to one or more TC IDs.
+void tcTest(
+  List<String> tcIds,
+  String description,
+  dynamic Function() body, {
+  Timeout? timeout,
+  dynamic skip,
+  dynamic tags,
+  Map<String, dynamic>? onPlatform,
+  int? retry,
+}) {
+  _record(description, tcIds);
+  test(description, body,
+      timeout: timeout,
+      skip: skip,
+      tags: tags,
+      onPlatform: onPlatform,
+      retry: retry);
+}
+
+/// Flutter-only wrapper around `testWidgets`. Importable lazily; if the host
+/// project does not depend on flutter_test, comment this out or move to a
+/// separate file `tc_widgets.dart`.
+//
+// import 'package:flutter_test/flutter_test.dart';
+//
+// void tcTestWidgets(
+//   List<String> tcIds,
+//   String description,
+//   WidgetTesterCallback body, {
+//   bool? skip,
+//   Timeout? timeout,
+//   Duration? initialTimeout,
+//   bool semanticsEnabled = true,
+//   TestVariant<Object?> variant = const DefaultTestVariant(),
+//   dynamic tags,
+// }) {
+//   _record(description, tcIds);
+//   testWidgets(description, body,
+//       skip: skip,
+//       timeout: timeout,
+//       semanticsEnabled: semanticsEnabled,
+//       variant: variant,
+//       tags: tags);
+// }

package/dist/assets/marketplace/plugins/ccl-skills/skills/test-artifact-management/references/tc_helpers/tc.go

@@ -0,0 +1,197 @@
+// Package tc records TC IDs from Go tests to a JSONL sidecar.
+//
+// Usage:
+//
+//	import "yourrepo/testkit/tc"
+//
+//	func TestLoginSuccess(t *testing.T) {
+//	    tc.Mark(t, "TC-SY-001")
+//	    // ... test body
+//	}
+//
+//	func TestBulkImportPartialFailure(t *testing.T) {
+//	    tc.Mark(t, "TC-SY-001", "TC-SY-002")
+//	    // ... test body
+//	}
+//
+// Each Mark call appends one JSONL line to test/results/tc-map.jsonl
+// (configurable via TC_SIDECAR env). gen_report.py reads the sidecar and
+// joins by t.Name(). The Makefile test target should truncate the sidecar
+// before running tests so deleted tests don't leave stale entries.
+package tc
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"sync"
+	"testing"
+)
+
+var mu sync.Mutex
+
+// testKeyFromPC returns "<package-path>::<t.Name()>" so two TestLogin functions
+// in different packages don't collide. The PC argument MUST be captured at the
+// Mark callsite (runtime.Caller(1) inside Mark) — passing it explicitly avoids
+// brittleness around helper-function inlining: if testKey/Mark were inlined,
+// a fixed runtime.Caller(2) inside testKey would skip past the user's frame.
+//
+// Subtest closures register as "<pkg>.<TestName>.func1[.<n>...]" via
+// runtime.FuncForPC. We strip every trailing segment until we land on a test
+// entry function (prefix Test/Benchmark/Example/Fuzz), then strip ONCE more
+// to drop the test name and reveal the package path.
+//
+// If no Test* entry is ever found in the chain, the PC almost certainly
+// pointed at a wrapper helper (wrong extraSkip in MarkAt). In that case we
+// log loudly and — under TC_SIDECAR_STRICT — fail the test, because a
+// silently-wrong key turns a passing test into untracked and the bug only
+// surfaces during report review.
+func testKeyFromPC(t *testing.T, pc uintptr) string {
+	t.Helper()
+	name := t.Name()
+	fn := runtime.FuncForPC(pc)
+	if fn == nil {
+		warnBadFrame(t, "runtime.FuncForPC returned nil — wrong extraSkip in MarkAt?")
+		return name
+	}
+	full := fn.Name()
+	original := full
+	foundEntry := false
+	// Strip trailing segments until the last segment is a test entry.
+	for {
+		i := strings.LastIndex(full, ".")
+		if i < 0 {
+			break
+		}
+		last := full[i+1:]
+		if isTestEntry(last) {
+			full = full[:i] // drop the test name → leave package path
+			foundEntry = true
+			break
+		}
+		full = full[:i] // drop closure / numeric / func suffix and keep going
+	}
+	if !foundEntry {
+		warnBadFrame(t, "no Test*/Benchmark*/Example*/Fuzz* entry found in PC chain "+
+			"(captured "+original+"). Wrong extraSkip in MarkAt? "+
+			"If using a project wrapper, count how many helpers sit between the "+
+			"test and MarkAt; that's the extraSkip value.")
+		return name
+	}
+	if full == "" {
+		return name
+	}
+	return full + "::" + name
+}
+
+// warnBadFrame surfaces a wrong-frame attribution. Under TC_SIDECAR_STRICT
+// this becomes a test failure so CI catches the bug instead of silently
+// recording a sidecar key that won't join JUnit.
+func warnBadFrame(t *testing.T, msg string) {
+	t.Helper()
+	if strictMode() {
+		t.Fatalf("tc.MarkAt frame attribution failed: %s (TC_SIDECAR_STRICT=1)", msg)
+	} else {
+		t.Logf("⚠ tc.MarkAt frame attribution failed: %s", msg)
+	}
+}
+
+func isTestEntry(s string) bool {
+	return strings.HasPrefix(s, "Test") ||
+		strings.HasPrefix(s, "Benchmark") ||
+		strings.HasPrefix(s, "Example") ||
+		strings.HasPrefix(s, "Fuzz")
+}
+
+// Mark links the currently-running test to one or more TC IDs.
+// Safe under t.Parallel(); does not fail the test on I/O error (logged via t.Logf).
+//
+// MUST be called before any t.Skip / t.Skipf / setup that may call t.Fatal —
+// otherwise the sidecar entry is not written for that test.
+//
+// DO NOT wrap Mark in a project-local helper without using MarkAt: the
+// package-path detection reads the caller's PC, which would point to your
+// wrapper's package instead of the test's package, producing wrong sidecar
+// keys that don't join JUnit's classname.
+func Mark(t *testing.T, ids ...string) {
+	t.Helper()
+	if len(ids) == 0 {
+		return
+	}
+	pc, _, _, _ := runtime.Caller(1) // caller of Mark = user test
+	markPC(t, pc, ids...)
+}
+
+// MarkAt lets a project-local wrapper register TC IDs while still attributing
+// them to the USER's test (not the wrapper's package). `extraSkip` is the
+// number of caller frames between the user's test code and the call to MarkAt.
+//
+// Examples:
+//
+//	// Single wrapper: TestX → Smoke → MarkAt; extraSkip = 1 (skip Smoke).
+//	func Smoke(t *testing.T, ids ...string) {
+//	    t.Helper()
+//	    tc.MarkAt(t, 1, ids...)
+//	}
+//
+//	// Two-level wrapper: TestX → Smoke → InnerMark → MarkAt; extraSkip = 2.
+func MarkAt(t *testing.T, extraSkip int, ids ...string) {
+	t.Helper()
+	if len(ids) == 0 {
+		return
+	}
+	// depth 0 = MarkAt; depth 1 = caller of MarkAt (the wrapper);
+	// depth 1+extraSkip = the user's test (one extra hop per wrapper frame).
+	pc, _, _, _ := runtime.Caller(1 + extraSkip)
+	markPC(t, pc, ids...)
+}
+
+// markPC is the shared implementation. PC must already point at the user's
+// test frame (so the package-path strip resolves to the test's package).
+func markPC(t *testing.T, pc uintptr, ids ...string) {
+	t.Helper()
+	path := os.Getenv("TC_SIDECAR")
+	if path == "" {
+		path = "test/results/tc-map.jsonl"
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	strict := strictMode()
+	fail := func(err error, what string) {
+		// Mark the closure as a helper too, so t.Fatalf credits the test
+		// callsite (the line that invoked tc.Mark), not tc.go.
+		t.Helper()
+		if strict {
+			t.Fatalf("tc.Mark: %s: %v (TC_SIDECAR_STRICT=1)", what, err)
+		}
+		t.Logf("tc.Mark: %s: %v", what, err)
+	}
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		fail(err, "mkdir "+filepath.Dir(path))
+		return
+	}
+	f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
+	if err != nil {
+		fail(err, "open "+path)
+		return
+	}
+	defer f.Close()
+	entry := map[string]any{"test": testKeyFromPC(t, pc), "tc_ids": ids}
+	line, err := json.Marshal(entry)
+	if err != nil {
+		fail(err, "marshal")
+		return
+	}
+	if _, err := f.Write(append(line, '\n')); err != nil {
+		fail(err, "write "+path)
+	}
+}
+
+// strictMode returns true when TC_SIDECAR_STRICT=1|true|yes — sidecar write
+// failures become test failures instead of best-effort log lines.
+func strictMode() bool {
+	v := strings.ToLower(os.Getenv("TC_SIDECAR_STRICT"))
+	return v == "1" || v == "true" || v == "yes"
+}

package/dist/assets/marketplace/plugins/ccl-skills/skills/test-artifact-management/references/tc_helpers/tc.py

@@ -0,0 +1,135 @@
+"""
+TC ID helper for pytest.
+
+Link a test to one or more TC IDs using the `@pytest.mark.tc(...)` marker.
+Recorded at collection time, so `@skip`, `@skipif`, `xfail`, and fixture
+failures all map to Bitable status correctly:
+
+    @pytest.mark.tc("TC-SY-001")
+    @pytest.mark.skipif(sys.platform != "linux", reason="requires linux")
+    def test_login_success():
+        assert ...
+
+    @pytest.mark.tc("TC-SY-001", "TC-SY-002")
+    def test_bulk_import_partial_failure():
+        ...
+
+For TC IDs computed at runtime (property-based tests, ID derived from input),
+the in-body `tc("TC-...")` form is available — it records only when the body
+actually runs, so skipped tests are not covered:
+
+    def test_dynamic():
+        tc(decide_tc_id())
+        ...
+
+Each registration appends one JSONL line to `test/results/tc-map.jsonl`
+(configurable via `TC_SIDECAR` env). gen_report.py joins JUnit XML against
+the sidecar by pytest nodeid (e.g. `tests/test_auth.py::test_login_success`).
+
+## Install
+
+1. Drop this file at `<project>/test/tc.py` (or anywhere on pythonpath).
+2. In pytest config (`pyproject.toml` or `pytest.ini`), make it importable and
+   register it as a plugin:
+
+       [tool.pytest.ini_options]
+       pythonpath = ["test"]
+       addopts = ["-p", "tc"]
+
+   Or in `pytest.ini`:
+
+       [pytest]
+       pythonpath = test
+       addopts = -p tc
+
+3. In test files: `import pytest` and use `@pytest.mark.tc(...)`. For the
+   rare dynamic-ID case, `from tc import tc` and call `tc(...)` in the body.
+   Markers and in-body calls compose — gen_report.py merges duplicates.
+
+4. The Makefile `test` target truncates the sidecar before each run (so
+   deleted tests do not leave stale entries).
+
+5. Set `TC_SIDECAR_STRICT=1` in CI so sidecar write failures fail the test
+   (otherwise a permission/disk error silently leaves Bitable stale while
+   CI passes).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from pathlib import Path
+
+import pytest
+
+_lock = threading.Lock()
+
+
+def _sidecar_path() -> Path:
+    return Path(os.environ.get("TC_SIDECAR", "test/results/tc-map.jsonl"))
+
+
+def _append_entry(test_name: str, ids: list[str]) -> None:
+    """Append one JSONL line for (test_name, ids). Safe under thread parallelism.
+
+    Best-effort by default (CI sidecar write failures don't fail the test).
+    Set TC_SIDECAR_STRICT=1 (recommended in CI) to raise on write failure —
+    otherwise a permissions/disk error silently turns linked tests into
+    untracked tests and Bitable goes stale while CI passes.
+    """
+    if not ids or not test_name:
+        return
+    path = _sidecar_path()
+    line = json.dumps({"test": test_name, "tc_ids": list(ids)}, ensure_ascii=False)
+    strict = os.environ.get("TC_SIDECAR_STRICT", "").lower() in ("1", "true", "yes")
+    try:
+        with _lock:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            with path.open("a", encoding="utf-8") as f:
+                f.write(line + "\n")
+    except OSError:
+        if strict:
+            raise
+
+
+def _current_test_nodeid() -> str:
+    raw = os.environ.get("PYTEST_CURRENT_TEST", "")
+    return raw.split(" ")[0] if raw else ""
+
+
+def tc(*ids: str) -> None:
+    """Record TC IDs at runtime from inside a test body. Use only when the IDs
+    are computed (property-based tests, parameterised inputs that produce
+    different TCs per run). For static TC mapping use @pytest.mark.tc(...).
+
+    Skipped tests / fixture failures don't reach the body, so this form
+    cannot register them — the marker form is the answer for those cases.
+    """
+    if not ids:
+        return
+    _append_entry(_current_test_nodeid(), list(ids))
+
+
+# ── pytest plugin: marker registration + collection-time sidecar write ──────
+
+def pytest_configure(config):
+    config.addinivalue_line(
+        "markers",
+        "tc(*ids): link this test to one or more TC IDs (e.g. @pytest.mark.tc(\"TC-SY-001\")). "
+        "Recorded at collection time so @skip / fixture failures still register correctly.",
+    )
+
+
+def pytest_collection_modifyitems(config, items):
+    """Record TC IDs from @pytest.mark.tc markers at collection time.
+    This catches @skip / @skipif / setup-failure cases (the test body never
+    runs in those, so the in-body tc() call wouldn't be reached)."""
+    for item in items:
+        ids: list[str] = []
+        for marker in item.iter_markers(name="tc"):
+            for arg in marker.args:
+                if isinstance(arg, str) and arg:
+                    ids.append(arg)
+        if ids:
+            _append_entry(item.nodeid, ids)