t1k:cocos:playable:stdlib-harvest
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: consumption, harvest pipeline, harvest pla, repoint, stdlib ledger, stdlib-harvest
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:stdlib-harvest[--resume-from <stage>] [--stop-after <stage>] [--repo <owner/name>]stdlib-harvest
Section titled “stdlib-harvest”Runs the harvest pipeline: find the reusable capabilities already sitting in the fleet’s
playable-ad repos and move them into
The1Studio/cocos-stdlib as @playablelabs/*
packages — then record what the run learned so the next one is cheaper.
This skill decides nothing about packaging. From S5 onward each accepted candidate goes to
t1k-cocos-base-stdlib-contribute, whose Steps 0-2 still own the scope gate and the
granularity decision. What this skill adds is the pipeline around that skill: an org-wide
inventory, a symbol fingerprint (S4) that finds duplicates mechanically rather than by reading,
a purity and equivalence gate (S6a/S6b) that makes a dedupe claim falsifiable, and a ledger that
makes recurrence countable.
references/contracts.md is the interface freeze — every script CLI, JSON shape, exit code,
the run-draft file and the evidence layout. assets/failure-codes.json is the catalogue every
failure code comes from (D20). Neither is restated here; a reference cites them by section.
Preconditions
Section titled “Preconditions”| Check | Why |
|---|---|
Session cwd is the cocos-stdlib clone, on main, tree clean | The ledger, clone index and report are written there; S11 branches from it |
Harvest deps installed: bun install --frozen-lockfile --ignore-scripts --cwd .claude/modules/playable/skills/t1k-cocos-playable-stdlib-harvest/scripts | ts-morph, jscpd and ajv are pinned; a missing one is exit 2, never a heuristic fallback. Bun ≥1.4.3, gh and git ≥2.35 are REQUIRED prerequisites, declared with this step in install.json. The test suite has its own pin (tests/package.json, fast-check) — bun test "tests/*.test.cjs" needs that one installed too, or it fails with Cannot find module 'fast-check' (references/contracts.md § DEPS/DEPS_TESTS) |
gh auth status succeeds and reaches The1Studio | S0 lists the org, S7’s stop check calls gh pr list, S11 opens the PR |
STDLIB_HARVEST_DISCORD_WEBHOOK_URL is set | S12 has no fallback to DISCORD_WEBHOOK_URL (D8). Check presence, never print the value |
| A user is present | Five stages ask — S0, S9, S10, S12, S14; a non-interactive session stops at the first gate |
Agent/Task is available (not a routed hop, not a fork) | S3 onward spawns on nearly every row — see “This skill runs in the main session (D17)” below. harvest-clone.cjs clone (S1) itself refuses with S1-NO-FANOUT when MR_SPAWNED=1, before any side effect (#579); a forked skill body carries no such marker, so this row’s fork half is prose-only, self-checked by the session |
One repo per session. A run is scoped to a single repo at a single SHA; a second repo is a
second session with its own runId, its own branch and its own ledger row.
This skill runs in the main session (D17)
Section titled “This skill runs in the main session (D17)”effort: high with no context: fork — a forked skill body loses Agent, and
validate-skill-context-fork-spawn-usage.cjs rejects fork + spawn outright. The stage table below
spawns on nearly every row, and the five human gates are direct AskUserQuestion calls, so a
context: key here is not a tuning mistake; it is the pipeline failing to run at all.
t1k-cook has the same shape for the same reason.
Never edit this skill within its own run. S13’s tier-2/3 fixes leave via that run’s sync-back PR; the body you are executing is the body you would be changing, and the change cannot be validated by the run that depends on it.
Stage table
Section titled “Stage table”Stages run in execution order — the numbering is the ledger’s key, not the run order. S6b follows S7 because purity (S6a) and extraction (S7) must both happen before an equivalence spec can be written against the extracted original.
| # | Stage | Tool | Reference | Ledger | Failure codes |
|---|---|---|---|---|---|
| S0 | Inventory the org: Cocos 3.x repos not yet harvested at HEAD | harvest-preflight.cjs, harvest-inventory.cjs | references/s00-inventory.md | S0 | S0-GH-AUTH S0-INACCESSIBLE S0-NO-WEBHOOK-CONFIG |
| S1 | Sparse-clone the chosen repo at its SHA; open the run draft | harvest-clone.cjs | references/s01-clone.md | S1 | S1-CLONE-FAILED |
| S2 | Guard: confirm on the working copy that this is a Cocos 3.x project | detect-cocos-project.cjs | references/s02-guard.md | S2 | S2-NOT-3X |
| S3 | Chunked candidate scan + six read-only audits into evidence/ | stdlib-candidates.cjs + six audits | references/s03-audits.md | S3 | S3-AUDIT-FAILED S3-CEILING-DROP |
| S4 | Fingerprint every symbol; compare prior → stdlib → fleet | clone-fingerprint.cjs, near-dup-report.cjs | references/s04-fingerprint.md | S4 | S4-TS-PARSE |
| S4b | Classify game-foundation overlaps as REUSE-via-port | enumerate-subsystems.cjs | references/s04-fingerprint.md | S4b | (none — a documentary read) |
| S5 | Scope-gate, label and cap the candidate set for the gate | coupling-probe.cjs + (main session) + reason-loss-check.cjs | references/s05-classify.md | S5 | S5-SCOPE-REJECT |
| S6a | Purity check — does the symbol’s closure reach cc? | purity-check.cjs | references/s06a-purity.md | S6a | S6A-CC-COUPLED |
| S7 | Extract and scaffold in a package worktree, stopping after Step 6 | contributor agent | references/s07-extract.md | S7 | S7-STOP-VIOLATED S7-VERIFY-FAILED |
| S6b | Differential equivalence test, generated then run, then reconciled into the record | diff-test-generate.cjs, diff-test-run.cjs, s6b-verdict-check.cjs | references/s06b-equivalence.md | S6b | S6B-DIVERGENT S6B-INCONCLUSIVE S6B-RECORD-STALE |
| S8 | Gatekeeper verdict per candidate, up to 3 rounds | verdict-check.cjs + gatekeeper agent | references/s08-gatekeeper.md | S8 | S8-REJECT S8-ROUND-CAP |
| S9 | Human approval table — nothing passes it unapproved | AskUserQuestion | references/s09-human-approval.md | S9 | S9-HUMAN-REJECT |
| S10 | Resume the contributor, open the package PRs, confirm publish | contributor agent + t1k-ci-watcher | references/s10-contribute.md | S10 | S10-CI-RED S10-PUBLISH-MISSING |
| S11 | First ledger write; overlap register; open the S11 PR | harvest-ledger.cjs + reason-loss-check.cjs | references/s11-record.md | S11 | S11-SCHEMA-INVALID |
| S12 | Post the run summary to the Discord thread | discord-notify.cjs | references/s12-discord.md | S12 | S12-NO-WEBHOOK S12-POST-FAILED |
| S13 | Tier every lesson, emit markers, sync back, set final status | harvest-ledger.cjs | references/s13-self-improve.md | S13 | S13-SYNCBACK-FAILED |
| S14 | Clean up workspace, worktrees and state file | harvest-clone.cjs, stdlib-candidates.cjs | references/s14-cleanup.md | (none — D5) | (none) |
| S15 | Repoint the source repo onto the published package, per candidate — optional; Step 0 emits the plan | adopt-plan.cjs, install-package.cjs, retire-consumed.cjs (both t1k-cocos-playable-modularize-refactor), reuse-coverage.cjs | references/s15-repoint.md | (none — see reference) | (none — see reference) |
| F0 | Project each framework candidate’s share of project lines | candidate-projection.cjs | references/f00-candidate-projection.md | F0 | F0-NO-PROJECT-ROOT F0-COVERAGE-FAILED |
The F* rows are the framework lane, which runs alongside the repo-first S0–S14 lane above
rather than replacing it: S0–S14 harvests one repo’s reusable code bottom-up, while F0–F4
packages a repeated subsystem top-down. The plan retired the old C0–C3 capability lane on
2026-09-16 after measuring its dedupe ceiling at only 2–5%, and replaced it with F0–F4.
Code meanings live in assets/failure-codes.json, keyed by code. S14 is deliberately not a
ledger stage (D5): it runs after the S11 PR merges, so a row asserting it would have to predate
its own evidence. harvest-ledger stage --stage S14 is rejected with exit 2. S15 is also not a
ledger stage, and for a stronger reason than S14: its evidence is a PR on a repo this run’s
schema has no slot for at all (references/s15-repoint.md).
Where a run writes, and the PR guard
Section titled “Where a run writes, and the PR guard”Why this skill stays disable-model-invocation: true (deferred decision 7): S7 (package worktree),
S10 (package PRs), S11 (record PR), S12 (Discord post), S13 (sync-back PR) and S15 (repoint PRs)
write to shared repos or channels, and S0/S9 ask the user. The read-only front door a model may start
on its own is t1k-cocos-playable-stdlib-scan (detector dry-run, status, report, and a scan
into the per-user local queue; it writes to no repo).
Every PR this skill opens on The1Studio/cocos-stdlib (contribute/* and harvest/* branches):
- Carries a
Consumer:line in its body:<org>/<repo>,<org>/<repo>#<pr>,<org>/<repo>:<path>, ornone-yet (<reason of 20+ chars>). The last form is allowed on a ready PR like the others: the S8 gatekeeper APPROVE, not the consumer, is the merge gate, and the reason is the audit trail. When the reason says the package should wait for a consumer, ask the user whether to hold it (AskUserQuestion) rather than holding on your own judgment. - Opens ready, with no
no-automergelabel, soauto-merge.ymlon cocos-stdlib squash-merges it on a greenci(same default ast1k-cocos-base-stdlib-contributeStep 9; 2026-10-28 #536/#537, and #608/#548 sat draft forever because nothing promoted them). That workflow also refuses acontribute/*orharvest/*head with no gatekeeper APPROVE for its exact head sha, so the S8 verdict must be on record beforecicompletes: commit statusgatekeeper= success, or an owner/member commentgatekeeper: APPROVE <sha>(REVISE and REJECT block). Post it right after the PR opens with.claude/modules/base/skills/t1k-cocos-base-stdlib-contribute/scripts/post-gatekeeper-status.cjs --pr <n> --head-sha <PR head> --verdict <validated verdict.json>(it refuses a verdict reviewed on another sha and never posts a hand-worded comment);auto-merge.ymlonly runs whencicompletes, so a verdict posted later needs acire-run. Open draft withno-automergeONLY on an explicit user or command instruction to hold. Never arm--auto. - Is recorded in the ledger even if a later stage fails:
record-runstamps S11okitself. S12S12-NO-WEBHOOKstays non-blocking and unchanged.
Human gates
Section titled “Human gates”Each is a direct AskUserQuestion in the main session — never a prose list, and never a
paragraph the user might not answer (theonekit-core/.claude/modules/t1k-base/rules/always-ask-on-unresolved.md).
| Stage | Question | Guard |
|---|---|---|
| S0 | Confirm the inventory before probing the org | Preview-first: smoke a small --limit N first, surface it, then ask — theonekit-core/.claude/modules/t1k-base/rules/preview-first-batch.md. Required only when the worklist exceeds ~10 repos |
| S9 | Per ≤4 candidates: approve, reject, or defer this extraction? | The approval table shows verdict, equivalence, gatekeeper verdict with its round count, and any near-dup (nothing reaches S10 unapproved) |
| S10 | None — the merge waits on ci, not on a person | Ruleset 22741411 requires 0 approving reviews and carries no required_status_checks rule, so there is nothing for a human to gate. The orchestrator watches ci to green and merges (s10-contribute.md) |
| S12 | What is the Discord thread ID? | Only when harvest/config.json’s discord.threadId is null; write it back to the config on the S11 branch |
| S14 | None — the S11 PR merges under the same ci-green rule | If it is still open, watch ci and merge. Cleanup is never a reason to merge |
A non-interactive session stops at the first gate — it never auto-approves. An approval nobody gave is precisely what S9 exists to prevent.
Executed by
Section titled “Executed by”Depth 0 spawns to depth 1; the fan-out cap and the depth budget are
theonekit-core/.claude/modules/t1k-base/rules/agent-security-boilerplate.md § agent-only (8/3/2 by depth). This skill is a leaf
consumer of that budget, not a setter of it — it neither sets its children’s depth nor reads its
own.
| Work | Agent |
|---|---|
| S0–S6a, S6b, S11–S15 Step 0 mechanics | no agent — deterministic CLI plus main-session writes (D17) |
| S3 knowledge sweep | t1k-corpus-scout (one read-only hop; its output is evidence/knowledge-sweep.json) |
| S3 architecture audit | t1k-cocos-base-reviewer, read-only (writes evidence/architecture.json) |
| S7 extract, S10 resume | t1k-cocos-playable-stdlib-contributor — one at a time (D18: the worktrees share one clone and node_modules, so two live agents clobber each other silently) |
| S8 gatekeeper | t1k-cocos-base-stdlib-gatekeeper (fable), one candidate at a time |
| S10 PR watching | t1k-ci-watcher — watches to terminal, never retries, fixes or merges |
| S11/S12/S13 git | t1k-git-manager |
| S13 lessons | ONE background /t1k:sync-back, only when lessons is non-empty (U2) |
| S15 (optional, per candidate) | main session or the S7/S10 contributor’s own continuation, plus t1k-git-manager + t1k-ci-watcher on the source repo’s PR — see references/s15-repoint.md |
Routing rows live in theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md; this table is the harvest-specific map, not a
second copy of that one.
What a run leaves behind
Section titled “What a run leaves behind”A merged record (harvest/ledger.json, harvest/clone-index/<owner>__<name>.jsonl,
harvest/reports/<owner>__<name>.md), any package PRs, at most one sync-back PR to theonekit-cocos
(zero when lessons: [], U2), a Discord message, and — after S14 — no workspace, no state file
and no worktree. When S15 ran for one or more candidates, also a repoint PR per candidate on
that candidate’s own source repo — the run this pipeline extracted the code FROM, not
cocos-stdlib or theonekit-cocos.
Related
Section titled “Related”references/contracts.md— the interface freeze: script CLIs, JSON shapes, exit codes, the run-draft file, the evidence layout, the brief tokens, and the hook interaction note.references/incident-history.md— tier-1 lessons earlier runs wrote down (D11). Read it before re-deriving a fix for something already recorded; S13 appends to it.references/gatekeeper-rubric.md— the eleven rubric ids S8 grades against (GK-VALUEfirst).references/s15-repoint.md— the optional stage that repoints a candidate’s source repo onto the package this pipeline just published, closing the loop S0–S14 leaves open on their own. Step 0 (adopt-plan.cjs) turns the provenance record S6b already writes into that plan.t1k-cocos-base-stdlib-contribute— packages what this pipeline finds (Steps 0-2 decide).scripts/resolve-canonical-cli.cjs— which installed copy ofstdlib-candidates.cjsto run: the newest VALID copy, the others reported (never deleted;t1k modules updaterepairs them). Verdict tokens come fromscripts/lib/verdict-vocab.cjs, mapped to the core vocabulary on read (SKIP is KEEP); without core’snormalize()the output saysvocabulary: unverifiedon stderr.