@ccoalm/ccl-skills 0.8.0 → 0.10.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/check-contract-anchors.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# Contract-anchor gate: declarative wording-existence pinning for load-bearing
+# prose contracts that no structural check would otherwise protect.
+#
+# Problem class (observed, 074 RED-baseline probes): a skill reference's
+# load-bearing contract sentence — a verdict-taxonomy discriminator, a
+# stop-condition predicate, an externally verified numeric tier — can be
+# deleted, semantically inverted, or numerically falsified while every
+# structural gate stays green, because structural gates check shape and
+# references, never the survival of specific contract wording.
+#
+# Mechanism: a sidecar TSV table (contract-anchors.tsv, same directory) lists
+# one anchor per row:  id <TAB> repo-relative path <TAB> pinned literal <TAB> note
+#   - the literal must occur EXACTLY ONCE in the named file (fixed-string match).
+#     0 occurrences  => contract_anchor_missing    (drift/deletion)      exit 1
+#     >1 occurrences => contract_anchor_duplicate  (decoy/ambiguity;
+#       an anchor that matches twice can no longer prove which copy is the
+#       contract — same rule as the sync-pointer registry)                exit 1
+#   - a missing anchored file is a broken contract, not infrastructure:
+#     contract_anchor_file_missing                                        exit 1
+# Table integrity is fail-closed (exit 2, infra): unreadable/empty table
+# (an empty list scanning nothing must never certify), malformed row,
+# duplicate id, or a literal under 16 characters (too weak to be unique —
+# same floor as firing-path anchors).
+#
+# All rows are scanned before any exit: anchor-drift findings (rc 1) and
+# row-integrity findings (rc 2) are each collected across the whole table, so
+# one run reports every problem; when both classes are present the run exits 2
+# (a broken table means no verdict can be trusted). Green output grammar is
+# pinned for the caller:
+#   contract_anchor_gate_ok (N anchors)
+# Exemptions: none, and deliberately no environment override — an anchor is
+# removed or reworded only by editing the table in the same MR that changes
+# the pinned wording (reject-and-instruct failure message points there).
+#
+# Intentional-change recipe (printed on failure): edit the contract sentence
+# AND its table row together; the diff then shows the contract change
+# explicitly instead of a silent drift.
+set -u
+
+script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)
+root="${1:-.}"
+table="$script_dir/contract-anchors.tsv"
+if [[ "${2:-}" == "--table" && -n "${3:-}" ]]; then
+  table="$3"
+fi
+
+if [[ ! -d "$root" ]]; then
+  echo "contract_anchor_root_missing: $root" >&2
+  exit 2
+fi
+if [[ ! -f "$table" ]]; then
+  echo "contract_anchor_table_missing: $table" >&2
+  exit 2
+fi
+
+anchor_count=0
+fail_count=0
+infra_count=0
+# Bash 3.2-safe id-uniqueness set (stock macOS bash has no associative arrays):
+# newline-delimited membership string, ids are TSV fields so they carry no tabs
+# and no newlines.
+seen_ids=$'\n'
+line_no=0
+while IFS= read -r raw || [[ -n "$raw" ]]; do
+  line_no=$((line_no + 1))
+  [[ -z "$raw" || "$raw" == \#* ]] && continue
+  IFS=$'\t' read -r id path literal note <<<"$raw"
+  if [[ -z "${id:-}" || -z "${path:-}" || -z "${literal:-}" || -z "${note:-}" ]]; then
+    echo "contract_anchor_row_malformed: line $line_no of $table (need id<TAB>path<TAB>literal<TAB>note)" >&2
+    infra_count=$((infra_count + 1))
+    continue
+  fi
+  if [[ "$note" == *$'\t'* ]]; then
+    echo "contract_anchor_row_malformed: line $line_no of $table (extra tab-separated field)" >&2
+    infra_count=$((infra_count + 1))
+    continue
+  fi
+  case "$seen_ids" in
+    *$'\n'"$id"$'\n'*)
+      echo "contract_anchor_duplicate_id: $id (line $line_no repeats an earlier row's id)" >&2
+      infra_count=$((infra_count + 1))
+      continue
+      ;;
+  esac
+  seen_ids="$seen_ids$id"$'\n'
+  if (( ${#literal} < 16 )); then
+    echo "contract_anchor_literal_too_short: $id (${#literal} chars, need >=16)" >&2
+    infra_count=$((infra_count + 1))
+    continue
+  fi
+  anchor_count=$((anchor_count + 1))
+  target="$root/$path"
+  fix_line="  fix: restore the contract wording, or — for an intentional contract change — update this anchor row in $(basename "$table") in the same MR"
+  if [[ ! -f "$target" ]]; then
+    echo "contract_anchor_file_missing: $id $path" >&2
+    echo "  fix: restore the anchored file, or — for an intentional move/retirement — update or remove this anchor row in $(basename "$table") in the same MR" >&2
+    fail_count=$((fail_count + 1))
+    continue
+  fi
+  occurrences=$(grep -oF -- "$literal" "$target" | wc -l | tr -d '[:space:]')
+  if [[ "$occurrences" -eq 0 ]]; then
+    echo "contract_anchor_missing: $id in $path" >&2
+    echo "  pinned literal: $literal" >&2
+    echo "$fix_line" >&2
+    fail_count=$((fail_count + 1))
+  elif [[ "$occurrences" -gt 1 ]]; then
+    echo "contract_anchor_duplicate: $id in $path ($occurrences occurrences; the anchor can no longer prove which copy is the contract)" >&2
+    echo "  fix: keep the pinned wording in exactly one place (dedupe the copy), or repin the anchor row in $(basename "$table") to a longer unique literal in the same MR" >&2
+    fail_count=$((fail_count + 1))
+  fi
+done < "$table"
+
+if [[ "$infra_count" -gt 0 ]]; then
+  echo "contract_anchor_table_invalid: $infra_count integrity error(s) in $table (no verdict from a broken table — fail-closed)" >&2
+  exit 2
+fi
+if [[ "$anchor_count" -eq 0 ]]; then
+  echo "contract_anchor_table_empty: $table has no data rows (an empty anchor set must never certify)" >&2
+  exit 2
+fi
+if [[ "$fail_count" -gt 0 ]]; then
+  echo "contract_anchor_gate_failed: $fail_count of $anchor_count anchors" >&2
+  exit 1
+fi
+echo "contract_anchor_gate_ok ($anchor_count anchors)"

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/check-size-budget.sh

@@ -21,6 +21,18 @@
 #     advisory = no signal). A agent-context/session-start.md absent from base is treated as a NEW
 #     every-session injection and blocks like a new severe entrypoint.
 #
+# Blocking (delta-scoped, skills/*/references/**/*.md — the reference-file line
+#   ratchet; design invariants in references/attention-budget-ratchet.md):
+#   - a changed reference that is NEW or CROSSES over 500 physical lines (base
+#     was not over)               => block ("new reference over line budget")
+#   - a changed reference already over 500 lines in base that GREW
+#     (head_lines > base_lines)   => block ("over-limit reference grew")
+#   references/source-register.md is structurally excluded (append-only ledger;
+#   its growth is governed by the append-only contract, not a line cap) — the
+#   exclusion lives in this gate, never in the candidate. A NEW reference over
+#   100 lines with no "##" section headings draws an advisory token (never
+#   blocks). Rename credit is path-paired and non-growing, same as entrypoints.
+#
 # Advisory (never blocks on its own): the recommended-band body-char debt
 # counters, severe-debt counters, per-file deltas, and the agent-context/session-start.md 13000B
 # byte tripwire BAND remain VISIBILITY / DEBT-MANAGEMENT only (the band flags the
@@ -113,6 +125,11 @@ end
 WORD_BUDGET_MAX = 5000
 WORD_TOKEN_PATTERN = /\p{Han}|\uFFFD|(?:(?!\p{Han})[\p{L}\p{N}])+(?:[\u0027\u2019_-](?:(?!\p{Han})[\p{L}\p{N}])+)*/u
 
+REF_LINE_MAX = 500
+REF_NAV_MIN_LINES = 100
+REF_PATH_RE = %r{\Askills/[^/]+/references/.+\.md\z}
+REF_LEDGER_RE = %r{\Askills/[^/]+/references/source-register\.md\z}
+
 Metric = Struct.new(:body_chars, :body_words, :bytes, keyword_init: true)
 
 def metric_for_text(text)
@@ -195,6 +212,42 @@ def head_metric_for_path(root, rel)
   metric_for_file(full)
 end
 
+def ref_info_for_text(raw)
+  text = raw.b.dup.force_encoding(Encoding::UTF_8).scrub { |invalid| "�" * invalid.bytesize }
+  # Line-ending normalization comes first: a CR-only or CRLF file must measure the
+  # same as the LF file a reader sees, otherwise a 501-line CR-delimited file reads
+  # as one line and earns a clean verdict. Headings count EXACT H2 only, because an
+  # H3-only file gives a chunked read no section structure to navigate by.
+  text = text.gsub(/\r\n?/, "\n")
+  lines = text.lines
+  { lines: lines.length, headings: lines.count { |l| l.match?(/\A##[ \t]/) } }
+end
+
+def base_ref_info_for_path(root, base, rel)
+  return :unknown if base.nil?
+  return :missing unless git_success?("cat-file", "-e", "#{base}:#{rel}", root: root)
+  ref_info_for_text(git_text("show", "#{base}:#{rel}", root: root))
+end
+
+def head_ref_info_for_path(root, rel)
+  full = File.join(root, rel)
+  return :missing unless File.file?(full)
+  ref_info_for_text(File.binread(full))
+end
+
+def fmt_ref_value(info)
+  case info
+  when :unknown then "unknown"
+  when :missing then "missing"
+  else info[:lines].to_s
+  end
+end
+
+def fmt_ref_delta(base_info, head_info)
+  return "unknown" unless base_info.is_a?(Hash) && head_info.is_a?(Hash)
+  format("%+d", head_info[:lines] - base_info[:lines])
+end
+
 def fmt_metric_value(metric, field)
   case metric
   when :unknown then "unknown"
@@ -437,6 +490,144 @@ if bootstrap_changed
   # :missing (deleted) => nothing left to size-gate, same as a deleted entrypoint
 end
 
+# --- reference-file line-budget ratchet (delta-scoped) ------------------------
+# Design invariants: references/attention-budget-ratchet.md. Physical lines are
+# the stable proxy metric; the append-only ledger references/source-register.md
+# is excluded by gate design (its growth is governed by the append-only
+# contract) and the exclusion lives HERE so a candidate cannot nominate its own
+# exemption.
+ref_blocks = []
+ref_partials = []
+ref_changed = []
+ref_scan_error = nil
+begin
+  if system("git", "-C", root, "rev-parse", "--is-inside-work-tree", out: File::NULL, err: File::NULL)
+    rpaths = []
+    rpaths.concat(git_lines("diff", "--name-only", base, "HEAD", "--", "skills", root: root)) if base
+    rpaths.concat(git_lines("diff", "--name-only", "--", "skills", root: root))
+    rpaths.concat(git_lines("diff", "--cached", "--name-only", "--", "skills", root: root))
+    rpaths.concat(git_lines("ls-files", "--others", "--exclude-standard", "--", "skills", root: root))
+    ref_changed = rpaths.select { |p| p.match?(REF_PATH_RE) }.reject { |p| p.match?(REF_LEDGER_RE) }.uniq
+  end
+rescue StandardError => e
+  ref_scan_error = "#{e.class.name} #{e.message.lines.first.to_s.strip}"
+  warn "changed_reference_line_scan_skipped: #{ref_scan_error}"
+end
+# A scan failure must not silently read as "no references changed" — that would
+# false-green a real growth, so it fails closed as a partial.
+ref_partials << "skills/*/references: changed-detection failed (#{ref_scan_error}) — line-budget check unavailable (fail-closed)" if ref_scan_error
+
+ref_move_map = {}
+begin
+  if system("git", "-C", root, "rev-parse", "--is-inside-work-tree", out: File::NULL, err: File::NULL)
+    status_args = []
+    status_args << ["diff", "--name-status", base, "HEAD"] if base
+    status_args << ["diff", "--name-status", "--cached"]
+    status_args << ["diff", "--name-status"]
+    status_args.each do |cmd|
+      git_lines(*cmd, "--", "skills", root: root).each do |line|
+        status, *paths = line.split("\t")
+        next unless status.start_with?("R") && paths.length >= 2
+        next unless status[1..].to_i >= 90
+        old_rel = paths[0].match?(REF_PATH_RE) ? paths[0] : nil
+        new_rel = paths[1].match?(REF_PATH_RE) ? paths[1] : nil
+        ref_move_map[new_rel] = old_rel if old_rel && new_rel
+      end
+    end
+  end
+rescue StandardError => e
+  warn "reference_move_pair_scan_skipped: #{e.class.name}"
+end
+
+# The census is visibility only, so an unreadable or vanished file must degrade the
+# COUNTER to unknown rather than abort the program: aborting here would skip the
+# per-file fail-closed partials below and emit no verdict token at all.
+head_ref_over_count = 0
+head_ref_census_error = nil
+begin
+  Dir[File.join(root, "skills", "*", "references", "**", "*.md")].each do |path|
+    rel = path.start_with?(root + "/") ? path[(root.length + 1)..] : path.sub(%r{\A\./}, "")
+    next unless rel.match?(REF_PATH_RE)
+    next if rel.match?(REF_LEDGER_RE)
+    info = begin
+      head_ref_info_for_path(root, rel)
+    rescue StandardError => e
+      head_ref_census_error ||= "#{rel}: #{e.class.name}"
+      next
+    end
+    head_ref_over_count += 1 if info.is_a?(Hash) && info[:lines] > REF_LINE_MAX
+  end
+rescue StandardError => e
+  head_ref_census_error ||= e.class.name
+end
+if head_ref_census_error
+  warn "reference_line_census_partial: head over-limit census incomplete (#{head_ref_census_error}) — counter reported unknown; per-file verdicts below are unaffected"
+  head_ref_over_count = nil
+end
+base_ref_over_count = nil
+if base
+  begin
+    base_ref_over_count = 0
+    git_lines("grep", "-c", "-e", "", base, "--", "skills", root: root).each do |line|
+      rest, _, cnt = line.rpartition(":")
+      _, _, rel = rest.partition(":")
+      next unless rel.match?(REF_PATH_RE)
+      next if rel.match?(REF_LEDGER_RE)
+      base_ref_over_count += 1 if cnt.to_i > REF_LINE_MAX
+    end
+  rescue StandardError => e
+    base_ref_over_count = nil
+    warn "reference_line_trend_partial: base=unknown reason=#{e.class.name}"
+  end
+end
+puts "reference_line_over_limit_count_base=#{base_ref_over_count.nil? ? "unknown" : base_ref_over_count}"
+puts "reference_line_over_limit_count_head=#{head_ref_over_count.nil? ? "unknown" : head_ref_over_count}"
+puts "reference_line_over_limit_count_delta=#{(base_ref_over_count.nil? || head_ref_over_count.nil?) ? "unknown" : format("%+d", head_ref_over_count - base_ref_over_count)}"
+
+# Ledger visibility: excluded from the ratchet, still reported when over.
+Dir[File.join(root, "skills", "*", "references", "source-register.md")].sort.each do |path|
+  rel = path.start_with?(root + "/") ? path[(root.length + 1)..] : path.sub(%r{\A\./}, "")
+  info = begin
+    head_ref_info_for_path(root, rel)
+  rescue StandardError
+    :missing
+  end
+  if info.is_a?(Hash) && info[:lines] > REF_LINE_MAX
+    puts "reference_line_budget_ledger_excluded: #{rel} lines=#{info[:lines]} — append-only ledger, excluded by gate design (growth governed by the append-only contract)"
+  end
+end
+
+ref_changed.sort.each do |rel|
+  begin
+    head_info = head_ref_info_for_path(root, rel)
+  rescue StandardError => e
+    ref_partials << "#{rel}: head lines unreadable (#{e.class.name}) — line-budget check unavailable (fail-closed)"
+    next
+  end
+  next if head_info == :missing # deleted reference: nothing left to gate
+  base_info = base_ref_info_for_path(root, base, rel)
+  puts "changed_reference_line_delta: #{rel} base_lines=#{fmt_ref_value(base_info)} head_lines=#{head_info[:lines]} delta_lines=#{fmt_ref_delta(base_info, head_info)}"
+  if base_info == :missing && head_info[:lines] > REF_NAV_MIN_LINES && head_info[:headings].zero?
+    warn "reference_nav_advisory: #{rel} lines=#{head_info[:lines]} headings=0 — a new reference over #{REF_NAV_MIN_LINES} lines needs ## section structure so chunked reads and greps can navigate (advisory, never blocks)"
+  end
+  next unless head_info[:lines] > REF_LINE_MAX
+  if base_info == :unknown
+    ref_partials << "#{rel}: base unknown — reference line-budget check unavailable (fail-closed)"
+  elsif base_info == :missing || base_info[:lines] <= REF_LINE_MAX
+    source_rel = ref_move_map[rel]
+    source_info = source_rel ? base_ref_info_for_path(root, base, source_rel) : nil
+    if source_info.is_a?(Hash) && source_info[:lines] > REF_LINE_MAX && head_info[:lines] <= source_info[:lines]
+      puts "reference_line_budget_move_ok: #{rel} head_lines=#{head_info[:lines]} allowed_lines=#{source_info[:lines]} moved_from=#{source_rel}"
+    else
+      ref_blocks << "#{rel}: new reference over line budget head_lines=#{head_info[:lines]} (> #{REF_LINE_MAX}) — split it by subtopic before landing (see references/attention-budget-ratchet.md; there is no exempt marker or waiver flag)"
+    end
+  elsif head_info[:lines] > base_info[:lines]
+    ref_blocks << "#{rel}: over-limit reference grew base_lines=#{base_info[:lines]} head_lines=#{head_info[:lines]} — shrink or stay level; fund additions by consolidating text in the same file"
+  else
+    puts "reference_line_budget_legacy_ok: #{rel} base_lines=#{base_info[:lines]} head_lines=#{head_info[:lines]} allowed_lines=#{base_info[:lines]}"
+  end
+end
+
 # Advisory markers only when the blocking verdict is clean — a consumer reading
 # the preserved legacy token must never see ok next to a block.
 #
@@ -451,18 +642,20 @@ end
 # — but the token says un-evaluated, not ok.
 # NOTE: this comment lives inside the single-quoted `ruby -e` program; an
 # apostrophe here terminates the shell quote and breaks the script.
-if blocks.empty? && partials.empty? && word_blocks.empty? && word_partials.empty?
+if blocks.empty? && partials.empty? && word_blocks.empty? && word_partials.empty? && ref_blocks.empty? && ref_partials.empty?
   puts "size_budget_advisory_#{size_state}"
   puts "entrypoint_size_budget_advisory_ok"
   if base.nil?
     puts "entrypoint_size_blocking_unevaluated: base=unknown — committed changes were NOT delta-checked; this is not a pass"
     puts "entrypoint_word_budget_blocking_unevaluated: base=unknown — committed changes were NOT delta-checked; this is not a pass"
+    puts "reference_line_budget_blocking_unevaluated: base=unknown — committed changes were NOT delta-checked; this is not a pass"
     if File.file?(File.join(root, "agent-context/session-start.md"))
       puts "bootstrap_size_delta_unevaluated: base=unknown — agent-context/session-start.md committed changes were NOT delta-checked; this is not a pass"
     end
   else
     puts "entrypoint_size_blocking_ok"
     puts "entrypoint_word_budget_blocking_ok"
+    puts "reference_line_budget_blocking_ok"
   end
   exit 0
 end
@@ -470,7 +663,10 @@ blocks.each { |b| warn "entrypoint_size_block: #{b}" }
 partials.each { |b| warn "entrypoint_size_block_partial: #{b}" }
 word_blocks.each { |b| warn "entrypoint_word_budget_block: #{b}" }
 word_partials.each { |b| warn "entrypoint_word_budget_block_partial: #{b}" }
+ref_blocks.each { |b| warn "reference_line_block: #{b}" }
+ref_partials.each { |b| warn "reference_line_block_partial: #{b}" }
 puts "entrypoint_word_budget_blocking_failed" unless word_blocks.empty? && word_partials.empty?
+puts "reference_line_budget_blocking_failed" unless ref_blocks.empty? && ref_partials.empty?
 # Legacy aggregate token for every blocking verdict owned by this size-budget
 # script, including the body-word rule. Keep it unconditional so existing
 # consumers cannot miss a new word-only failure.

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/contract-anchors.tsv

@@ -0,0 +1,15 @@
+# Contract-anchor table for check-contract-anchors.sh (same directory).
+# One row per pinned load-bearing contract literal:
+#   id <TAB> repo-relative path <TAB> pinned literal (exactly-once, >=16 chars) <TAB> note
+# The note names the sanitized provenance label and why the wording is load-bearing.
+# To change pinned wording intentionally: edit the contract sentence AND this row
+# in the same MR. Keep this set small — load-bearing contracts only, never style.
+verdict-taxonomy-discriminator	skills/testing-strategy/references/ci-fixtures-and-flake-control.md	One discriminating predicate decides the verdict	071-chainA-r1f1: fault-origin discriminator sentence; deleting it reverts verdicts to case-by-case judgment
+verdict-taxonomy-false-green	skills/testing-strategy/references/ci-fixtures-and-flake-control.md	excludes `infra-error` cases to present a clean total is a false-green report	071-chainA-r1f1: report-completeness clause; deleting it legalizes infra-error-excluding clean totals
+stop-predicate-materially-differing	skills/product-rd-workflow/SKILL.md	materially differing viable approaches (none dominant-and-reversible)	071-chainB-r1f1: stop-condition predicate wording; inverting it flips blocked/continue classification
+stop-predicate-evidenced-cause	skills/product-rd-workflow/SKILL.md	a fix lacking evidenced cause	071-chainB-r1f1: stop-condition predicate wording; weakening it admits plausible-but-unevidenced fixes
+burn-rate-tiers-entry	skills/platform-observability/SKILL.md	page 14.4× 1h/5m, page 6× 6h/30m, ticket 1× 3d/6h	071-chainC-r1f4: SRE Workbook multiwindow tiers, externally verified value (specs/071 source-verification); silent renumbering must not pass
+burn-rate-page-row-reference	skills/platform-observability/references/sli-slo-design.md	| Page (P0) | 1h | 5m | 14.4 |	071-chainC-r1f4: reference-side copy of the page tier; pinning both sides makes entry/reference drift visible
+coverage-tier-provenance	skills/testing-strategy/references/test-code-authoring-patterns.md	60% acceptable / 75% commendable / 90% exemplary 分档	071-chainC-r1f4: externally verified coverage tiers (specs/071 source-verification)
+pairwise-trigger-range	skills/test-artifact-management/references/classical-test-design-techniques.md	2-way 累计触发 53–97%	071-chainC-r1f4: NIST SP 800-142 empirical range, externally verified (specs/071 source-verification)
+bva-two-vs-three-value	skills/test-artifact-management/references/classical-test-design-techniques.md	2-value（边界 + 下一格）和 3-value（边界 + 两侧）	071-chainC-r1f4: ISTQB v4 BVA variant definitions, externally verified (specs/071 source-verification)