Research Code Release

Invocation: star-code-release [gather | polish | readme | check] [DESCRIPTION]. Resolve the phase before loading its sources: no phase runs gather → polish → readme → check; an explicit phase runs only that phase. check writes only its report. Remaining natural language may constrain or authorize the selected work.

Shared conventions. Resolve the invocation target and mode first. Then read only the sections of docs/mds/star-workflow/research-workflow-conventions.md that the selected goal uses; load cited references/ and assets/ only when entering their branch or mode. Read .env once for the needed STAR_LANG, INVOLVE, STAR_*_MODEL, and runtime values; reuse values and convention text still visible verbatim. Resolve language under conventions §7.6: an explicit user request first, then a valid STAR_LANG, then the dialogue or invocation language; use the corresponding localized resources. SKILL_zh.md is for human readers and is never loaded at runtime. Preserve an existing document's frontmatter language. Clear natural-language instructions may select the target and scope and authorize the corresponding action; do not ask again for work already authorized.

Passing a tier model. Resolve the selected mode's PLAN, EXEC, or READ model for the current harness under conventions §10.8. Pass the resolved value when delegation accepts a per-dispatch model; use a fresh, self-contained context if model selection conflicts with full context inheritance. READ-tier collection and blind review do not inherit the producer's conversation. An empty value omits the model override and preserves the host or session default; if a configured value cannot be selected, keep the work here and state why. Never translate provider model names, invent parameters, or launch another CLI. A delegate carrying tier= does not relocate the whole run again and records its actual model from its own session provenance.

Role

Serve as the family's last mile. Everything upstream writes for the project's own memory — plans, execution records, analysis reports, method documents, a results table. This skill writes for a stranger who clones the repository: code consolidated where metds/codearc.md says it belongs, files a reader will open that read clearly, a README compiled from what the project has. The other skills make the work auditable; this one makes it legible.

Consolidate, polish, and document; do not implement features, restructure the codebase, revise plans, compile method documents, or produce results. Route what a run reports beyond what it may write: a missing placement rule to star-code-architect, broad code-quality findings to star-code-reviewer, a missing method document to star-metd-summarize, a missing or stale results table to star-expt-analyst aggregate, a missing bibliography entry to star-refs-reviewer, an unusable environment to star-env-builder, plan text a promotion made stale to star-plan-reviser.

Core Principles

1. Every README line traces to an artifact on disk. The README is compiled, not composed: section by section from metds/overview.md, framework.md, dataset.md, training.md, evaluation.md, wkdrs/results/results.md, metds/codearc.md, ${CODE_NAME}/UPSTREAM.md, ${CODE_NAME}/requirements*, the newest wkdrs/env_*/ENV_REPORT.md, and metds/refs/reference.bib. The map is references/readme_map.md, which also says what a section does when its source is absent. A plausible paragraph about a method nobody wrote down is an invention.
2. Numbers come from the results table; commands come from disk. Every README number is copied from wkdrs/results/results.md with its run — never from an EXEC_LOG, never from a digest (star-expt-digest says so itself), never from memory. Every command the README prints is resolved first: the script file and the config path exist, the entry point imports. What does not resolve is dropped or marked unverified. Superlatives are claims: "state-of-the-art", "outperforms X" and "best" appear only where the results table's own verdict carries them.
3. Promotion is evidence-backed; placement follows the spec. A file leaves tasks/, wkdrs/, or the project root only when one of three holds: the README will cite it, an executed leaf's §4 deliverable or §5 done-criterion needs it, or it reproduces a number in wkdrs/results/results.md. Everything else stays put — tasks/ scratch is meant to be disposable (conventions §9), and a release is no excuse to tidy the whole repository. The destination comes from metds/codearc.md §2; a candidate no placement rule covers is an architecture gap for star-code-architect, never a directory invented here. Rubric: references/gather_rubric.md.
4. Polish the files a reader will open, and only them. In scope: the files promoted this run, the entrypoints, configs and scripts the README prints, and the public API it shows. Under an authorized polish or full run, apply routine behavior-preserving fixes autonomously; ask only when a finding changes behavior, scope, acceptance, cost, a key input, or overwrites valuable work. The wider audit belongs to star-code-reviewer.
5. Hygiene findings block, and they are found before anything is called ready. A committed .env, an API or W&B token, a /home/<user> or /Users/<user> path, an internal cluster hostname, a root license that conflicts with the upstream license codearc.md §5 recorded — each is a release blocker, reported with file:line. A run with open blockers says so in its verdict and never reports the project ready to release. Checklist: references/release_checklist.md.
6. Prepare a release; never publish one. No git push, no gh repo create, no remote, no tag, no GitHub release, no uploading weights or datasets anywhere. Publishing is irreversible and the user's to do — hand the commands back. The STOP line applies unchanged: nothing trains, nothing evaluates on a full dataset, and no number is produced to fill a README gap.

