[any-victor]

Why

The operator asked for every ctl skill to be reviewed against current behaviour. I checked forkctl's bundled skill against every command's --help from the published 0.0.37 binary, and against the source.

Gaps found and fixed

1. The skill said nothing about declared patch checks (-C, -g, --check-at, --clear-checks), although they gate refresh, finish, rebase, and both hooks.
2. Publishing was described only as rewrite. A fork with publish: propose depends on the propose and promote flow: never merge the proposal pull request, and promote from a clone whose HEAD tree matches the proposal. The skill now covers append too, and publish --set-default.
3. The skill did not mention the FORKCTL_<LONG> variables beyond FORKCTL_MANIFEST.
4. --check-at help named only NAME=patch, though the parser takes stack|patch, with stack the default. Both help strings and the usage snapshot are updated.

Checked and correct

The command table, the init, check, patch, operation, rebase, contract, and api flags the skill names, the mise x recovery path, and --preview, which is ctl-core's visible alias of --dry-run. The installed instructions already covered all four topics above.

Proof

On a Linux build host, the usage snapshot and both operator renders were regenerated, and mise run verify passed, operator_docs included. The hooks passed on the pushed commit. A patch changeset ships the help text change.

Closes FRK-024

[kodus-hostinger]

Review

Incremental · 0 open

@kody review after new commits. @kody full re-reads the whole PR.

Summary

What these patches change

The changes are documentation and help text only. The one Rust change in src/cli.rs edits doc comments, so it changes help output but not argument parsing.

Help text (src/cli.rs, usage snapshot)

• The --check-at doc comment is rewritten in both PatchCreateCliArgs and PatchEditCliArgs, so patch create --help changes as well as patch edit --help.
  • Old text: "Evaluate a declared check at its own patch commit as NAME=patch"
  • New text: "Tree a declared check observes as NAME=stack|patch: the applied stack (the default) or its own patch commit"
• parse_check_stage and CheckStage are untouched. The new text documents what the parser already accepts.
• Both occurrences in cli__usage_spec_is_the_mounted_fork_grammar.snap are updated to match.

Skill content

The source template (.ctl/operator/SKILL.md.jinja) and the rendered skills/forkctl/SKILL.md receive identical additions, which keeps the two in sync.

The new declared-checks section adds a worked patch edit example using -C, -g, and --check-at. It also documents these semantics:

• Commands run via sh -c and must exit 0.
• {files} expands to the matched tracked files, shell-quoted.
• -g is repeatable and defaults to the patch scope.
• A check whose globs match no tracked file fails as stale.
• --check-at patch evaluates in a disposable clone with no origin remote.
• --clear-checks replaces the whole check set before adding the supplied checks.

The publish section is restructured around the repository default mode:

• The default comes from downstream.publish and is visible in status.
• rewrite is now described precisely: the recovery tag points at the overwritten tip.
• propose behaviour is spelled out:
  • Pushes forkctl/proposal/<branch> under a lease and opens or updates a draft pull request through gh.
  • A repeat updates the same branch and pull request in place.
  • --promote refuses unless the proposal tree matches HEAD.
  • --proposal overrides the proposal reference with a branch, tag, or URL.
• --set-default MODE publishes as well, unless it is the only action given.

The planning flags line now lists the -n short form alongside --dry-run / --preview.

The new environment-variable paragraph states:

• A command-line flag wins over its FORKCTL_<LONG> variable.
• An empty variable counts as unset.
• Help shows each variable beside its flag.

Tracking

• tasks.yaml adds the FRK-024 queue entry (scope docs, no blockers). Its acceptance criteria are skill coverage of checks, the publish modes, --set-default, and FORKCTL_<LONG>, plus --check-at help naming stack|patch.
• .changeset/skill-content.md records a forkctl patch release describing the help and skill updates.

Files

File	Status	+	−
.changeset/skill-content.md	added	+5	−0
.ctl/operator/SKILL.md.jinja	modified	+24	−2
skills/forkctl/SKILL.md	modified	+24	−2
src/cli.rs	modified	+4	−4
tasks.yaml	modified	+9	−0
tests/snapshots/cli__usage_spec_is_the_mounted_fork_grammar.snap	modified	+2	−2

Open

No open findings.

History

When	Pass	Open
15 Oct 16:08 UTC	Incremental	0

_{Inspect this review}