From 26277c2dce76a6829cb19b7ea3d102a810939705 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Victor=20Ara=C3=BAjo?= Date: Sat, 17 Oct 2026 10:04:26 -0300 Subject: [PATCH] docs: date the bundled skill with its release The vendored copy of the skill is a released snapshot, so a reader needs the forkctl release its text describes. The skill now renders version: from the crate version through ctl-core's version_line, and a skill pin in .ctl/ver.yaml moves it in each Version PR, as qctl and verctl do. Cargo.toml drops package.homepage, which repeated package.repository and which nightly cargo reports as redundant. Closes FRK-025 --- .ctl/operator/SKILL.md.jinja | 2 ++ .ctl/ver.yaml | 6 ++++++ AGENTS.md | 2 +- Cargo.toml | 1 - skills/forkctl/SKILL.md | 1 + src/operator_docs.rs | 1 + tasks.yaml | 9 +++++++++ 7 files changed, 20 insertions(+), 2 deletions(-) diff --git a/.ctl/operator/SKILL.md.jinja b/.ctl/operator/SKILL.md.jinja index e760938..3d95e7a 100644 --- a/.ctl/operator/SKILL.md.jinja +++ b/.ctl/operator/SKILL.md.jinja @@ -1,5 +1,6 @@ {%- from "ctl/invocation.md.jinja" import mounted_invocation -%} {%- from "ctl/commands.md.jinja" import command_inventory -%} +{%- from "ctl/version.md.jinja" import version_line -%} --- name: forkctl description: >- @@ -10,6 +11,7 @@ description: >- generated patch exports/ledger, or the user mentions forkctl, downstream patches, StGit fork maintenance, rebase recovery, or atomic fork publication. license: MIT +{{ version_line(version) }} compatibility: Requires forkctl plus supported git and stg executables; a repository-mounted mise `fork` task may provision exact versions. --- diff --git a/.ctl/ver.yaml b/.ctl/ver.yaml index 0597e62..f9a998e 100644 --- a/.ctl/ver.yaml +++ b/.ctl/ver.yaml @@ -18,6 +18,9 @@ patterns: task: match: '"github:victor-software-house/forkctl" = "{version}"' occurrences: once + skill: + match: "version: {version}" + occurrences: once pins: - file: examples/mise.toml @@ -26,6 +29,9 @@ pins: - file: tasks/fork/fork package: forkctl patterns: [task] + - file: skills/forkctl/SKILL.md + package: forkctl + patterns: [skill] # One key per host binary; the name is the job, the tarball, and the platform. # Both are built-in records; linux-x64 overrides only the triple, because the diff --git a/AGENTS.md b/AGENTS.md index 8c6fce9..e6857b1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -48,7 +48,7 @@ Forkctl is a Rust policy CLI for explicit audited StGit downstream patch stacks. - Pretty help, result tables, notices, and errors fit the detected terminal width; redirected output may use the standard `COLUMNS` fallback. JSON and generated machine contracts never reflow. - The remote catalog exposes one mounted `fork` file task using `dir = "{{cwd}}"`, exact task tools, the directives `ctl_core::mount_directives("fork")` returns (`raw = true`, `raw_args = true`, and the `#USAGE mount` line), and `exec forkctl "$@"`. `raw` hands the caller exactly what forkctl wrote: without it, in `prefix` output mode, mise relays each line and wraps it in colour whenever its own colour is on, as under `CLICOLOR_FORCE=1` into a pipe. Operators run `mise run fork status` with no `--`. The `--` in the mount is mise's completion bootstrap only. - VSH Lefthook defaults call `mise run fork check -s` on pre-commit and `mise run fork check -q` on pre-push; other managers call the same commands. -- `skills/forkctl/SKILL.md` is the portable skills.sh-installable operator workflow. Keep it concise and synchronized with released CLI behavior; installed help/instructions remain authoritative, so the skill must not duplicate a full flag grammar. Templates under `.ctl/operator/` keep domain prose and import ctl-core's mounted invocation/no-`--` and command-inventory fragments from the Clap-derived `Surface`. `operator_docs` byte-compares both committed renders; update them with `UPDATE_OPERATOR_DOCS=1 cargo test operator_docs`. +- `skills/forkctl/SKILL.md` is the portable skills.sh-installable operator workflow. Keep it concise and synchronized with released CLI behavior; installed help/instructions remain authoritative, so the skill must not duplicate a full flag grammar. Templates under `.ctl/operator/` keep domain prose and import ctl-core's mounted invocation/no-`--` and command-inventory fragments from the Clap-derived `Surface`. `operator_docs` byte-compares both committed renders; update them with `UPDATE_OPERATOR_DOCS=1 cargo test operator_docs`. The skill's `version:` frontmatter renders from `CARGO_PKG_VERSION` through ctl-core's `version_line`, and the `skill` pin in `.ctl/ver.yaml` lets the Version PR move it with the release. - Lifecycle fixtures use real Git/StGit binaries inside a private `tempfile` root with private HOME/XDG/Git configuration/templates, deterministic identity/time/locale, and command-local environment only; never inherit operator Git config or mutate the test process environment. - `mise run test:isolated` runs the cargo-nextest suite one test at a time (`--test-threads=1`); keep ordinary lifecycle tests container-free unless the scenario actually requires another OS, daemon, network, or toolchain image. diff --git a/Cargo.toml b/Cargo.toml index 1689a0f..09a070f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -6,7 +6,6 @@ rust-version.workspace = true description = "Control audited StGit downstream patch stacks" license = "MIT" repository = "https://github.com/victor-software-house/forkctl" -homepage = "https://github.com/victor-software-house/forkctl" readme = "README.md" keywords = ["git", "stgit", "fork", "patches", "cli"] categories = ["command-line-utilities", "development-tools"] diff --git a/skills/forkctl/SKILL.md b/skills/forkctl/SKILL.md index 1c42399..e46bcf4 100644 --- a/skills/forkctl/SKILL.md +++ b/skills/forkctl/SKILL.md @@ -8,6 +8,7 @@ description: >- generated patch exports/ledger, or the user mentions forkctl, downstream patches, StGit fork maintenance, rebase recovery, or atomic fork publication. license: MIT +version: 0.0.38 compatibility: Requires forkctl plus supported git and stg executables; a repository-mounted mise `fork` task may provision exact versions. --- diff --git a/src/operator_docs.rs b/src/operator_docs.rs index d09bb43..c4fbc40 100644 --- a/src/operator_docs.rs +++ b/src/operator_docs.rs @@ -24,6 +24,7 @@ fn render_template(relative: &str) -> String { .unwrap_or_else(|error| panic!("parse {relative}: {error}")) .render(minijinja::context! { surface => ctl_core::Surface::new::("fork"), + version => env!("CARGO_PKG_VERSION"), }) .unwrap_or_else(|error| panic!("render {relative}: {error}")) } diff --git a/tasks.yaml b/tasks.yaml index 215fa9c..6325837 100644 --- a/tasks.yaml +++ b/tasks.yaml @@ -25,6 +25,15 @@ queue: acceptance: - The skill covers declared checks, the rewrite, append, propose, and promote publish modes, --set-default, and FORKCTL_ variables. - Help for --check-at names stack|patch. + + - id: FRK-025 + title: Date the bundled skill with its release + scope: docs + outcome: The bundled skill names the forkctl release its text describes, and the Version PR moves it. + blocked_by: [] + acceptance: + - 'skills/forkctl/SKILL.md carries version: equal to the crate version, rendered by operator_docs.' + - The skill pin in .ctl/ver.yaml matches it exactly once. horizon: - id: FRK-009 title: Install StGit without compiling it