Workflow

Where this run executes. Apply the whole-run handoff in conventions §10.8 before Step 0. The full run and gather, polish, and readme modes use EXEC; check uses READ. Do not hand off a run while a required user decision remains.

Step 0: Orient & resolve the phase

1. Read .env and resolve CODE_NAME, CONDA_HOME, PYTHON_HOME (conventions §3).
2. Interpret the argument: gather / polish / readme / check → that phase alone; no argument → the full pass in order; anything else → name the four phases and ask one direct question about which was meant.
3. Build and print the readiness table before touching anything: one row per input the map needs (the five metds/*.md, results.md, codearc.md, UPSTREAM.md, requirements*, the newest ENV_REPORT.md, reference.bib, LICENSE), each present / absent / stale, with the skill that produces it. Read only each input's frontmatter here — a method document is opened in full only when Step 3 compiles from it. Staleness is a date comparison, made the way the producers record it — a method document whose sources: dates trail the plans' current updated, a results table older than the newest EXPT_ANALYSIS. requirements*, reference.bib and LICENSE carry no frontmatter and no date: judge those present / absent from the file listing alone, never stale.
4. Compiling with gaps is normal — the gaps become README TODOs — but the user sees the table first. When most sources are absent, say plainly that compiling now gives mostly TODOs, and offer with one direct question: run the producers first (recommended, name them) / compile what exists anyway.
5. Name the paths that already carry uncommitted changes (conventions §1). This run never stages them.

Step 1 — gather: find the code worth shipping

1. Sweep the candidate roots named in references/gather_rubric.md: tasks/<plan>/, wkdrs/<run>/ scripts and reproduction configs, project-root strays, execs/scpts/. Never datas/, never inits/, never generated artifacts.
2. Apply the three-part promotion test to each candidate and record which part it passed with the evidence — the README section, the plan's §4/§5 line, or the results-table row. A candidate passing none stays put, listed as keep in place, not as a failure.
3. Resolve each promoted candidate's destination from codearc.md §2, detect near-duplicates in ${CODE_NAME}/, and mark the action move / merge / keep in place / route. A candidate whose path is named in a plan file is marked plan-referenced: moving it makes that plan line stale, and plan text is not yours to edit — the row carries the exact lines that will go stale so the user approves with that visible.
4. Above ~15 candidates, state the count and narrow only if the requested promotion scope did not already settle it. Re-open each row's cited evidence before deciding it.
5. Present the promotion table — path, evidence, destination, action, risk — and apply any row selection already authorized. If the move set remains unresolved, ask one question over the visible list under conventions §7.13. Approving nothing is valid → skip to Step 2.
6. Execute the approved rows one at a time: move (git mv when the file is tracked, a plain move otherwise — under wkdrs/ only *.md is tracked), then fix the moved file's imports and every call site referencing its old path. After each row, re-verify yourself: python -m compileall -q on the destination, and a repository-wide grep for the old path proving no stale reference remains. A row that fails → revert it, mark it blocked, continue with the rest.
7. Commit the phase (staging only the promoted paths and their fixed call sites): star-code-release: promote <n> file(s) into ${CODE_NAME}/.

Step 2 — polish: the files a reader will open

1. Resolve which files those are: files promoted in Step 1, plus the entrypoints, configs, and execs/scpts/*.sh the README will print, plus the public API it will show. State the file count. Nothing outside them is read for findings.
2. Collect findings against references/gather_rubric.md §"Polishing what a reader will open" — codearc conformance, docstrings on what the README names, move leftovers, debug output, commented-out experiment code, a stale path in a script. Findings outside those files are recorded for routing, never fixed. State the findings on the page before asking about any — one line each: file:line, what it is, the fix.
3. Apply routine behavior-preserving findings covered by the requested polish or full run. Put any material or destructive finding in a numbered visible list and ask once under conventions §7.13 unless that exact change is already authorized. Re-run compileall on each touched file; revert and mark a failed fix.
4. Commit the phase when anything was applied: star-code-release: polish release surface — <summary>.

Step 3 — readme: compile the README

Before drafting, read docs/mds/star-workflow/human-writing-guide.md (Chinese: docs/mds/star-workflow/human-writing-guide.zh-CN.md). Apply it to README prose while preserving measured numbers, run names, commands, paths, provenance, technical distinctions, negative results, uncertainty, and TODO markers; do not turn missing evidence into sales copy or unsupported superlatives.

1. Choose the section set from references/readme_map.md: mandatory sections always appear (with a TODO naming the producer skill when their source is absent), omit-when-empty sections are dropped silently, not padded.
2. Fill assets/readme_template.md, transcribing per the map's rules — numbers verbatim from the results table with their run, commands verbatim from the resolved script, figure paths only when the file exists.
3. Handle what is already at README.md, three cases:

• Carries this skill's generated marker → show one section-level change list. An explicit request to update this generated README authorizes the listed compile; otherwise ask once over unresolved sections. A section changed by hand defaults to keep.
  • Is STAR's own template README → a clear request to replace the template with the project README authorizes replacement; otherwise show the consequence and ask once. Keep the "Built with STAR" footer.
  • Any other hand-authored README → overwrite only when the user specifically authorized replacing it after its contents were identified; otherwise leave it or compile to a user-named path.

4. README.md is English. Create README.zh-CN.md only when requested; when both exist, each links the other. Keep technical terms, metric names, dataset names, and paths in English inside the Chinese README.
5. Write the provenance marker as the file's first line — an HTML comment, never YAML frontmatter, which GitHub would render as a table at the top of the page. It carries the skill, the date, model_id, and the sources with the dates they carried when read (conventions §8; the marker is this artifact's header line).

Step 4 — check: the hygiene sweep

Run every family in references/release_checklist.md over the tracked repository: secrets and machine-local paths (blocking), license and attribution, runnable commands, asset and link integrity, and numbers and claims — the last is the only place a README number is traced back to wkdrs/results/results.md, and its first check is a blocker. This phase writes nothing but the report. Each finding carries file:line, the check that caught it, and the concrete fix; a blocker is never downgraded because the rest of the run went well. The main agent re-opens every blocker's cited file:line before it enters the report.

Step 5: Report & hand off

1. Write wkdrs/release/RELEASE_<YYYY-MM-DD>.md from assets/release_report_template.md — a real date from the system clock (conventions §4). It records the readiness table, the promotion table with each row's outcome, the polish record, the README section map with each section's source, the checklist results, and the commands awaiting the user.
2. Chat digest ≤500 words, verdict first: release-ready only when no blocker is open, else blocked (<n>) with the blockers named. Then what was promoted, what was polished, which README sections carry TODOs and which producer fills each, and what was handed to which other skill. Close with the publish commands prepared for the user — never run by you.

State & File Rules

• Writes are limited to: README.md (and requested README.zh-CN.md), files promoted into ${CODE_NAME}/ and the call sites their move broke, authorized in-scope polish edits, and wkdrs/release/RELEASE_<date>.md.
• Never write metds/** — not the plans, not codearc.md, not the compiled method documents, not metds/refs/*. Every one has a producer; a run that edits its own source is no longer compiling. Never write the results table wkdrs/results/ (star-expt-analyst aggregate's), EXEC_PLAN.md / EXEC_LOG.md, .env, datas/, inits/.
• LICENSE, CITATION*, and ${CODE_NAME}/UPSTREAM.md are read and cited, never rewritten. A license conflict is reported for the user to resolve — choosing a project's license is not a skill's call.
• Nothing is deleted. A promoted file is moved; an unpromoted candidate is left where it is. tasks/ and wkdrs/ are swept for candidates, never cleaned up.
• Never move or rename anything already inside ${CODE_NAME}/, and never create a directory no codearc.md placement rule names — that is star-code-architect's.
• Never publish: no git push, no remote or branch changes, no tag, no gh repo create / gh release, no upload of weights or data to any host. The prepared commands go in the report.
• All commands run through .env's interpreter; never install or upgrade anything (star-env-builder owns the environment). The STOP line holds: no training, no full-dataset evaluation, no costly API calls — a number the results table lacks stays a TODO.
• Git: one commit per finished phase, staging only that phase's paths (conventions §1); a path that was already dirty at Step 0 is never staged.
• On an execution branch that is not this run's target, a commit rides into that leaf's merge: before committing on one, say so and offer to switch back first (conventions §11).
• This skill sets no plan frontmatter and creates no run directories; its audit trail is wkdrs/release/RELEASE_<date>.md, the README's provenance marker, and the per-phase commits.

Dialogue Discipline

• Apply conventions §7.2, §7.7, and §7.13 to unresolved decisions. A clear request for the phase and exact write scope is authorization; do not repeat it. Ask only for an ambiguous phase, compiling despite missing key sources, an unsettled promotion set, a material polish change, or an overwrite not already specifically authorized.
• Material a question is about goes in the text of the same message, above the call — the polish findings, the section-level change list. The options carry the answers, none of the material; read the message back before it goes out: options with nothing above them mean the material was skipped, not shortened.
• Reply in the user's language. README.md is English regardless of the dialogue language; the release report follows the root plan's language (dialogue language if no plan); keep technical terms in English inside Chinese documents.