tiny-pattern-ts/development/workflow.md

Workflow

How work moves through the repository: the branching model, the npm run script taxonomy, the feedback tiers, and commit messages. The contributor-facing steps are in CONTRIBUTING.md; this file records why they are shaped the way they are.

Branching model

The contributor-facing steps are in CONTRIBUTING.md § Branching model. Two bits of context behind the model: collaborative review through the Gitea UI is not in place, so Gitea is the lab; and the project will be promoted to GitHub once it is tested and ready for production. What follows is why the front doors exist and what was rejected.

Decision (2026-09)

Work is opened and closed by create:branch / create:finish rather than by prose plus hand-written git commands.

Why

• The branching model's preconditions were prose. Prose rots silently — a rule nobody checks is a suggestion. A script asserts, then acts, and the branch or merge only happens if the assertions passed.
• The type-driven loop only produces trustworthy results if the baseline was green before the first edit. Cheap checks run first and npm run test last, so the expensive gate is not paid on a tree that was never eligible.
• create:finish owns the merge-side preconditions and the post-merge npm run verify, so a merge cannot land unverified. The push stays with create:release so the merge remains local and reviewable until then.
• Every check failure is non-mutating, except the baseline test which runs on main after switching there — a red main restores the branch you started on rather than stranding you on it. A merge conflict aborts and returns to the feature branch, so a failed finish never leaves a half-merged main.

Rejected

• Hand-written git switch -c / git merge: same rules, no enforcement.
• Reusing pubv's preflight for create:branch: it is release-shaped and third-party, and would make starting a branch pay for a build and pack it has no use for.
• Leaving the merge as reviewer judgment: that judgment still exists, but it now happens when the maintainer reviews the handover before invoking create:finish, rather than being encoded in a command that anyone can run from a dirty tree.
• --no-ff rather than a fast-forward: it keeps each unit of work visible in git log.

Known issue

• create:finish deliberately does not push, so main is ahead of origin/main between a merge and the next push or release. create:branch requires main to match its upstream and will refuse until it is pushed. Push main before starting the next branch.

Script prefix convention

The prefix taxonomy is the rule, and it lives in CONTRIBUTING.md § Script prefix convention. What follows is the design rationale and the create: decision.

One part of the taxonomy is not a prefix rule: some top-level scripts are bare (no prefix): the entry points that either run a single tool (build, clean) or aggregate a prefix:* family (check, fix, test, watch, maintain, setup), plus one convenience that composes across tiers: verify — composing check + test:unit into one whole-project correctness gate (it deliberately uses test:unit rather than test because check already runs check:tsc, so the type checker runs exactly once). Bare commands are how you invoke a tier; the prefix:* scripts are what those tiers are made of.

Decision (2026-09)

create: is the prefix for workflow front doors, and there is no bare create aggregator.

Why

• Both members really do create something: a branch, a release.
• The prefix was added to both lists in CONTRIBUTING.md in the same commit as its first members, because a prefix missing from those lists is invisible — which was the use: mistake this repo previously carried (since retired into setup:).
• publish:* already set the precedent for a prefix without an aggregator.

Rejected

• run: / perform: — both mean only "do the thing named after them", so every script in the repo would fit under them and the taxonomy collapses.
• git: — names the tool, not the lifecycle moment, and advertises passthrough aliases.
• start: — describes the branch half, not the release.
• cut: — idiomatic for both, but it needs VCS slang to decode, and a signpost that has to be explained is not one.
• flow: — overloaded in a library about type-level matching.
• The existing families: check:* is read-only and aggregated by check, so CI would run a command that mutates repo state; fix:*'s review surface is a file diff, not a branch; maintain:* is advisory and explicitly never a gate.

Feedback tiers

The tier table and the rules for invoking it are in CONTRIBUTING.md § Feedback tiers; this section explains why the split is where it is.

Decision (2026-09)

Split fast, offline, staged-file checks into pre-commit; whole-project test runs into pre-push and verify; and slow or network-bound scans into maintain.

Why

• watch:* is a manual tier, not a hook. The developer starts it on demand (it has to be killed with Ctrl-C) and it runs in a dedicated terminal pane. It sits as the earliest tier in the ladder, catching failures the moment a file is saved — before staging, before commit.
• check:tsc, check:oxlint, check:oxfmt, check:cspell are in pre-commit because they are fast (~0.2–0.5s each), fully offline, and naturally scope to staged files via the LEFTHOOK_FILES env var convention. They give instant feedback on what you typed.
• test (and the tsc it includes) is in pre-push because it runs the whole test suite across the whole project. The pre-commit LEFTHOOK_FILES convention doesn't apply to the test runner, so pre-commit isn't the right home. Pre-push runs after all commits are made but before the push leaves the machine, catching regressions that span multiple commits.

Rejected

• Running maintain:* in check or pre-commit: advisory, whole-project and network-bound scans are not correctness gates and would make the fast tier slow.
• Treating a green pre-commit as the definition of done: it only sees staged files, which is why npm run verify exists as the one-shot whole-project gate.
• A separate git push hook for verify: it would duplicate the pre-push test tier; verify is run by hand because the push is where the whole project is already checked.

Commit messages

The convention is in CONTRIBUTING.md § Commit messages. Examples from history: :sparkles: Add watch tier with watch:test child, :recycle: Move type-aware config to .oxlintrc.json; use source-level disable directives, :memo: Restore unique maintainer content as CONTRIBUTING.md. The body explains what and why, not how; link issues with Resolves #....

Decision (2026-09)

Gitmoji subjects with imperative mood, wrapped 50/72, rather than Conventional Commits.

Why

• The history is gitmoji, not Conventional, and it predates any commit-lint tooling; switching would rewrite the convention for no gain.
• The body carries reasoning, which is what a reviewer needs; the subject is a signpost, not a semantic key.

Rejected

• Conventional Commits: the release flow uses hand-written Keep-a-Changelog notes, not generated ones, so the prefix carries no automation value here (see publishing.md).