feat(debt): adopt // sin-debt: <ceiling>, upgrade: <trigger> marker convention

[Delqhi]

Summary

Adopts ponytail v4.7.0's ponytail: marker convention as a first-class,
parseable // sin-debt: <ceiling>, upgrade: <trigger> convention for
SIN-Code (issue #177). Every intentional shortcut in source code now
carries a marker naming its ceiling and the trigger to revisit.

Components

internal/sindept/ package (cmd/sin-code/internal/sindept/)

• parser.go — Marker{File,Line,Column,Reason,Upgrade,HasUpg,Raw,Language,Symbol},
  precompiled regex over five comment families (//, #, --, /* */, <!-- -->),
  ParseFile + ParseDir. Trims trailing block-comment closers (*/, -->)
  from captured clauses for byte-deterministic output. Best-effort Symbol
  resolver walks up to 40 lines for func name(...) / def name(...).
• stats.go — Stats{Total, WithUpgrade, WithoutUpgrade, ByFile, ByReason, ByLanguage, BySymbol, RotRisk, Oldest, MarkersPerFile}. Every map is
  materialized as a lex-sorted []KV so reports are stable.
• report.go — RenderStats / RenderStatsString / RenderListString
  with FormatVersion = "sin-debt/v1". Two scans of the same tree emit
  the same bytes — the precondition for the four-arm comparator
  golden snapshot (issue feat(eval): three-arm eval harness (baseline/terse/<skill>) with --compare and snapshot round-trip #171).
• policy.go — Policy{DefaultReasons, UpgradeTriggers, MaxNoUpgrade, RequireUpgrade, Source}. TOML overlay via .sin-code/debt-policy.toml.
  LoadPolicyForRoot walks upward to the closest file. Default policy
  ships 21 reason phrases + 8 upgrade triggers.

debt_cmd.go — 41st subcommand

sin-code debt list | stats | check | policy | fix | export with shared
flags (--path, --format table|json, --no-trigger). stats takes
--by file|reason|language|symbol|age|summary. check exits non-zero
when Missing > MaxNoUpgrade or RequireUpgrade=true && Missing > 0.

Documentation

• docs/sin-debt-convention.md — author-facing reference
• cmd/sin-code/debt_cmd.doc.md — CLI reference
• cmd/sin-code/internal/sindept/sindept.doc.md — package internals
• AGENTS.md §6 (layout) + §10 (naming/stability) — sin-debt section + roadmap entry
• CHANGELOG.md — Unreleased entry

Permission defaults (internal/permission_defaults.go)

Tool pattern	Policy	Reason
sindept__list, sindept__stats, sindept__policy	allow	read-only scanner
sindept__check, sindept__fix, sindept__export	ask	visible signal / writes file

Real markers placed in production code

• cmd/sin-code/internal/orchestrator/dispatcher.go — global mutex (plan-level state)
• cmd/sin-code/internal/lessons/store.go:173 — 16-hex fingerprint collision
• cmd/sin-code/internal/lessons/store.go:181 — linear Briefing scan
• cmd/sin-code/internal/ledger/store.go:173 — Sessions DISTINCT scan

Test fixtures

10 golden markers across 5 languages:

• cmd/sin-code/internal/sindept/testdata/markers.{go,py,ts,sh,md}

23 tests cover family coverage, trailing-closer stripping, byte-stability,
vendor / hidden-dir walk, age/rot grouping, policy gates above/below threshold
plus the require_upgrade=true strict mode.

Verification

gofmt -l .                                # clean on new files
go build ./...                            # clean
go vet ./...                              # clean
go test -race -count=1 ./cmd/sin-code/internal/sindept/  # 23 PASS
python3 scripts/validate_skill.py --all-bundled --strict  # 34 skills, 0 failed
golangci-lint run --timeout=5m ./cmd/sin-code/internal/sindept/  # 0 issues
govulncheck ./...                         # No vulnerabilities found
gosec -no-fail -fmt sarif ./...           # 0 findings on new files

Acceptance criteria

• cmd/sin-code/internal/sindept/ package — Scanner, Aggregator, Reporter, Policy
• cmd/sin-code/debt_cmd.go — 6 subcommands (list, stats, check, policy, fix, export)
• // sin-debt: <ceiling>, upgrade: <trigger> parses in 100% of cases (5/5 languages)
• no-trigger (rot-risk) detection — verified by TestPolicyCheckFailsOverThreshold
• docs/sin-debt-convention.md exists with format spec + 5 real examples
• 4 real production-code markers added
• All tests pass with -race
• golangci-lint, govulncheck, gosec clean on new files

Closes #177

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sin-code	Ready	Preview, Comment, Open in v0	Jun 16, 2026 7:35pm

[vercel]

Deployment failed with the following error:

Resource is limited - try again in 24 hours (more than 100, code: "api-deployments-young-hobby-team-24h").

Learn More: https://vercel.com/manheiler-8784s-projects?upgradeToPro=build-rate-limit

[github-actions]

🏆 CEO Audit — A+ (100.0/100)

Metric	Value
Grade	A+
Score	100.0/100
Critical findings	0
High findings	0
Profile	QUICK
Min grade gate	B

📥 Download full report (Markdown)
📊 Download SARIF (for Code Scanning)

Run ~/.config/opencode/skills/ceo-audit/scripts/audit.sh . --profile=QUICK locally to reproduce.

[github-actions]

🏆 CEO Audit — A+ (100.0/100)

Metric	Value
Grade	A+
Score	100.0/100
Critical findings	0
High findings	0
Medium findings	0
Profile	QUICK
Min grade gate	B

📥 Download full report (Markdown)

Run ID: 27643033033 · Commit: ${github.sha}

Run ~/.config/opencode/skills/ceo-audit/scripts/audit.sh . --profile=QUICK locally to reproduce.