From 10977d99d3b281d9b5ef732f706ccb7fc3aaf612 Mon Sep 17 00:00:00 2001 From: Rob Masson Date: Fri, 9 Oct 2026 22:48:47 -0700 Subject: [PATCH 1/4] Teach rule candidate capture through the installed ArchDev skill --- archdev/SKILL.md | 7 ++++ archdev/references/rule-candidates.md | 37 +++++++++++++++++++ plugins/antigravity/skills/archdev/SKILL.md | 7 ++++ .../archdev/references/rule-candidates.md | 37 +++++++++++++++++++ plugins/claude/skills/archdev/SKILL.md | 7 ++++ .../archdev/references/rule-candidates.md | 37 +++++++++++++++++++ plugins/codex/skills/archdev/SKILL.md | 7 ++++ .../archdev/references/rule-candidates.md | 37 +++++++++++++++++++ plugins/copilot/skills/archdev/SKILL.md | 7 ++++ .../archdev/references/rule-candidates.md | 37 +++++++++++++++++++ plugins/cursor/skills/archdev/SKILL.md | 7 ++++ .../archdev/references/rule-candidates.md | 37 +++++++++++++++++++ plugins/grok/skills/archdev/SKILL.md | 7 ++++ .../archdev/references/rule-candidates.md | 37 +++++++++++++++++++ plugins/opencode/skills/archdev/SKILL.md | 7 ++++ .../archdev/references/rule-candidates.md | 37 +++++++++++++++++++ plugins/pi/skills/archdev/SKILL.md | 7 ++++ .../archdev/references/rule-candidates.md | 37 +++++++++++++++++++ 18 files changed, 396 insertions(+) create mode 100644 archdev/references/rule-candidates.md create mode 100644 plugins/antigravity/skills/archdev/references/rule-candidates.md create mode 100644 plugins/claude/skills/archdev/references/rule-candidates.md create mode 100644 plugins/codex/skills/archdev/references/rule-candidates.md create mode 100644 plugins/copilot/skills/archdev/references/rule-candidates.md create mode 100644 plugins/cursor/skills/archdev/references/rule-candidates.md create mode 100644 plugins/grok/skills/archdev/references/rule-candidates.md create mode 100644 plugins/opencode/skills/archdev/references/rule-candidates.md create mode 100644 plugins/pi/skills/archdev/references/rule-candidates.md diff --git a/archdev/SKILL.md b/archdev/SKILL.md index 7d50638..f91b796 100644 --- a/archdev/SKILL.md +++ b/archdev/SKILL.md @@ -109,6 +109,13 @@ subagents and agents you spawn. - PR reporting requires no local grading, annotations, or stop hold, including Factory and daemon sessions. Follow the host's publication ownership. +## Rule corrections during a session + +On a standing never/always correction or a repeated correction, follow +[rule candidate capture](references/rule-candidates.md): draft a Markdown/Jev +pair and capture only the supplied correction with the public CLI. Candidates +remain inert until the user authorizes policy adoption through a PR. + ## 1. Bootstrap Read [bootstrap.md](references/bootstrap.md). Goal: the binary is current, diff --git a/archdev/references/rule-candidates.md b/archdev/references/rule-candidates.md new file mode 100644 index 0000000..f15a780 --- /dev/null +++ b/archdev/references/rule-candidates.md @@ -0,0 +1,37 @@ +# Rule candidate capture + +When the user gives a standing never/always correction or repeats a correction, +draft a reusable rule pair from that correction. Follow the repository's +`rules/README.md` when present. Otherwise use Markdown frontmatter containing +`name`, `description`, and `date`, with cited good/bad examples. Its sibling +`.jev` uses `jev-latest`, exactly the Noul questions `applicable` and `complies`, +and `state.diff` and `state.context` placeholders starting `REPLACE_BEFORE_USE:`. +Keep the supplied constraint and examples; do not infer unrelated policy. + +Read `.archdev/rules.yaml` for `adopt_to` (default `.archdev/rules/`). Choose +its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, +or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add +the pair at that path, then capture the supplied correction: + +```sh +archdev rules propose --repository owner/repo --md-file --jev-file --proposed-path --correction +archdev rules candidates --repository owner/repo +``` + +These commands require the Rust CLI release containing `rules` and deployed +candidate storage. If unavailable, retain the draft and report that limitation; +do not substitute the frozen TypeScript CLI or install anything without consent. +Use the current signed-in organization and the repository's installed identity. + +Proposals append immutable caller-owned answers. Recall shows the summary, +complete drafts, proposed path, status, and evidence; your unfolded proposals +are marked pending and are visible only to you until automation folds them. +Do not automatically retry an uncertain write. Recall first and report any +uncertainty. Store no secrets or unrelated transcript. + +Candidates do not activate policy. Do not edit, commit, or adopt repository +policy without the user's authorization. Human adoption is a PR adding the +Markdown/Jev pair. After approval, `rules adopt` can record that PR or commit +as adoption evidence; `rules dismiss` records a reason for dismissal. These +commands append human decisions for automation to fold; they do not add files +or change candidate status directly. No backtesting is required. diff --git a/plugins/antigravity/skills/archdev/SKILL.md b/plugins/antigravity/skills/archdev/SKILL.md index 7d50638..f91b796 100644 --- a/plugins/antigravity/skills/archdev/SKILL.md +++ b/plugins/antigravity/skills/archdev/SKILL.md @@ -109,6 +109,13 @@ subagents and agents you spawn. - PR reporting requires no local grading, annotations, or stop hold, including Factory and daemon sessions. Follow the host's publication ownership. +## Rule corrections during a session + +On a standing never/always correction or a repeated correction, follow +[rule candidate capture](references/rule-candidates.md): draft a Markdown/Jev +pair and capture only the supplied correction with the public CLI. Candidates +remain inert until the user authorizes policy adoption through a PR. + ## 1. Bootstrap Read [bootstrap.md](references/bootstrap.md). Goal: the binary is current, diff --git a/plugins/antigravity/skills/archdev/references/rule-candidates.md b/plugins/antigravity/skills/archdev/references/rule-candidates.md new file mode 100644 index 0000000..f15a780 --- /dev/null +++ b/plugins/antigravity/skills/archdev/references/rule-candidates.md @@ -0,0 +1,37 @@ +# Rule candidate capture + +When the user gives a standing never/always correction or repeats a correction, +draft a reusable rule pair from that correction. Follow the repository's +`rules/README.md` when present. Otherwise use Markdown frontmatter containing +`name`, `description`, and `date`, with cited good/bad examples. Its sibling +`.jev` uses `jev-latest`, exactly the Noul questions `applicable` and `complies`, +and `state.diff` and `state.context` placeholders starting `REPLACE_BEFORE_USE:`. +Keep the supplied constraint and examples; do not infer unrelated policy. + +Read `.archdev/rules.yaml` for `adopt_to` (default `.archdev/rules/`). Choose +its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, +or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add +the pair at that path, then capture the supplied correction: + +```sh +archdev rules propose --repository owner/repo --md-file --jev-file --proposed-path --correction +archdev rules candidates --repository owner/repo +``` + +These commands require the Rust CLI release containing `rules` and deployed +candidate storage. If unavailable, retain the draft and report that limitation; +do not substitute the frozen TypeScript CLI or install anything without consent. +Use the current signed-in organization and the repository's installed identity. + +Proposals append immutable caller-owned answers. Recall shows the summary, +complete drafts, proposed path, status, and evidence; your unfolded proposals +are marked pending and are visible only to you until automation folds them. +Do not automatically retry an uncertain write. Recall first and report any +uncertainty. Store no secrets or unrelated transcript. + +Candidates do not activate policy. Do not edit, commit, or adopt repository +policy without the user's authorization. Human adoption is a PR adding the +Markdown/Jev pair. After approval, `rules adopt` can record that PR or commit +as adoption evidence; `rules dismiss` records a reason for dismissal. These +commands append human decisions for automation to fold; they do not add files +or change candidate status directly. No backtesting is required. diff --git a/plugins/claude/skills/archdev/SKILL.md b/plugins/claude/skills/archdev/SKILL.md index 7d50638..f91b796 100644 --- a/plugins/claude/skills/archdev/SKILL.md +++ b/plugins/claude/skills/archdev/SKILL.md @@ -109,6 +109,13 @@ subagents and agents you spawn. - PR reporting requires no local grading, annotations, or stop hold, including Factory and daemon sessions. Follow the host's publication ownership. +## Rule corrections during a session + +On a standing never/always correction or a repeated correction, follow +[rule candidate capture](references/rule-candidates.md): draft a Markdown/Jev +pair and capture only the supplied correction with the public CLI. Candidates +remain inert until the user authorizes policy adoption through a PR. + ## 1. Bootstrap Read [bootstrap.md](references/bootstrap.md). Goal: the binary is current, diff --git a/plugins/claude/skills/archdev/references/rule-candidates.md b/plugins/claude/skills/archdev/references/rule-candidates.md new file mode 100644 index 0000000..f15a780 --- /dev/null +++ b/plugins/claude/skills/archdev/references/rule-candidates.md @@ -0,0 +1,37 @@ +# Rule candidate capture + +When the user gives a standing never/always correction or repeats a correction, +draft a reusable rule pair from that correction. Follow the repository's +`rules/README.md` when present. Otherwise use Markdown frontmatter containing +`name`, `description`, and `date`, with cited good/bad examples. Its sibling +`.jev` uses `jev-latest`, exactly the Noul questions `applicable` and `complies`, +and `state.diff` and `state.context` placeholders starting `REPLACE_BEFORE_USE:`. +Keep the supplied constraint and examples; do not infer unrelated policy. + +Read `.archdev/rules.yaml` for `adopt_to` (default `.archdev/rules/`). Choose +its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, +or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add +the pair at that path, then capture the supplied correction: + +```sh +archdev rules propose --repository owner/repo --md-file --jev-file --proposed-path --correction +archdev rules candidates --repository owner/repo +``` + +These commands require the Rust CLI release containing `rules` and deployed +candidate storage. If unavailable, retain the draft and report that limitation; +do not substitute the frozen TypeScript CLI or install anything without consent. +Use the current signed-in organization and the repository's installed identity. + +Proposals append immutable caller-owned answers. Recall shows the summary, +complete drafts, proposed path, status, and evidence; your unfolded proposals +are marked pending and are visible only to you until automation folds them. +Do not automatically retry an uncertain write. Recall first and report any +uncertainty. Store no secrets or unrelated transcript. + +Candidates do not activate policy. Do not edit, commit, or adopt repository +policy without the user's authorization. Human adoption is a PR adding the +Markdown/Jev pair. After approval, `rules adopt` can record that PR or commit +as adoption evidence; `rules dismiss` records a reason for dismissal. These +commands append human decisions for automation to fold; they do not add files +or change candidate status directly. No backtesting is required. diff --git a/plugins/codex/skills/archdev/SKILL.md b/plugins/codex/skills/archdev/SKILL.md index 7d50638..f91b796 100644 --- a/plugins/codex/skills/archdev/SKILL.md +++ b/plugins/codex/skills/archdev/SKILL.md @@ -109,6 +109,13 @@ subagents and agents you spawn. - PR reporting requires no local grading, annotations, or stop hold, including Factory and daemon sessions. Follow the host's publication ownership. +## Rule corrections during a session + +On a standing never/always correction or a repeated correction, follow +[rule candidate capture](references/rule-candidates.md): draft a Markdown/Jev +pair and capture only the supplied correction with the public CLI. Candidates +remain inert until the user authorizes policy adoption through a PR. + ## 1. Bootstrap Read [bootstrap.md](references/bootstrap.md). Goal: the binary is current, diff --git a/plugins/codex/skills/archdev/references/rule-candidates.md b/plugins/codex/skills/archdev/references/rule-candidates.md new file mode 100644 index 0000000..f15a780 --- /dev/null +++ b/plugins/codex/skills/archdev/references/rule-candidates.md @@ -0,0 +1,37 @@ +# Rule candidate capture + +When the user gives a standing never/always correction or repeats a correction, +draft a reusable rule pair from that correction. Follow the repository's +`rules/README.md` when present. Otherwise use Markdown frontmatter containing +`name`, `description`, and `date`, with cited good/bad examples. Its sibling +`.jev` uses `jev-latest`, exactly the Noul questions `applicable` and `complies`, +and `state.diff` and `state.context` placeholders starting `REPLACE_BEFORE_USE:`. +Keep the supplied constraint and examples; do not infer unrelated policy. + +Read `.archdev/rules.yaml` for `adopt_to` (default `.archdev/rules/`). Choose +its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, +or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add +the pair at that path, then capture the supplied correction: + +```sh +archdev rules propose --repository owner/repo --md-file --jev-file --proposed-path --correction +archdev rules candidates --repository owner/repo +``` + +These commands require the Rust CLI release containing `rules` and deployed +candidate storage. If unavailable, retain the draft and report that limitation; +do not substitute the frozen TypeScript CLI or install anything without consent. +Use the current signed-in organization and the repository's installed identity. + +Proposals append immutable caller-owned answers. Recall shows the summary, +complete drafts, proposed path, status, and evidence; your unfolded proposals +are marked pending and are visible only to you until automation folds them. +Do not automatically retry an uncertain write. Recall first and report any +uncertainty. Store no secrets or unrelated transcript. + +Candidates do not activate policy. Do not edit, commit, or adopt repository +policy without the user's authorization. Human adoption is a PR adding the +Markdown/Jev pair. After approval, `rules adopt` can record that PR or commit +as adoption evidence; `rules dismiss` records a reason for dismissal. These +commands append human decisions for automation to fold; they do not add files +or change candidate status directly. No backtesting is required. diff --git a/plugins/copilot/skills/archdev/SKILL.md b/plugins/copilot/skills/archdev/SKILL.md index 7d50638..f91b796 100644 --- a/plugins/copilot/skills/archdev/SKILL.md +++ b/plugins/copilot/skills/archdev/SKILL.md @@ -109,6 +109,13 @@ subagents and agents you spawn. - PR reporting requires no local grading, annotations, or stop hold, including Factory and daemon sessions. Follow the host's publication ownership. +## Rule corrections during a session + +On a standing never/always correction or a repeated correction, follow +[rule candidate capture](references/rule-candidates.md): draft a Markdown/Jev +pair and capture only the supplied correction with the public CLI. Candidates +remain inert until the user authorizes policy adoption through a PR. + ## 1. Bootstrap Read [bootstrap.md](references/bootstrap.md). Goal: the binary is current, diff --git a/plugins/copilot/skills/archdev/references/rule-candidates.md b/plugins/copilot/skills/archdev/references/rule-candidates.md new file mode 100644 index 0000000..f15a780 --- /dev/null +++ b/plugins/copilot/skills/archdev/references/rule-candidates.md @@ -0,0 +1,37 @@ +# Rule candidate capture + +When the user gives a standing never/always correction or repeats a correction, +draft a reusable rule pair from that correction. Follow the repository's +`rules/README.md` when present. Otherwise use Markdown frontmatter containing +`name`, `description`, and `date`, with cited good/bad examples. Its sibling +`.jev` uses `jev-latest`, exactly the Noul questions `applicable` and `complies`, +and `state.diff` and `state.context` placeholders starting `REPLACE_BEFORE_USE:`. +Keep the supplied constraint and examples; do not infer unrelated policy. + +Read `.archdev/rules.yaml` for `adopt_to` (default `.archdev/rules/`). Choose +its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, +or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add +the pair at that path, then capture the supplied correction: + +```sh +archdev rules propose --repository owner/repo --md-file --jev-file --proposed-path --correction +archdev rules candidates --repository owner/repo +``` + +These commands require the Rust CLI release containing `rules` and deployed +candidate storage. If unavailable, retain the draft and report that limitation; +do not substitute the frozen TypeScript CLI or install anything without consent. +Use the current signed-in organization and the repository's installed identity. + +Proposals append immutable caller-owned answers. Recall shows the summary, +complete drafts, proposed path, status, and evidence; your unfolded proposals +are marked pending and are visible only to you until automation folds them. +Do not automatically retry an uncertain write. Recall first and report any +uncertainty. Store no secrets or unrelated transcript. + +Candidates do not activate policy. Do not edit, commit, or adopt repository +policy without the user's authorization. Human adoption is a PR adding the +Markdown/Jev pair. After approval, `rules adopt` can record that PR or commit +as adoption evidence; `rules dismiss` records a reason for dismissal. These +commands append human decisions for automation to fold; they do not add files +or change candidate status directly. No backtesting is required. diff --git a/plugins/cursor/skills/archdev/SKILL.md b/plugins/cursor/skills/archdev/SKILL.md index 7d50638..f91b796 100644 --- a/plugins/cursor/skills/archdev/SKILL.md +++ b/plugins/cursor/skills/archdev/SKILL.md @@ -109,6 +109,13 @@ subagents and agents you spawn. - PR reporting requires no local grading, annotations, or stop hold, including Factory and daemon sessions. Follow the host's publication ownership. +## Rule corrections during a session + +On a standing never/always correction or a repeated correction, follow +[rule candidate capture](references/rule-candidates.md): draft a Markdown/Jev +pair and capture only the supplied correction with the public CLI. Candidates +remain inert until the user authorizes policy adoption through a PR. + ## 1. Bootstrap Read [bootstrap.md](references/bootstrap.md). Goal: the binary is current, diff --git a/plugins/cursor/skills/archdev/references/rule-candidates.md b/plugins/cursor/skills/archdev/references/rule-candidates.md new file mode 100644 index 0000000..f15a780 --- /dev/null +++ b/plugins/cursor/skills/archdev/references/rule-candidates.md @@ -0,0 +1,37 @@ +# Rule candidate capture + +When the user gives a standing never/always correction or repeats a correction, +draft a reusable rule pair from that correction. Follow the repository's +`rules/README.md` when present. Otherwise use Markdown frontmatter containing +`name`, `description`, and `date`, with cited good/bad examples. Its sibling +`.jev` uses `jev-latest`, exactly the Noul questions `applicable` and `complies`, +and `state.diff` and `state.context` placeholders starting `REPLACE_BEFORE_USE:`. +Keep the supplied constraint and examples; do not infer unrelated policy. + +Read `.archdev/rules.yaml` for `adopt_to` (default `.archdev/rules/`). Choose +its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, +or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add +the pair at that path, then capture the supplied correction: + +```sh +archdev rules propose --repository owner/repo --md-file --jev-file --proposed-path --correction +archdev rules candidates --repository owner/repo +``` + +These commands require the Rust CLI release containing `rules` and deployed +candidate storage. If unavailable, retain the draft and report that limitation; +do not substitute the frozen TypeScript CLI or install anything without consent. +Use the current signed-in organization and the repository's installed identity. + +Proposals append immutable caller-owned answers. Recall shows the summary, +complete drafts, proposed path, status, and evidence; your unfolded proposals +are marked pending and are visible only to you until automation folds them. +Do not automatically retry an uncertain write. Recall first and report any +uncertainty. Store no secrets or unrelated transcript. + +Candidates do not activate policy. Do not edit, commit, or adopt repository +policy without the user's authorization. Human adoption is a PR adding the +Markdown/Jev pair. After approval, `rules adopt` can record that PR or commit +as adoption evidence; `rules dismiss` records a reason for dismissal. These +commands append human decisions for automation to fold; they do not add files +or change candidate status directly. No backtesting is required. diff --git a/plugins/grok/skills/archdev/SKILL.md b/plugins/grok/skills/archdev/SKILL.md index 7d50638..f91b796 100644 --- a/plugins/grok/skills/archdev/SKILL.md +++ b/plugins/grok/skills/archdev/SKILL.md @@ -109,6 +109,13 @@ subagents and agents you spawn. - PR reporting requires no local grading, annotations, or stop hold, including Factory and daemon sessions. Follow the host's publication ownership. +## Rule corrections during a session + +On a standing never/always correction or a repeated correction, follow +[rule candidate capture](references/rule-candidates.md): draft a Markdown/Jev +pair and capture only the supplied correction with the public CLI. Candidates +remain inert until the user authorizes policy adoption through a PR. + ## 1. Bootstrap Read [bootstrap.md](references/bootstrap.md). Goal: the binary is current, diff --git a/plugins/grok/skills/archdev/references/rule-candidates.md b/plugins/grok/skills/archdev/references/rule-candidates.md new file mode 100644 index 0000000..f15a780 --- /dev/null +++ b/plugins/grok/skills/archdev/references/rule-candidates.md @@ -0,0 +1,37 @@ +# Rule candidate capture + +When the user gives a standing never/always correction or repeats a correction, +draft a reusable rule pair from that correction. Follow the repository's +`rules/README.md` when present. Otherwise use Markdown frontmatter containing +`name`, `description`, and `date`, with cited good/bad examples. Its sibling +`.jev` uses `jev-latest`, exactly the Noul questions `applicable` and `complies`, +and `state.diff` and `state.context` placeholders starting `REPLACE_BEFORE_USE:`. +Keep the supplied constraint and examples; do not infer unrelated policy. + +Read `.archdev/rules.yaml` for `adopt_to` (default `.archdev/rules/`). Choose +its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, +or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add +the pair at that path, then capture the supplied correction: + +```sh +archdev rules propose --repository owner/repo --md-file --jev-file --proposed-path --correction +archdev rules candidates --repository owner/repo +``` + +These commands require the Rust CLI release containing `rules` and deployed +candidate storage. If unavailable, retain the draft and report that limitation; +do not substitute the frozen TypeScript CLI or install anything without consent. +Use the current signed-in organization and the repository's installed identity. + +Proposals append immutable caller-owned answers. Recall shows the summary, +complete drafts, proposed path, status, and evidence; your unfolded proposals +are marked pending and are visible only to you until automation folds them. +Do not automatically retry an uncertain write. Recall first and report any +uncertainty. Store no secrets or unrelated transcript. + +Candidates do not activate policy. Do not edit, commit, or adopt repository +policy without the user's authorization. Human adoption is a PR adding the +Markdown/Jev pair. After approval, `rules adopt` can record that PR or commit +as adoption evidence; `rules dismiss` records a reason for dismissal. These +commands append human decisions for automation to fold; they do not add files +or change candidate status directly. No backtesting is required. diff --git a/plugins/opencode/skills/archdev/SKILL.md b/plugins/opencode/skills/archdev/SKILL.md index 7d50638..f91b796 100644 --- a/plugins/opencode/skills/archdev/SKILL.md +++ b/plugins/opencode/skills/archdev/SKILL.md @@ -109,6 +109,13 @@ subagents and agents you spawn. - PR reporting requires no local grading, annotations, or stop hold, including Factory and daemon sessions. Follow the host's publication ownership. +## Rule corrections during a session + +On a standing never/always correction or a repeated correction, follow +[rule candidate capture](references/rule-candidates.md): draft a Markdown/Jev +pair and capture only the supplied correction with the public CLI. Candidates +remain inert until the user authorizes policy adoption through a PR. + ## 1. Bootstrap Read [bootstrap.md](references/bootstrap.md). Goal: the binary is current, diff --git a/plugins/opencode/skills/archdev/references/rule-candidates.md b/plugins/opencode/skills/archdev/references/rule-candidates.md new file mode 100644 index 0000000..f15a780 --- /dev/null +++ b/plugins/opencode/skills/archdev/references/rule-candidates.md @@ -0,0 +1,37 @@ +# Rule candidate capture + +When the user gives a standing never/always correction or repeats a correction, +draft a reusable rule pair from that correction. Follow the repository's +`rules/README.md` when present. Otherwise use Markdown frontmatter containing +`name`, `description`, and `date`, with cited good/bad examples. Its sibling +`.jev` uses `jev-latest`, exactly the Noul questions `applicable` and `complies`, +and `state.diff` and `state.context` placeholders starting `REPLACE_BEFORE_USE:`. +Keep the supplied constraint and examples; do not infer unrelated policy. + +Read `.archdev/rules.yaml` for `adopt_to` (default `.archdev/rules/`). Choose +its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, +or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add +the pair at that path, then capture the supplied correction: + +```sh +archdev rules propose --repository owner/repo --md-file --jev-file --proposed-path --correction +archdev rules candidates --repository owner/repo +``` + +These commands require the Rust CLI release containing `rules` and deployed +candidate storage. If unavailable, retain the draft and report that limitation; +do not substitute the frozen TypeScript CLI or install anything without consent. +Use the current signed-in organization and the repository's installed identity. + +Proposals append immutable caller-owned answers. Recall shows the summary, +complete drafts, proposed path, status, and evidence; your unfolded proposals +are marked pending and are visible only to you until automation folds them. +Do not automatically retry an uncertain write. Recall first and report any +uncertainty. Store no secrets or unrelated transcript. + +Candidates do not activate policy. Do not edit, commit, or adopt repository +policy without the user's authorization. Human adoption is a PR adding the +Markdown/Jev pair. After approval, `rules adopt` can record that PR or commit +as adoption evidence; `rules dismiss` records a reason for dismissal. These +commands append human decisions for automation to fold; they do not add files +or change candidate status directly. No backtesting is required. diff --git a/plugins/pi/skills/archdev/SKILL.md b/plugins/pi/skills/archdev/SKILL.md index 7d50638..f91b796 100644 --- a/plugins/pi/skills/archdev/SKILL.md +++ b/plugins/pi/skills/archdev/SKILL.md @@ -109,6 +109,13 @@ subagents and agents you spawn. - PR reporting requires no local grading, annotations, or stop hold, including Factory and daemon sessions. Follow the host's publication ownership. +## Rule corrections during a session + +On a standing never/always correction or a repeated correction, follow +[rule candidate capture](references/rule-candidates.md): draft a Markdown/Jev +pair and capture only the supplied correction with the public CLI. Candidates +remain inert until the user authorizes policy adoption through a PR. + ## 1. Bootstrap Read [bootstrap.md](references/bootstrap.md). Goal: the binary is current, diff --git a/plugins/pi/skills/archdev/references/rule-candidates.md b/plugins/pi/skills/archdev/references/rule-candidates.md new file mode 100644 index 0000000..f15a780 --- /dev/null +++ b/plugins/pi/skills/archdev/references/rule-candidates.md @@ -0,0 +1,37 @@ +# Rule candidate capture + +When the user gives a standing never/always correction or repeats a correction, +draft a reusable rule pair from that correction. Follow the repository's +`rules/README.md` when present. Otherwise use Markdown frontmatter containing +`name`, `description`, and `date`, with cited good/bad examples. Its sibling +`.jev` uses `jev-latest`, exactly the Noul questions `applicable` and `complies`, +and `state.diff` and `state.context` placeholders starting `REPLACE_BEFORE_USE:`. +Keep the supplied constraint and examples; do not infer unrelated policy. + +Read `.archdev/rules.yaml` for `adopt_to` (default `.archdev/rules/`). Choose +its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, +or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add +the pair at that path, then capture the supplied correction: + +```sh +archdev rules propose --repository owner/repo --md-file --jev-file --proposed-path --correction +archdev rules candidates --repository owner/repo +``` + +These commands require the Rust CLI release containing `rules` and deployed +candidate storage. If unavailable, retain the draft and report that limitation; +do not substitute the frozen TypeScript CLI or install anything without consent. +Use the current signed-in organization and the repository's installed identity. + +Proposals append immutable caller-owned answers. Recall shows the summary, +complete drafts, proposed path, status, and evidence; your unfolded proposals +are marked pending and are visible only to you until automation folds them. +Do not automatically retry an uncertain write. Recall first and report any +uncertainty. Store no secrets or unrelated transcript. + +Candidates do not activate policy. Do not edit, commit, or adopt repository +policy without the user's authorization. Human adoption is a PR adding the +Markdown/Jev pair. After approval, `rules adopt` can record that PR or commit +as adoption evidence; `rules dismiss` records a reason for dismissal. These +commands append human decisions for automation to fold; they do not add files +or change candidate status directly. No backtesting is required. From a3e6f19a3b9b19247617f972601417d5fc45a1bb Mon Sep 17 00:00:00 2001 From: Rob Masson Date: Fri, 9 Oct 2026 23:18:18 -0700 Subject: [PATCH 2/4] Use configured rule pairs as session format examples --- archdev/references/rule-candidates.md | 19 ++++++++++++------- .../archdev/references/rule-candidates.md | 19 ++++++++++++------- .../archdev/references/rule-candidates.md | 19 ++++++++++++------- .../archdev/references/rule-candidates.md | 19 ++++++++++++------- .../archdev/references/rule-candidates.md | 19 ++++++++++++------- .../archdev/references/rule-candidates.md | 19 ++++++++++++------- .../archdev/references/rule-candidates.md | 19 ++++++++++++------- .../archdev/references/rule-candidates.md | 19 ++++++++++++------- .../archdev/references/rule-candidates.md | 19 ++++++++++++------- 9 files changed, 108 insertions(+), 63 deletions(-) diff --git a/archdev/references/rule-candidates.md b/archdev/references/rule-candidates.md index f15a780..4a420d8 100644 --- a/archdev/references/rule-candidates.md +++ b/archdev/references/rule-candidates.md @@ -1,14 +1,19 @@ # Rule candidate capture When the user gives a standing never/always correction or repeats a correction, -draft a reusable rule pair from that correction. Follow the repository's -`rules/README.md` when present. Otherwise use Markdown frontmatter containing -`name`, `description`, and `date`, with cited good/bad examples. Its sibling -`.jev` uses `jev-latest`, exactly the Noul questions `applicable` and `complies`, -and `state.diff` and `state.context` placeholders starting `REPLACE_BEFORE_USE:`. -Keep the supplied constraint and examples; do not infer unrelated policy. +draft a reusable Markdown/Jev rule pair from that correction. Read +`.archdev/rules.yaml` and inspect existing `.md` + `.jev` pairs matched by its +`include` patterns. Use those pairs as format examples. The `adopt_to` directory +(default `.archdev/rules/`) is the destination for the proposed pair. -Read `.archdev/rules.yaml` for `adopt_to` (default `.archdev/rules/`). Choose +When no existing pairs are available, use this default format: Markdown +frontmatter containing `name`, `description`, and `date`, with cited good/bad +examples; a sibling `.jev` using `jev-latest`, exactly the Noul questions +`applicable` and `complies`, and `state.diff` and `state.context` placeholders +starting `REPLACE_BEFORE_USE:`. Keep the supplied constraint and examples; +do not infer unrelated policy. + +Under `adopt_to`, choose its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add the pair at that path, then capture the supplied correction: diff --git a/plugins/antigravity/skills/archdev/references/rule-candidates.md b/plugins/antigravity/skills/archdev/references/rule-candidates.md index f15a780..4a420d8 100644 --- a/plugins/antigravity/skills/archdev/references/rule-candidates.md +++ b/plugins/antigravity/skills/archdev/references/rule-candidates.md @@ -1,14 +1,19 @@ # Rule candidate capture When the user gives a standing never/always correction or repeats a correction, -draft a reusable rule pair from that correction. Follow the repository's -`rules/README.md` when present. Otherwise use Markdown frontmatter containing -`name`, `description`, and `date`, with cited good/bad examples. Its sibling -`.jev` uses `jev-latest`, exactly the Noul questions `applicable` and `complies`, -and `state.diff` and `state.context` placeholders starting `REPLACE_BEFORE_USE:`. -Keep the supplied constraint and examples; do not infer unrelated policy. +draft a reusable Markdown/Jev rule pair from that correction. Read +`.archdev/rules.yaml` and inspect existing `.md` + `.jev` pairs matched by its +`include` patterns. Use those pairs as format examples. The `adopt_to` directory +(default `.archdev/rules/`) is the destination for the proposed pair. -Read `.archdev/rules.yaml` for `adopt_to` (default `.archdev/rules/`). Choose +When no existing pairs are available, use this default format: Markdown +frontmatter containing `name`, `description`, and `date`, with cited good/bad +examples; a sibling `.jev` using `jev-latest`, exactly the Noul questions +`applicable` and `complies`, and `state.diff` and `state.context` placeholders +starting `REPLACE_BEFORE_USE:`. Keep the supplied constraint and examples; +do not infer unrelated policy. + +Under `adopt_to`, choose its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add the pair at that path, then capture the supplied correction: diff --git a/plugins/claude/skills/archdev/references/rule-candidates.md b/plugins/claude/skills/archdev/references/rule-candidates.md index f15a780..4a420d8 100644 --- a/plugins/claude/skills/archdev/references/rule-candidates.md +++ b/plugins/claude/skills/archdev/references/rule-candidates.md @@ -1,14 +1,19 @@ # Rule candidate capture When the user gives a standing never/always correction or repeats a correction, -draft a reusable rule pair from that correction. Follow the repository's -`rules/README.md` when present. Otherwise use Markdown frontmatter containing -`name`, `description`, and `date`, with cited good/bad examples. Its sibling -`.jev` uses `jev-latest`, exactly the Noul questions `applicable` and `complies`, -and `state.diff` and `state.context` placeholders starting `REPLACE_BEFORE_USE:`. -Keep the supplied constraint and examples; do not infer unrelated policy. +draft a reusable Markdown/Jev rule pair from that correction. Read +`.archdev/rules.yaml` and inspect existing `.md` + `.jev` pairs matched by its +`include` patterns. Use those pairs as format examples. The `adopt_to` directory +(default `.archdev/rules/`) is the destination for the proposed pair. -Read `.archdev/rules.yaml` for `adopt_to` (default `.archdev/rules/`). Choose +When no existing pairs are available, use this default format: Markdown +frontmatter containing `name`, `description`, and `date`, with cited good/bad +examples; a sibling `.jev` using `jev-latest`, exactly the Noul questions +`applicable` and `complies`, and `state.diff` and `state.context` placeholders +starting `REPLACE_BEFORE_USE:`. Keep the supplied constraint and examples; +do not infer unrelated policy. + +Under `adopt_to`, choose its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add the pair at that path, then capture the supplied correction: diff --git a/plugins/codex/skills/archdev/references/rule-candidates.md b/plugins/codex/skills/archdev/references/rule-candidates.md index f15a780..4a420d8 100644 --- a/plugins/codex/skills/archdev/references/rule-candidates.md +++ b/plugins/codex/skills/archdev/references/rule-candidates.md @@ -1,14 +1,19 @@ # Rule candidate capture When the user gives a standing never/always correction or repeats a correction, -draft a reusable rule pair from that correction. Follow the repository's -`rules/README.md` when present. Otherwise use Markdown frontmatter containing -`name`, `description`, and `date`, with cited good/bad examples. Its sibling -`.jev` uses `jev-latest`, exactly the Noul questions `applicable` and `complies`, -and `state.diff` and `state.context` placeholders starting `REPLACE_BEFORE_USE:`. -Keep the supplied constraint and examples; do not infer unrelated policy. +draft a reusable Markdown/Jev rule pair from that correction. Read +`.archdev/rules.yaml` and inspect existing `.md` + `.jev` pairs matched by its +`include` patterns. Use those pairs as format examples. The `adopt_to` directory +(default `.archdev/rules/`) is the destination for the proposed pair. -Read `.archdev/rules.yaml` for `adopt_to` (default `.archdev/rules/`). Choose +When no existing pairs are available, use this default format: Markdown +frontmatter containing `name`, `description`, and `date`, with cited good/bad +examples; a sibling `.jev` using `jev-latest`, exactly the Noul questions +`applicable` and `complies`, and `state.diff` and `state.context` placeholders +starting `REPLACE_BEFORE_USE:`. Keep the supplied constraint and examples; +do not infer unrelated policy. + +Under `adopt_to`, choose its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add the pair at that path, then capture the supplied correction: diff --git a/plugins/copilot/skills/archdev/references/rule-candidates.md b/plugins/copilot/skills/archdev/references/rule-candidates.md index f15a780..4a420d8 100644 --- a/plugins/copilot/skills/archdev/references/rule-candidates.md +++ b/plugins/copilot/skills/archdev/references/rule-candidates.md @@ -1,14 +1,19 @@ # Rule candidate capture When the user gives a standing never/always correction or repeats a correction, -draft a reusable rule pair from that correction. Follow the repository's -`rules/README.md` when present. Otherwise use Markdown frontmatter containing -`name`, `description`, and `date`, with cited good/bad examples. Its sibling -`.jev` uses `jev-latest`, exactly the Noul questions `applicable` and `complies`, -and `state.diff` and `state.context` placeholders starting `REPLACE_BEFORE_USE:`. -Keep the supplied constraint and examples; do not infer unrelated policy. +draft a reusable Markdown/Jev rule pair from that correction. Read +`.archdev/rules.yaml` and inspect existing `.md` + `.jev` pairs matched by its +`include` patterns. Use those pairs as format examples. The `adopt_to` directory +(default `.archdev/rules/`) is the destination for the proposed pair. -Read `.archdev/rules.yaml` for `adopt_to` (default `.archdev/rules/`). Choose +When no existing pairs are available, use this default format: Markdown +frontmatter containing `name`, `description`, and `date`, with cited good/bad +examples; a sibling `.jev` using `jev-latest`, exactly the Noul questions +`applicable` and `complies`, and `state.diff` and `state.context` placeholders +starting `REPLACE_BEFORE_USE:`. Keep the supplied constraint and examples; +do not infer unrelated policy. + +Under `adopt_to`, choose its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add the pair at that path, then capture the supplied correction: diff --git a/plugins/cursor/skills/archdev/references/rule-candidates.md b/plugins/cursor/skills/archdev/references/rule-candidates.md index f15a780..4a420d8 100644 --- a/plugins/cursor/skills/archdev/references/rule-candidates.md +++ b/plugins/cursor/skills/archdev/references/rule-candidates.md @@ -1,14 +1,19 @@ # Rule candidate capture When the user gives a standing never/always correction or repeats a correction, -draft a reusable rule pair from that correction. Follow the repository's -`rules/README.md` when present. Otherwise use Markdown frontmatter containing -`name`, `description`, and `date`, with cited good/bad examples. Its sibling -`.jev` uses `jev-latest`, exactly the Noul questions `applicable` and `complies`, -and `state.diff` and `state.context` placeholders starting `REPLACE_BEFORE_USE:`. -Keep the supplied constraint and examples; do not infer unrelated policy. +draft a reusable Markdown/Jev rule pair from that correction. Read +`.archdev/rules.yaml` and inspect existing `.md` + `.jev` pairs matched by its +`include` patterns. Use those pairs as format examples. The `adopt_to` directory +(default `.archdev/rules/`) is the destination for the proposed pair. -Read `.archdev/rules.yaml` for `adopt_to` (default `.archdev/rules/`). Choose +When no existing pairs are available, use this default format: Markdown +frontmatter containing `name`, `description`, and `date`, with cited good/bad +examples; a sibling `.jev` using `jev-latest`, exactly the Noul questions +`applicable` and `complies`, and `state.diff` and `state.context` placeholders +starting `REPLACE_BEFORE_USE:`. Keep the supplied constraint and examples; +do not infer unrelated policy. + +Under `adopt_to`, choose its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add the pair at that path, then capture the supplied correction: diff --git a/plugins/grok/skills/archdev/references/rule-candidates.md b/plugins/grok/skills/archdev/references/rule-candidates.md index f15a780..4a420d8 100644 --- a/plugins/grok/skills/archdev/references/rule-candidates.md +++ b/plugins/grok/skills/archdev/references/rule-candidates.md @@ -1,14 +1,19 @@ # Rule candidate capture When the user gives a standing never/always correction or repeats a correction, -draft a reusable rule pair from that correction. Follow the repository's -`rules/README.md` when present. Otherwise use Markdown frontmatter containing -`name`, `description`, and `date`, with cited good/bad examples. Its sibling -`.jev` uses `jev-latest`, exactly the Noul questions `applicable` and `complies`, -and `state.diff` and `state.context` placeholders starting `REPLACE_BEFORE_USE:`. -Keep the supplied constraint and examples; do not infer unrelated policy. +draft a reusable Markdown/Jev rule pair from that correction. Read +`.archdev/rules.yaml` and inspect existing `.md` + `.jev` pairs matched by its +`include` patterns. Use those pairs as format examples. The `adopt_to` directory +(default `.archdev/rules/`) is the destination for the proposed pair. -Read `.archdev/rules.yaml` for `adopt_to` (default `.archdev/rules/`). Choose +When no existing pairs are available, use this default format: Markdown +frontmatter containing `name`, `description`, and `date`, with cited good/bad +examples; a sibling `.jev` using `jev-latest`, exactly the Noul questions +`applicable` and `complies`, and `state.diff` and `state.context` placeholders +starting `REPLACE_BEFORE_USE:`. Keep the supplied constraint and examples; +do not infer unrelated policy. + +Under `adopt_to`, choose its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add the pair at that path, then capture the supplied correction: diff --git a/plugins/opencode/skills/archdev/references/rule-candidates.md b/plugins/opencode/skills/archdev/references/rule-candidates.md index f15a780..4a420d8 100644 --- a/plugins/opencode/skills/archdev/references/rule-candidates.md +++ b/plugins/opencode/skills/archdev/references/rule-candidates.md @@ -1,14 +1,19 @@ # Rule candidate capture When the user gives a standing never/always correction or repeats a correction, -draft a reusable rule pair from that correction. Follow the repository's -`rules/README.md` when present. Otherwise use Markdown frontmatter containing -`name`, `description`, and `date`, with cited good/bad examples. Its sibling -`.jev` uses `jev-latest`, exactly the Noul questions `applicable` and `complies`, -and `state.diff` and `state.context` placeholders starting `REPLACE_BEFORE_USE:`. -Keep the supplied constraint and examples; do not infer unrelated policy. +draft a reusable Markdown/Jev rule pair from that correction. Read +`.archdev/rules.yaml` and inspect existing `.md` + `.jev` pairs matched by its +`include` patterns. Use those pairs as format examples. The `adopt_to` directory +(default `.archdev/rules/`) is the destination for the proposed pair. -Read `.archdev/rules.yaml` for `adopt_to` (default `.archdev/rules/`). Choose +When no existing pairs are available, use this default format: Markdown +frontmatter containing `name`, `description`, and `date`, with cited good/bad +examples; a sibling `.jev` using `jev-latest`, exactly the Noul questions +`applicable` and `complies`, and `state.diff` and `state.context` placeholders +starting `REPLACE_BEFORE_USE:`. Keep the supplied constraint and examples; +do not infer unrelated policy. + +Under `adopt_to`, choose its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add the pair at that path, then capture the supplied correction: diff --git a/plugins/pi/skills/archdev/references/rule-candidates.md b/plugins/pi/skills/archdev/references/rule-candidates.md index f15a780..4a420d8 100644 --- a/plugins/pi/skills/archdev/references/rule-candidates.md +++ b/plugins/pi/skills/archdev/references/rule-candidates.md @@ -1,14 +1,19 @@ # Rule candidate capture When the user gives a standing never/always correction or repeats a correction, -draft a reusable rule pair from that correction. Follow the repository's -`rules/README.md` when present. Otherwise use Markdown frontmatter containing -`name`, `description`, and `date`, with cited good/bad examples. Its sibling -`.jev` uses `jev-latest`, exactly the Noul questions `applicable` and `complies`, -and `state.diff` and `state.context` placeholders starting `REPLACE_BEFORE_USE:`. -Keep the supplied constraint and examples; do not infer unrelated policy. +draft a reusable Markdown/Jev rule pair from that correction. Read +`.archdev/rules.yaml` and inspect existing `.md` + `.jev` pairs matched by its +`include` patterns. Use those pairs as format examples. The `adopt_to` directory +(default `.archdev/rules/`) is the destination for the proposed pair. -Read `.archdev/rules.yaml` for `adopt_to` (default `.archdev/rules/`). Choose +When no existing pairs are available, use this default format: Markdown +frontmatter containing `name`, `description`, and `date`, with cited good/bad +examples; a sibling `.jev` using `jev-latest`, exactly the Noul questions +`applicable` and `complies`, and `state.diff` and `state.context` placeholders +starting `REPLACE_BEFORE_USE:`. Keep the supplied constraint and examples; +do not infer unrelated policy. + +Under `adopt_to`, choose its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add the pair at that path, then capture the supplied correction: From 758096e7a7bbea29f9ae838fac34317f6b859607 Mon Sep 17 00:00:00 2001 From: Rob Masson Date: Tue, 13 Oct 2026 11:00:27 -0700 Subject: [PATCH 3/4] docs(archdev): guide session rule proposals and rules PRs --- archdev/SKILL.md | 11 +-- archdev/references/rule-candidates.md | 84 +++++++++++-------- plugins/antigravity/skills/archdev/SKILL.md | 11 +-- .../archdev/references/rule-candidates.md | 84 +++++++++++-------- plugins/claude/skills/archdev/SKILL.md | 11 +-- .../archdev/references/rule-candidates.md | 84 +++++++++++-------- plugins/codex/skills/archdev/SKILL.md | 11 +-- .../archdev/references/rule-candidates.md | 84 +++++++++++-------- plugins/copilot/skills/archdev/SKILL.md | 11 +-- .../archdev/references/rule-candidates.md | 84 +++++++++++-------- plugins/cursor/skills/archdev/SKILL.md | 11 +-- .../archdev/references/rule-candidates.md | 84 +++++++++++-------- plugins/grok/skills/archdev/SKILL.md | 11 +-- .../archdev/references/rule-candidates.md | 84 +++++++++++-------- plugins/opencode/skills/archdev/SKILL.md | 11 +-- .../archdev/references/rule-candidates.md | 84 +++++++++++-------- plugins/pi/skills/archdev/SKILL.md | 11 +-- .../archdev/references/rule-candidates.md | 84 +++++++++++-------- 18 files changed, 486 insertions(+), 369 deletions(-) diff --git a/archdev/SKILL.md b/archdev/SKILL.md index f91b796..c1d8ba8 100644 --- a/archdev/SKILL.md +++ b/archdev/SKILL.md @@ -109,12 +109,13 @@ subagents and agents you spawn. - PR reporting requires no local grading, annotations, or stop hold, including Factory and daemon sessions. Follow the host's publication ownership. -## Rule corrections during a session +## Rule candidates from a session -On a standing never/always correction or a repeated correction, follow -[rule candidate capture](references/rule-candidates.md): draft a Markdown/Jev -pair and capture only the supplied correction with the public CLI. Candidates -remain inert until the user authorizes policy adoption through a PR. +When a user asks to turn a correction into a repository rule, follow +[rule candidate capture](references/rule-candidates.md). Discuss a checkable +obligation before drafting. Propose the pair only when the user asks; open a +rules PR only on a separate explicit request. Candidates remain inert until +the user merges a rules PR. ## 1. Bootstrap diff --git a/archdev/references/rule-candidates.md b/archdev/references/rule-candidates.md index 4a420d8..f09861c 100644 --- a/archdev/references/rule-candidates.md +++ b/archdev/references/rule-candidates.md @@ -1,42 +1,54 @@ # Rule candidate capture -When the user gives a standing never/always correction or repeats a correction, -draft a reusable Markdown/Jev rule pair from that correction. Read -`.archdev/rules.yaml` and inspect existing `.md` + `.jev` pairs matched by its -`include` patterns. Use those pairs as format examples. The `adopt_to` directory -(default `.archdev/rules/`) is the destination for the proposed pair. - -When no existing pairs are available, use this default format: Markdown -frontmatter containing `name`, `description`, and `date`, with cited good/bad -examples; a sibling `.jev` using `jev-latest`, exactly the Noul questions -`applicable` and `complies`, and `state.diff` and `state.context` placeholders -starting `REPLACE_BEFORE_USE:`. Keep the supplied constraint and examples; -do not infer unrelated policy. - -Under `adopt_to`, choose -its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, -or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add -the pair at that path, then capture the supplied correction: +Use this flow when a user wants to brainstorm a repository rule from a correction. A useful rule states one obligation a reviewer can see violated in a PR diff. A mechanical check may instead inspect the PR title or description. Ask for the concrete failure and expected change when they are missing. Push back on session-process instructions and pure style preferences: a diff reviewer cannot reliably check them. Do not turn an inferred preference into policy. + +## Draft the pair + +Read `.archdev/rules.yaml` in the target repository. Its `adopt_to` directory defaults to `.archdev/rules/`; choose a language or topic folder under it and follow an existing `.md`/`.jev` pair in that folder if available. Keep drafts in a temporary directory, not in the repository. The proposed path is where a later human-approved PR would place the Markdown file. + +The `.md` frontmatter has `name`, `description`, and `date`. Do not write a `sources` key: `archdev rules propose` stamps the session answer source. In particular, `type: instruction_file` would falsely identify this rule as an instruction-file draft and can cause a retirement proposal when the rule is absent from `AGENTS.md`. The body states the obligation, why it matters, what violates it, what complies, scope and exclusions, good and bad examples with real paths or PR references when available, and an Enforcement note. Exclude secrets and unrelated transcript. + +The sibling `.jev` is JSON with `model`, `state.diff`, `state.context`, and exactly two Noul questions, `applicable` and `complies`. Follow an existing pair's model and state placeholders. `applicable` starts `Scope check only; do not judge compliance.` and names included and excluded paths. `complies` starts `Judge obligations only.` and states violations and compliant cases, including deletions and generalizations. Exclude test trees explicitly when the rule is for production code; otherwise tests can generate false violations. + +```json +{ + "model": "jev-latest", + "state": { + "diff": "REPLACE_BEFORE_USE: PR diff", + "context": "REPLACE_BEFORE_USE: repository and PR context" + }, + "questions": { + "applicable": { + "type": "noul", + "instructions": "Scope check only; do not judge compliance. Apply to ; exclude ." + }, + "complies": { + "type": "noul", + "instructions": "Judge obligations only. Flag ; accept ." + } + } +} +``` + +## Propose and inspect + +Only after the user explicitly asks to propose the rule, run: ```sh -archdev rules propose --repository owner/repo --md-file --jev-file --proposed-path --correction -archdev rules candidates --repository owner/repo +archdev rules propose --repository --md-file --jev-file --proposed-path --correction "" +archdev --json rules candidates --repository ``` -These commands require the Rust CLI release containing `rules` and deployed -candidate storage. If unavailable, retain the draft and report that limitation; -do not substitute the frozen TypeScript CLI or install anything without consent. -Use the current signed-in organization and the repository's installed identity. - -Proposals append immutable caller-owned answers. Recall shows the summary, -complete drafts, proposed path, status, and evidence; your unfolded proposals -are marked pending and are visible only to you until automation folds them. -Do not automatically retry an uncertain write. Recall first and report any -uncertainty. Store no secrets or unrelated transcript. - -Candidates do not activate policy. Do not edit, commit, or adopt repository -policy without the user's authorization. Human adoption is a PR adding the -Markdown/Jev pair. After approval, `rules adopt` can record that PR or commit -as adoption evidence; `rules dismiss` records a reason for dismissal. These -commands append human decisions for automation to fold; they do not add files -or change candidate status directly. No backtesting is required. +Keep `--correction` to the user's relevant steer, without secrets or unrelated conversation. The proposal creates a session candidate; it does not edit repository files or activate a check. Confirm an `open` candidate of kind `add`, source `session`, at the proposed path. The CLI prints its candidate, pending answer, and full theme key; the JSON list's `.data[].theme_key` carries that key. The plain list prints full bodies, and an empty list currently exits 1. If a write's outcome is uncertain, inspect candidates before retrying. + +## Open a rules PR + +Only when the user explicitly asks to open the rules PR, pass the exact full theme key from the proposal or JSON list to: + +```sh +archdev rules pr --repository [...] +``` + +The CLI opens one PR as the signed-in user on an `archdev/rules-*` branch, carrying only the selected pairs, with the ArchCode link first. Confirm the candidate becomes `pr_open`. The user reviews and merges the PR; adoption automation then marks the candidate `adopted`, and future PR verdicts can use the rule. Never add the pair to the repository or open a separate adoption PR by hand. + +For status inspection, `rules candidates --status` accepts one of `open`, `pr_open`, `adopted`, or `dismissed` per call; there is no `--status all`. If `rules pr` reports that opening the PR could not be confirmed, do not retry blindly. Report the error and inspect repository branches and candidate status first. diff --git a/plugins/antigravity/skills/archdev/SKILL.md b/plugins/antigravity/skills/archdev/SKILL.md index f91b796..c1d8ba8 100644 --- a/plugins/antigravity/skills/archdev/SKILL.md +++ b/plugins/antigravity/skills/archdev/SKILL.md @@ -109,12 +109,13 @@ subagents and agents you spawn. - PR reporting requires no local grading, annotations, or stop hold, including Factory and daemon sessions. Follow the host's publication ownership. -## Rule corrections during a session +## Rule candidates from a session -On a standing never/always correction or a repeated correction, follow -[rule candidate capture](references/rule-candidates.md): draft a Markdown/Jev -pair and capture only the supplied correction with the public CLI. Candidates -remain inert until the user authorizes policy adoption through a PR. +When a user asks to turn a correction into a repository rule, follow +[rule candidate capture](references/rule-candidates.md). Discuss a checkable +obligation before drafting. Propose the pair only when the user asks; open a +rules PR only on a separate explicit request. Candidates remain inert until +the user merges a rules PR. ## 1. Bootstrap diff --git a/plugins/antigravity/skills/archdev/references/rule-candidates.md b/plugins/antigravity/skills/archdev/references/rule-candidates.md index 4a420d8..f09861c 100644 --- a/plugins/antigravity/skills/archdev/references/rule-candidates.md +++ b/plugins/antigravity/skills/archdev/references/rule-candidates.md @@ -1,42 +1,54 @@ # Rule candidate capture -When the user gives a standing never/always correction or repeats a correction, -draft a reusable Markdown/Jev rule pair from that correction. Read -`.archdev/rules.yaml` and inspect existing `.md` + `.jev` pairs matched by its -`include` patterns. Use those pairs as format examples. The `adopt_to` directory -(default `.archdev/rules/`) is the destination for the proposed pair. - -When no existing pairs are available, use this default format: Markdown -frontmatter containing `name`, `description`, and `date`, with cited good/bad -examples; a sibling `.jev` using `jev-latest`, exactly the Noul questions -`applicable` and `complies`, and `state.diff` and `state.context` placeholders -starting `REPLACE_BEFORE_USE:`. Keep the supplied constraint and examples; -do not infer unrelated policy. - -Under `adopt_to`, choose -its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, -or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add -the pair at that path, then capture the supplied correction: +Use this flow when a user wants to brainstorm a repository rule from a correction. A useful rule states one obligation a reviewer can see violated in a PR diff. A mechanical check may instead inspect the PR title or description. Ask for the concrete failure and expected change when they are missing. Push back on session-process instructions and pure style preferences: a diff reviewer cannot reliably check them. Do not turn an inferred preference into policy. + +## Draft the pair + +Read `.archdev/rules.yaml` in the target repository. Its `adopt_to` directory defaults to `.archdev/rules/`; choose a language or topic folder under it and follow an existing `.md`/`.jev` pair in that folder if available. Keep drafts in a temporary directory, not in the repository. The proposed path is where a later human-approved PR would place the Markdown file. + +The `.md` frontmatter has `name`, `description`, and `date`. Do not write a `sources` key: `archdev rules propose` stamps the session answer source. In particular, `type: instruction_file` would falsely identify this rule as an instruction-file draft and can cause a retirement proposal when the rule is absent from `AGENTS.md`. The body states the obligation, why it matters, what violates it, what complies, scope and exclusions, good and bad examples with real paths or PR references when available, and an Enforcement note. Exclude secrets and unrelated transcript. + +The sibling `.jev` is JSON with `model`, `state.diff`, `state.context`, and exactly two Noul questions, `applicable` and `complies`. Follow an existing pair's model and state placeholders. `applicable` starts `Scope check only; do not judge compliance.` and names included and excluded paths. `complies` starts `Judge obligations only.` and states violations and compliant cases, including deletions and generalizations. Exclude test trees explicitly when the rule is for production code; otherwise tests can generate false violations. + +```json +{ + "model": "jev-latest", + "state": { + "diff": "REPLACE_BEFORE_USE: PR diff", + "context": "REPLACE_BEFORE_USE: repository and PR context" + }, + "questions": { + "applicable": { + "type": "noul", + "instructions": "Scope check only; do not judge compliance. Apply to ; exclude ." + }, + "complies": { + "type": "noul", + "instructions": "Judge obligations only. Flag ; accept ." + } + } +} +``` + +## Propose and inspect + +Only after the user explicitly asks to propose the rule, run: ```sh -archdev rules propose --repository owner/repo --md-file --jev-file --proposed-path --correction -archdev rules candidates --repository owner/repo +archdev rules propose --repository --md-file --jev-file --proposed-path --correction "" +archdev --json rules candidates --repository ``` -These commands require the Rust CLI release containing `rules` and deployed -candidate storage. If unavailable, retain the draft and report that limitation; -do not substitute the frozen TypeScript CLI or install anything without consent. -Use the current signed-in organization and the repository's installed identity. - -Proposals append immutable caller-owned answers. Recall shows the summary, -complete drafts, proposed path, status, and evidence; your unfolded proposals -are marked pending and are visible only to you until automation folds them. -Do not automatically retry an uncertain write. Recall first and report any -uncertainty. Store no secrets or unrelated transcript. - -Candidates do not activate policy. Do not edit, commit, or adopt repository -policy without the user's authorization. Human adoption is a PR adding the -Markdown/Jev pair. After approval, `rules adopt` can record that PR or commit -as adoption evidence; `rules dismiss` records a reason for dismissal. These -commands append human decisions for automation to fold; they do not add files -or change candidate status directly. No backtesting is required. +Keep `--correction` to the user's relevant steer, without secrets or unrelated conversation. The proposal creates a session candidate; it does not edit repository files or activate a check. Confirm an `open` candidate of kind `add`, source `session`, at the proposed path. The CLI prints its candidate, pending answer, and full theme key; the JSON list's `.data[].theme_key` carries that key. The plain list prints full bodies, and an empty list currently exits 1. If a write's outcome is uncertain, inspect candidates before retrying. + +## Open a rules PR + +Only when the user explicitly asks to open the rules PR, pass the exact full theme key from the proposal or JSON list to: + +```sh +archdev rules pr --repository [...] +``` + +The CLI opens one PR as the signed-in user on an `archdev/rules-*` branch, carrying only the selected pairs, with the ArchCode link first. Confirm the candidate becomes `pr_open`. The user reviews and merges the PR; adoption automation then marks the candidate `adopted`, and future PR verdicts can use the rule. Never add the pair to the repository or open a separate adoption PR by hand. + +For status inspection, `rules candidates --status` accepts one of `open`, `pr_open`, `adopted`, or `dismissed` per call; there is no `--status all`. If `rules pr` reports that opening the PR could not be confirmed, do not retry blindly. Report the error and inspect repository branches and candidate status first. diff --git a/plugins/claude/skills/archdev/SKILL.md b/plugins/claude/skills/archdev/SKILL.md index f91b796..c1d8ba8 100644 --- a/plugins/claude/skills/archdev/SKILL.md +++ b/plugins/claude/skills/archdev/SKILL.md @@ -109,12 +109,13 @@ subagents and agents you spawn. - PR reporting requires no local grading, annotations, or stop hold, including Factory and daemon sessions. Follow the host's publication ownership. -## Rule corrections during a session +## Rule candidates from a session -On a standing never/always correction or a repeated correction, follow -[rule candidate capture](references/rule-candidates.md): draft a Markdown/Jev -pair and capture only the supplied correction with the public CLI. Candidates -remain inert until the user authorizes policy adoption through a PR. +When a user asks to turn a correction into a repository rule, follow +[rule candidate capture](references/rule-candidates.md). Discuss a checkable +obligation before drafting. Propose the pair only when the user asks; open a +rules PR only on a separate explicit request. Candidates remain inert until +the user merges a rules PR. ## 1. Bootstrap diff --git a/plugins/claude/skills/archdev/references/rule-candidates.md b/plugins/claude/skills/archdev/references/rule-candidates.md index 4a420d8..f09861c 100644 --- a/plugins/claude/skills/archdev/references/rule-candidates.md +++ b/plugins/claude/skills/archdev/references/rule-candidates.md @@ -1,42 +1,54 @@ # Rule candidate capture -When the user gives a standing never/always correction or repeats a correction, -draft a reusable Markdown/Jev rule pair from that correction. Read -`.archdev/rules.yaml` and inspect existing `.md` + `.jev` pairs matched by its -`include` patterns. Use those pairs as format examples. The `adopt_to` directory -(default `.archdev/rules/`) is the destination for the proposed pair. - -When no existing pairs are available, use this default format: Markdown -frontmatter containing `name`, `description`, and `date`, with cited good/bad -examples; a sibling `.jev` using `jev-latest`, exactly the Noul questions -`applicable` and `complies`, and `state.diff` and `state.context` placeholders -starting `REPLACE_BEFORE_USE:`. Keep the supplied constraint and examples; -do not infer unrelated policy. - -Under `adopt_to`, choose -its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, -or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add -the pair at that path, then capture the supplied correction: +Use this flow when a user wants to brainstorm a repository rule from a correction. A useful rule states one obligation a reviewer can see violated in a PR diff. A mechanical check may instead inspect the PR title or description. Ask for the concrete failure and expected change when they are missing. Push back on session-process instructions and pure style preferences: a diff reviewer cannot reliably check them. Do not turn an inferred preference into policy. + +## Draft the pair + +Read `.archdev/rules.yaml` in the target repository. Its `adopt_to` directory defaults to `.archdev/rules/`; choose a language or topic folder under it and follow an existing `.md`/`.jev` pair in that folder if available. Keep drafts in a temporary directory, not in the repository. The proposed path is where a later human-approved PR would place the Markdown file. + +The `.md` frontmatter has `name`, `description`, and `date`. Do not write a `sources` key: `archdev rules propose` stamps the session answer source. In particular, `type: instruction_file` would falsely identify this rule as an instruction-file draft and can cause a retirement proposal when the rule is absent from `AGENTS.md`. The body states the obligation, why it matters, what violates it, what complies, scope and exclusions, good and bad examples with real paths or PR references when available, and an Enforcement note. Exclude secrets and unrelated transcript. + +The sibling `.jev` is JSON with `model`, `state.diff`, `state.context`, and exactly two Noul questions, `applicable` and `complies`. Follow an existing pair's model and state placeholders. `applicable` starts `Scope check only; do not judge compliance.` and names included and excluded paths. `complies` starts `Judge obligations only.` and states violations and compliant cases, including deletions and generalizations. Exclude test trees explicitly when the rule is for production code; otherwise tests can generate false violations. + +```json +{ + "model": "jev-latest", + "state": { + "diff": "REPLACE_BEFORE_USE: PR diff", + "context": "REPLACE_BEFORE_USE: repository and PR context" + }, + "questions": { + "applicable": { + "type": "noul", + "instructions": "Scope check only; do not judge compliance. Apply to ; exclude ." + }, + "complies": { + "type": "noul", + "instructions": "Judge obligations only. Flag ; accept ." + } + } +} +``` + +## Propose and inspect + +Only after the user explicitly asks to propose the rule, run: ```sh -archdev rules propose --repository owner/repo --md-file --jev-file --proposed-path --correction -archdev rules candidates --repository owner/repo +archdev rules propose --repository --md-file --jev-file --proposed-path --correction "" +archdev --json rules candidates --repository ``` -These commands require the Rust CLI release containing `rules` and deployed -candidate storage. If unavailable, retain the draft and report that limitation; -do not substitute the frozen TypeScript CLI or install anything without consent. -Use the current signed-in organization and the repository's installed identity. - -Proposals append immutable caller-owned answers. Recall shows the summary, -complete drafts, proposed path, status, and evidence; your unfolded proposals -are marked pending and are visible only to you until automation folds them. -Do not automatically retry an uncertain write. Recall first and report any -uncertainty. Store no secrets or unrelated transcript. - -Candidates do not activate policy. Do not edit, commit, or adopt repository -policy without the user's authorization. Human adoption is a PR adding the -Markdown/Jev pair. After approval, `rules adopt` can record that PR or commit -as adoption evidence; `rules dismiss` records a reason for dismissal. These -commands append human decisions for automation to fold; they do not add files -or change candidate status directly. No backtesting is required. +Keep `--correction` to the user's relevant steer, without secrets or unrelated conversation. The proposal creates a session candidate; it does not edit repository files or activate a check. Confirm an `open` candidate of kind `add`, source `session`, at the proposed path. The CLI prints its candidate, pending answer, and full theme key; the JSON list's `.data[].theme_key` carries that key. The plain list prints full bodies, and an empty list currently exits 1. If a write's outcome is uncertain, inspect candidates before retrying. + +## Open a rules PR + +Only when the user explicitly asks to open the rules PR, pass the exact full theme key from the proposal or JSON list to: + +```sh +archdev rules pr --repository [...] +``` + +The CLI opens one PR as the signed-in user on an `archdev/rules-*` branch, carrying only the selected pairs, with the ArchCode link first. Confirm the candidate becomes `pr_open`. The user reviews and merges the PR; adoption automation then marks the candidate `adopted`, and future PR verdicts can use the rule. Never add the pair to the repository or open a separate adoption PR by hand. + +For status inspection, `rules candidates --status` accepts one of `open`, `pr_open`, `adopted`, or `dismissed` per call; there is no `--status all`. If `rules pr` reports that opening the PR could not be confirmed, do not retry blindly. Report the error and inspect repository branches and candidate status first. diff --git a/plugins/codex/skills/archdev/SKILL.md b/plugins/codex/skills/archdev/SKILL.md index f91b796..c1d8ba8 100644 --- a/plugins/codex/skills/archdev/SKILL.md +++ b/plugins/codex/skills/archdev/SKILL.md @@ -109,12 +109,13 @@ subagents and agents you spawn. - PR reporting requires no local grading, annotations, or stop hold, including Factory and daemon sessions. Follow the host's publication ownership. -## Rule corrections during a session +## Rule candidates from a session -On a standing never/always correction or a repeated correction, follow -[rule candidate capture](references/rule-candidates.md): draft a Markdown/Jev -pair and capture only the supplied correction with the public CLI. Candidates -remain inert until the user authorizes policy adoption through a PR. +When a user asks to turn a correction into a repository rule, follow +[rule candidate capture](references/rule-candidates.md). Discuss a checkable +obligation before drafting. Propose the pair only when the user asks; open a +rules PR only on a separate explicit request. Candidates remain inert until +the user merges a rules PR. ## 1. Bootstrap diff --git a/plugins/codex/skills/archdev/references/rule-candidates.md b/plugins/codex/skills/archdev/references/rule-candidates.md index 4a420d8..f09861c 100644 --- a/plugins/codex/skills/archdev/references/rule-candidates.md +++ b/plugins/codex/skills/archdev/references/rule-candidates.md @@ -1,42 +1,54 @@ # Rule candidate capture -When the user gives a standing never/always correction or repeats a correction, -draft a reusable Markdown/Jev rule pair from that correction. Read -`.archdev/rules.yaml` and inspect existing `.md` + `.jev` pairs matched by its -`include` patterns. Use those pairs as format examples. The `adopt_to` directory -(default `.archdev/rules/`) is the destination for the proposed pair. - -When no existing pairs are available, use this default format: Markdown -frontmatter containing `name`, `description`, and `date`, with cited good/bad -examples; a sibling `.jev` using `jev-latest`, exactly the Noul questions -`applicable` and `complies`, and `state.diff` and `state.context` placeholders -starting `REPLACE_BEFORE_USE:`. Keep the supplied constraint and examples; -do not infer unrelated policy. - -Under `adopt_to`, choose -its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, -or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add -the pair at that path, then capture the supplied correction: +Use this flow when a user wants to brainstorm a repository rule from a correction. A useful rule states one obligation a reviewer can see violated in a PR diff. A mechanical check may instead inspect the PR title or description. Ask for the concrete failure and expected change when they are missing. Push back on session-process instructions and pure style preferences: a diff reviewer cannot reliably check them. Do not turn an inferred preference into policy. + +## Draft the pair + +Read `.archdev/rules.yaml` in the target repository. Its `adopt_to` directory defaults to `.archdev/rules/`; choose a language or topic folder under it and follow an existing `.md`/`.jev` pair in that folder if available. Keep drafts in a temporary directory, not in the repository. The proposed path is where a later human-approved PR would place the Markdown file. + +The `.md` frontmatter has `name`, `description`, and `date`. Do not write a `sources` key: `archdev rules propose` stamps the session answer source. In particular, `type: instruction_file` would falsely identify this rule as an instruction-file draft and can cause a retirement proposal when the rule is absent from `AGENTS.md`. The body states the obligation, why it matters, what violates it, what complies, scope and exclusions, good and bad examples with real paths or PR references when available, and an Enforcement note. Exclude secrets and unrelated transcript. + +The sibling `.jev` is JSON with `model`, `state.diff`, `state.context`, and exactly two Noul questions, `applicable` and `complies`. Follow an existing pair's model and state placeholders. `applicable` starts `Scope check only; do not judge compliance.` and names included and excluded paths. `complies` starts `Judge obligations only.` and states violations and compliant cases, including deletions and generalizations. Exclude test trees explicitly when the rule is for production code; otherwise tests can generate false violations. + +```json +{ + "model": "jev-latest", + "state": { + "diff": "REPLACE_BEFORE_USE: PR diff", + "context": "REPLACE_BEFORE_USE: repository and PR context" + }, + "questions": { + "applicable": { + "type": "noul", + "instructions": "Scope check only; do not judge compliance. Apply to ; exclude ." + }, + "complies": { + "type": "noul", + "instructions": "Judge obligations only. Flag ; accept ." + } + } +} +``` + +## Propose and inspect + +Only after the user explicitly asks to propose the rule, run: ```sh -archdev rules propose --repository owner/repo --md-file --jev-file --proposed-path --correction -archdev rules candidates --repository owner/repo +archdev rules propose --repository --md-file --jev-file --proposed-path --correction "" +archdev --json rules candidates --repository ``` -These commands require the Rust CLI release containing `rules` and deployed -candidate storage. If unavailable, retain the draft and report that limitation; -do not substitute the frozen TypeScript CLI or install anything without consent. -Use the current signed-in organization and the repository's installed identity. - -Proposals append immutable caller-owned answers. Recall shows the summary, -complete drafts, proposed path, status, and evidence; your unfolded proposals -are marked pending and are visible only to you until automation folds them. -Do not automatically retry an uncertain write. Recall first and report any -uncertainty. Store no secrets or unrelated transcript. - -Candidates do not activate policy. Do not edit, commit, or adopt repository -policy without the user's authorization. Human adoption is a PR adding the -Markdown/Jev pair. After approval, `rules adopt` can record that PR or commit -as adoption evidence; `rules dismiss` records a reason for dismissal. These -commands append human decisions for automation to fold; they do not add files -or change candidate status directly. No backtesting is required. +Keep `--correction` to the user's relevant steer, without secrets or unrelated conversation. The proposal creates a session candidate; it does not edit repository files or activate a check. Confirm an `open` candidate of kind `add`, source `session`, at the proposed path. The CLI prints its candidate, pending answer, and full theme key; the JSON list's `.data[].theme_key` carries that key. The plain list prints full bodies, and an empty list currently exits 1. If a write's outcome is uncertain, inspect candidates before retrying. + +## Open a rules PR + +Only when the user explicitly asks to open the rules PR, pass the exact full theme key from the proposal or JSON list to: + +```sh +archdev rules pr --repository [...] +``` + +The CLI opens one PR as the signed-in user on an `archdev/rules-*` branch, carrying only the selected pairs, with the ArchCode link first. Confirm the candidate becomes `pr_open`. The user reviews and merges the PR; adoption automation then marks the candidate `adopted`, and future PR verdicts can use the rule. Never add the pair to the repository or open a separate adoption PR by hand. + +For status inspection, `rules candidates --status` accepts one of `open`, `pr_open`, `adopted`, or `dismissed` per call; there is no `--status all`. If `rules pr` reports that opening the PR could not be confirmed, do not retry blindly. Report the error and inspect repository branches and candidate status first. diff --git a/plugins/copilot/skills/archdev/SKILL.md b/plugins/copilot/skills/archdev/SKILL.md index f91b796..c1d8ba8 100644 --- a/plugins/copilot/skills/archdev/SKILL.md +++ b/plugins/copilot/skills/archdev/SKILL.md @@ -109,12 +109,13 @@ subagents and agents you spawn. - PR reporting requires no local grading, annotations, or stop hold, including Factory and daemon sessions. Follow the host's publication ownership. -## Rule corrections during a session +## Rule candidates from a session -On a standing never/always correction or a repeated correction, follow -[rule candidate capture](references/rule-candidates.md): draft a Markdown/Jev -pair and capture only the supplied correction with the public CLI. Candidates -remain inert until the user authorizes policy adoption through a PR. +When a user asks to turn a correction into a repository rule, follow +[rule candidate capture](references/rule-candidates.md). Discuss a checkable +obligation before drafting. Propose the pair only when the user asks; open a +rules PR only on a separate explicit request. Candidates remain inert until +the user merges a rules PR. ## 1. Bootstrap diff --git a/plugins/copilot/skills/archdev/references/rule-candidates.md b/plugins/copilot/skills/archdev/references/rule-candidates.md index 4a420d8..f09861c 100644 --- a/plugins/copilot/skills/archdev/references/rule-candidates.md +++ b/plugins/copilot/skills/archdev/references/rule-candidates.md @@ -1,42 +1,54 @@ # Rule candidate capture -When the user gives a standing never/always correction or repeats a correction, -draft a reusable Markdown/Jev rule pair from that correction. Read -`.archdev/rules.yaml` and inspect existing `.md` + `.jev` pairs matched by its -`include` patterns. Use those pairs as format examples. The `adopt_to` directory -(default `.archdev/rules/`) is the destination for the proposed pair. - -When no existing pairs are available, use this default format: Markdown -frontmatter containing `name`, `description`, and `date`, with cited good/bad -examples; a sibling `.jev` using `jev-latest`, exactly the Noul questions -`applicable` and `complies`, and `state.diff` and `state.context` placeholders -starting `REPLACE_BEFORE_USE:`. Keep the supplied constraint and examples; -do not infer unrelated policy. - -Under `adopt_to`, choose -its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, -or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add -the pair at that path, then capture the supplied correction: +Use this flow when a user wants to brainstorm a repository rule from a correction. A useful rule states one obligation a reviewer can see violated in a PR diff. A mechanical check may instead inspect the PR title or description. Ask for the concrete failure and expected change when they are missing. Push back on session-process instructions and pure style preferences: a diff reviewer cannot reliably check them. Do not turn an inferred preference into policy. + +## Draft the pair + +Read `.archdev/rules.yaml` in the target repository. Its `adopt_to` directory defaults to `.archdev/rules/`; choose a language or topic folder under it and follow an existing `.md`/`.jev` pair in that folder if available. Keep drafts in a temporary directory, not in the repository. The proposed path is where a later human-approved PR would place the Markdown file. + +The `.md` frontmatter has `name`, `description`, and `date`. Do not write a `sources` key: `archdev rules propose` stamps the session answer source. In particular, `type: instruction_file` would falsely identify this rule as an instruction-file draft and can cause a retirement proposal when the rule is absent from `AGENTS.md`. The body states the obligation, why it matters, what violates it, what complies, scope and exclusions, good and bad examples with real paths or PR references when available, and an Enforcement note. Exclude secrets and unrelated transcript. + +The sibling `.jev` is JSON with `model`, `state.diff`, `state.context`, and exactly two Noul questions, `applicable` and `complies`. Follow an existing pair's model and state placeholders. `applicable` starts `Scope check only; do not judge compliance.` and names included and excluded paths. `complies` starts `Judge obligations only.` and states violations and compliant cases, including deletions and generalizations. Exclude test trees explicitly when the rule is for production code; otherwise tests can generate false violations. + +```json +{ + "model": "jev-latest", + "state": { + "diff": "REPLACE_BEFORE_USE: PR diff", + "context": "REPLACE_BEFORE_USE: repository and PR context" + }, + "questions": { + "applicable": { + "type": "noul", + "instructions": "Scope check only; do not judge compliance. Apply to ; exclude ." + }, + "complies": { + "type": "noul", + "instructions": "Judge obligations only. Flag ; accept ." + } + } +} +``` + +## Propose and inspect + +Only after the user explicitly asks to propose the rule, run: ```sh -archdev rules propose --repository owner/repo --md-file --jev-file --proposed-path --correction -archdev rules candidates --repository owner/repo +archdev rules propose --repository --md-file --jev-file --proposed-path --correction "" +archdev --json rules candidates --repository ``` -These commands require the Rust CLI release containing `rules` and deployed -candidate storage. If unavailable, retain the draft and report that limitation; -do not substitute the frozen TypeScript CLI or install anything without consent. -Use the current signed-in organization and the repository's installed identity. - -Proposals append immutable caller-owned answers. Recall shows the summary, -complete drafts, proposed path, status, and evidence; your unfolded proposals -are marked pending and are visible only to you until automation folds them. -Do not automatically retry an uncertain write. Recall first and report any -uncertainty. Store no secrets or unrelated transcript. - -Candidates do not activate policy. Do not edit, commit, or adopt repository -policy without the user's authorization. Human adoption is a PR adding the -Markdown/Jev pair. After approval, `rules adopt` can record that PR or commit -as adoption evidence; `rules dismiss` records a reason for dismissal. These -commands append human decisions for automation to fold; they do not add files -or change candidate status directly. No backtesting is required. +Keep `--correction` to the user's relevant steer, without secrets or unrelated conversation. The proposal creates a session candidate; it does not edit repository files or activate a check. Confirm an `open` candidate of kind `add`, source `session`, at the proposed path. The CLI prints its candidate, pending answer, and full theme key; the JSON list's `.data[].theme_key` carries that key. The plain list prints full bodies, and an empty list currently exits 1. If a write's outcome is uncertain, inspect candidates before retrying. + +## Open a rules PR + +Only when the user explicitly asks to open the rules PR, pass the exact full theme key from the proposal or JSON list to: + +```sh +archdev rules pr --repository [...] +``` + +The CLI opens one PR as the signed-in user on an `archdev/rules-*` branch, carrying only the selected pairs, with the ArchCode link first. Confirm the candidate becomes `pr_open`. The user reviews and merges the PR; adoption automation then marks the candidate `adopted`, and future PR verdicts can use the rule. Never add the pair to the repository or open a separate adoption PR by hand. + +For status inspection, `rules candidates --status` accepts one of `open`, `pr_open`, `adopted`, or `dismissed` per call; there is no `--status all`. If `rules pr` reports that opening the PR could not be confirmed, do not retry blindly. Report the error and inspect repository branches and candidate status first. diff --git a/plugins/cursor/skills/archdev/SKILL.md b/plugins/cursor/skills/archdev/SKILL.md index f91b796..c1d8ba8 100644 --- a/plugins/cursor/skills/archdev/SKILL.md +++ b/plugins/cursor/skills/archdev/SKILL.md @@ -109,12 +109,13 @@ subagents and agents you spawn. - PR reporting requires no local grading, annotations, or stop hold, including Factory and daemon sessions. Follow the host's publication ownership. -## Rule corrections during a session +## Rule candidates from a session -On a standing never/always correction or a repeated correction, follow -[rule candidate capture](references/rule-candidates.md): draft a Markdown/Jev -pair and capture only the supplied correction with the public CLI. Candidates -remain inert until the user authorizes policy adoption through a PR. +When a user asks to turn a correction into a repository rule, follow +[rule candidate capture](references/rule-candidates.md). Discuss a checkable +obligation before drafting. Propose the pair only when the user asks; open a +rules PR only on a separate explicit request. Candidates remain inert until +the user merges a rules PR. ## 1. Bootstrap diff --git a/plugins/cursor/skills/archdev/references/rule-candidates.md b/plugins/cursor/skills/archdev/references/rule-candidates.md index 4a420d8..f09861c 100644 --- a/plugins/cursor/skills/archdev/references/rule-candidates.md +++ b/plugins/cursor/skills/archdev/references/rule-candidates.md @@ -1,42 +1,54 @@ # Rule candidate capture -When the user gives a standing never/always correction or repeats a correction, -draft a reusable Markdown/Jev rule pair from that correction. Read -`.archdev/rules.yaml` and inspect existing `.md` + `.jev` pairs matched by its -`include` patterns. Use those pairs as format examples. The `adopt_to` directory -(default `.archdev/rules/`) is the destination for the proposed pair. - -When no existing pairs are available, use this default format: Markdown -frontmatter containing `name`, `description`, and `date`, with cited good/bad -examples; a sibling `.jev` using `jev-latest`, exactly the Noul questions -`applicable` and `complies`, and `state.diff` and `state.context` placeholders -starting `REPLACE_BEFORE_USE:`. Keep the supplied constraint and examples; -do not infer unrelated policy. - -Under `adopt_to`, choose -its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, -or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add -the pair at that path, then capture the supplied correction: +Use this flow when a user wants to brainstorm a repository rule from a correction. A useful rule states one obligation a reviewer can see violated in a PR diff. A mechanical check may instead inspect the PR title or description. Ask for the concrete failure and expected change when they are missing. Push back on session-process instructions and pure style preferences: a diff reviewer cannot reliably check them. Do not turn an inferred preference into policy. + +## Draft the pair + +Read `.archdev/rules.yaml` in the target repository. Its `adopt_to` directory defaults to `.archdev/rules/`; choose a language or topic folder under it and follow an existing `.md`/`.jev` pair in that folder if available. Keep drafts in a temporary directory, not in the repository. The proposed path is where a later human-approved PR would place the Markdown file. + +The `.md` frontmatter has `name`, `description`, and `date`. Do not write a `sources` key: `archdev rules propose` stamps the session answer source. In particular, `type: instruction_file` would falsely identify this rule as an instruction-file draft and can cause a retirement proposal when the rule is absent from `AGENTS.md`. The body states the obligation, why it matters, what violates it, what complies, scope and exclusions, good and bad examples with real paths or PR references when available, and an Enforcement note. Exclude secrets and unrelated transcript. + +The sibling `.jev` is JSON with `model`, `state.diff`, `state.context`, and exactly two Noul questions, `applicable` and `complies`. Follow an existing pair's model and state placeholders. `applicable` starts `Scope check only; do not judge compliance.` and names included and excluded paths. `complies` starts `Judge obligations only.` and states violations and compliant cases, including deletions and generalizations. Exclude test trees explicitly when the rule is for production code; otherwise tests can generate false violations. + +```json +{ + "model": "jev-latest", + "state": { + "diff": "REPLACE_BEFORE_USE: PR diff", + "context": "REPLACE_BEFORE_USE: repository and PR context" + }, + "questions": { + "applicable": { + "type": "noul", + "instructions": "Scope check only; do not judge compliance. Apply to ; exclude ." + }, + "complies": { + "type": "noul", + "instructions": "Judge obligations only. Flag ; accept ." + } + } +} +``` + +## Propose and inspect + +Only after the user explicitly asks to propose the rule, run: ```sh -archdev rules propose --repository owner/repo --md-file --jev-file --proposed-path --correction -archdev rules candidates --repository owner/repo +archdev rules propose --repository --md-file --jev-file --proposed-path --correction "" +archdev --json rules candidates --repository ``` -These commands require the Rust CLI release containing `rules` and deployed -candidate storage. If unavailable, retain the draft and report that limitation; -do not substitute the frozen TypeScript CLI or install anything without consent. -Use the current signed-in organization and the repository's installed identity. - -Proposals append immutable caller-owned answers. Recall shows the summary, -complete drafts, proposed path, status, and evidence; your unfolded proposals -are marked pending and are visible only to you until automation folds them. -Do not automatically retry an uncertain write. Recall first and report any -uncertainty. Store no secrets or unrelated transcript. - -Candidates do not activate policy. Do not edit, commit, or adopt repository -policy without the user's authorization. Human adoption is a PR adding the -Markdown/Jev pair. After approval, `rules adopt` can record that PR or commit -as adoption evidence; `rules dismiss` records a reason for dismissal. These -commands append human decisions for automation to fold; they do not add files -or change candidate status directly. No backtesting is required. +Keep `--correction` to the user's relevant steer, without secrets or unrelated conversation. The proposal creates a session candidate; it does not edit repository files or activate a check. Confirm an `open` candidate of kind `add`, source `session`, at the proposed path. The CLI prints its candidate, pending answer, and full theme key; the JSON list's `.data[].theme_key` carries that key. The plain list prints full bodies, and an empty list currently exits 1. If a write's outcome is uncertain, inspect candidates before retrying. + +## Open a rules PR + +Only when the user explicitly asks to open the rules PR, pass the exact full theme key from the proposal or JSON list to: + +```sh +archdev rules pr --repository [...] +``` + +The CLI opens one PR as the signed-in user on an `archdev/rules-*` branch, carrying only the selected pairs, with the ArchCode link first. Confirm the candidate becomes `pr_open`. The user reviews and merges the PR; adoption automation then marks the candidate `adopted`, and future PR verdicts can use the rule. Never add the pair to the repository or open a separate adoption PR by hand. + +For status inspection, `rules candidates --status` accepts one of `open`, `pr_open`, `adopted`, or `dismissed` per call; there is no `--status all`. If `rules pr` reports that opening the PR could not be confirmed, do not retry blindly. Report the error and inspect repository branches and candidate status first. diff --git a/plugins/grok/skills/archdev/SKILL.md b/plugins/grok/skills/archdev/SKILL.md index f91b796..c1d8ba8 100644 --- a/plugins/grok/skills/archdev/SKILL.md +++ b/plugins/grok/skills/archdev/SKILL.md @@ -109,12 +109,13 @@ subagents and agents you spawn. - PR reporting requires no local grading, annotations, or stop hold, including Factory and daemon sessions. Follow the host's publication ownership. -## Rule corrections during a session +## Rule candidates from a session -On a standing never/always correction or a repeated correction, follow -[rule candidate capture](references/rule-candidates.md): draft a Markdown/Jev -pair and capture only the supplied correction with the public CLI. Candidates -remain inert until the user authorizes policy adoption through a PR. +When a user asks to turn a correction into a repository rule, follow +[rule candidate capture](references/rule-candidates.md). Discuss a checkable +obligation before drafting. Propose the pair only when the user asks; open a +rules PR only on a separate explicit request. Candidates remain inert until +the user merges a rules PR. ## 1. Bootstrap diff --git a/plugins/grok/skills/archdev/references/rule-candidates.md b/plugins/grok/skills/archdev/references/rule-candidates.md index 4a420d8..f09861c 100644 --- a/plugins/grok/skills/archdev/references/rule-candidates.md +++ b/plugins/grok/skills/archdev/references/rule-candidates.md @@ -1,42 +1,54 @@ # Rule candidate capture -When the user gives a standing never/always correction or repeats a correction, -draft a reusable Markdown/Jev rule pair from that correction. Read -`.archdev/rules.yaml` and inspect existing `.md` + `.jev` pairs matched by its -`include` patterns. Use those pairs as format examples. The `adopt_to` directory -(default `.archdev/rules/`) is the destination for the proposed pair. - -When no existing pairs are available, use this default format: Markdown -frontmatter containing `name`, `description`, and `date`, with cited good/bad -examples; a sibling `.jev` using `jev-latest`, exactly the Noul questions -`applicable` and `complies`, and `state.diff` and `state.context` placeholders -starting `REPLACE_BEFORE_USE:`. Keep the supplied constraint and examples; -do not infer unrelated policy. - -Under `adopt_to`, choose -its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, -or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add -the pair at that path, then capture the supplied correction: +Use this flow when a user wants to brainstorm a repository rule from a correction. A useful rule states one obligation a reviewer can see violated in a PR diff. A mechanical check may instead inspect the PR title or description. Ask for the concrete failure and expected change when they are missing. Push back on session-process instructions and pure style preferences: a diff reviewer cannot reliably check them. Do not turn an inferred preference into policy. + +## Draft the pair + +Read `.archdev/rules.yaml` in the target repository. Its `adopt_to` directory defaults to `.archdev/rules/`; choose a language or topic folder under it and follow an existing `.md`/`.jev` pair in that folder if available. Keep drafts in a temporary directory, not in the repository. The proposed path is where a later human-approved PR would place the Markdown file. + +The `.md` frontmatter has `name`, `description`, and `date`. Do not write a `sources` key: `archdev rules propose` stamps the session answer source. In particular, `type: instruction_file` would falsely identify this rule as an instruction-file draft and can cause a retirement proposal when the rule is absent from `AGENTS.md`. The body states the obligation, why it matters, what violates it, what complies, scope and exclusions, good and bad examples with real paths or PR references when available, and an Enforcement note. Exclude secrets and unrelated transcript. + +The sibling `.jev` is JSON with `model`, `state.diff`, `state.context`, and exactly two Noul questions, `applicable` and `complies`. Follow an existing pair's model and state placeholders. `applicable` starts `Scope check only; do not judge compliance.` and names included and excluded paths. `complies` starts `Judge obligations only.` and states violations and compliant cases, including deletions and generalizations. Exclude test trees explicitly when the rule is for production code; otherwise tests can generate false violations. + +```json +{ + "model": "jev-latest", + "state": { + "diff": "REPLACE_BEFORE_USE: PR diff", + "context": "REPLACE_BEFORE_USE: repository and PR context" + }, + "questions": { + "applicable": { + "type": "noul", + "instructions": "Scope check only; do not judge compliance. Apply to ; exclude ." + }, + "complies": { + "type": "noul", + "instructions": "Judge obligations only. Flag ; accept ." + } + } +} +``` + +## Propose and inspect + +Only after the user explicitly asks to propose the rule, run: ```sh -archdev rules propose --repository owner/repo --md-file --jev-file --proposed-path --correction -archdev rules candidates --repository owner/repo +archdev rules propose --repository --md-file --jev-file --proposed-path --correction "" +archdev --json rules candidates --repository ``` -These commands require the Rust CLI release containing `rules` and deployed -candidate storage. If unavailable, retain the draft and report that limitation; -do not substitute the frozen TypeScript CLI or install anything without consent. -Use the current signed-in organization and the repository's installed identity. - -Proposals append immutable caller-owned answers. Recall shows the summary, -complete drafts, proposed path, status, and evidence; your unfolded proposals -are marked pending and are visible only to you until automation folds them. -Do not automatically retry an uncertain write. Recall first and report any -uncertainty. Store no secrets or unrelated transcript. - -Candidates do not activate policy. Do not edit, commit, or adopt repository -policy without the user's authorization. Human adoption is a PR adding the -Markdown/Jev pair. After approval, `rules adopt` can record that PR or commit -as adoption evidence; `rules dismiss` records a reason for dismissal. These -commands append human decisions for automation to fold; they do not add files -or change candidate status directly. No backtesting is required. +Keep `--correction` to the user's relevant steer, without secrets or unrelated conversation. The proposal creates a session candidate; it does not edit repository files or activate a check. Confirm an `open` candidate of kind `add`, source `session`, at the proposed path. The CLI prints its candidate, pending answer, and full theme key; the JSON list's `.data[].theme_key` carries that key. The plain list prints full bodies, and an empty list currently exits 1. If a write's outcome is uncertain, inspect candidates before retrying. + +## Open a rules PR + +Only when the user explicitly asks to open the rules PR, pass the exact full theme key from the proposal or JSON list to: + +```sh +archdev rules pr --repository [...] +``` + +The CLI opens one PR as the signed-in user on an `archdev/rules-*` branch, carrying only the selected pairs, with the ArchCode link first. Confirm the candidate becomes `pr_open`. The user reviews and merges the PR; adoption automation then marks the candidate `adopted`, and future PR verdicts can use the rule. Never add the pair to the repository or open a separate adoption PR by hand. + +For status inspection, `rules candidates --status` accepts one of `open`, `pr_open`, `adopted`, or `dismissed` per call; there is no `--status all`. If `rules pr` reports that opening the PR could not be confirmed, do not retry blindly. Report the error and inspect repository branches and candidate status first. diff --git a/plugins/opencode/skills/archdev/SKILL.md b/plugins/opencode/skills/archdev/SKILL.md index f91b796..c1d8ba8 100644 --- a/plugins/opencode/skills/archdev/SKILL.md +++ b/plugins/opencode/skills/archdev/SKILL.md @@ -109,12 +109,13 @@ subagents and agents you spawn. - PR reporting requires no local grading, annotations, or stop hold, including Factory and daemon sessions. Follow the host's publication ownership. -## Rule corrections during a session +## Rule candidates from a session -On a standing never/always correction or a repeated correction, follow -[rule candidate capture](references/rule-candidates.md): draft a Markdown/Jev -pair and capture only the supplied correction with the public CLI. Candidates -remain inert until the user authorizes policy adoption through a PR. +When a user asks to turn a correction into a repository rule, follow +[rule candidate capture](references/rule-candidates.md). Discuss a checkable +obligation before drafting. Propose the pair only when the user asks; open a +rules PR only on a separate explicit request. Candidates remain inert until +the user merges a rules PR. ## 1. Bootstrap diff --git a/plugins/opencode/skills/archdev/references/rule-candidates.md b/plugins/opencode/skills/archdev/references/rule-candidates.md index 4a420d8..f09861c 100644 --- a/plugins/opencode/skills/archdev/references/rule-candidates.md +++ b/plugins/opencode/skills/archdev/references/rule-candidates.md @@ -1,42 +1,54 @@ # Rule candidate capture -When the user gives a standing never/always correction or repeats a correction, -draft a reusable Markdown/Jev rule pair from that correction. Read -`.archdev/rules.yaml` and inspect existing `.md` + `.jev` pairs matched by its -`include` patterns. Use those pairs as format examples. The `adopt_to` directory -(default `.archdev/rules/`) is the destination for the proposed pair. - -When no existing pairs are available, use this default format: Markdown -frontmatter containing `name`, `description`, and `date`, with cited good/bad -examples; a sibling `.jev` using `jev-latest`, exactly the Noul questions -`applicable` and `complies`, and `state.diff` and `state.context` placeholders -starting `REPLACE_BEFORE_USE:`. Keep the supplied constraint and examples; -do not infer unrelated policy. - -Under `adopt_to`, choose -its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, -or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add -the pair at that path, then capture the supplied correction: +Use this flow when a user wants to brainstorm a repository rule from a correction. A useful rule states one obligation a reviewer can see violated in a PR diff. A mechanical check may instead inspect the PR title or description. Ask for the concrete failure and expected change when they are missing. Push back on session-process instructions and pure style preferences: a diff reviewer cannot reliably check them. Do not turn an inferred preference into policy. + +## Draft the pair + +Read `.archdev/rules.yaml` in the target repository. Its `adopt_to` directory defaults to `.archdev/rules/`; choose a language or topic folder under it and follow an existing `.md`/`.jev` pair in that folder if available. Keep drafts in a temporary directory, not in the repository. The proposed path is where a later human-approved PR would place the Markdown file. + +The `.md` frontmatter has `name`, `description`, and `date`. Do not write a `sources` key: `archdev rules propose` stamps the session answer source. In particular, `type: instruction_file` would falsely identify this rule as an instruction-file draft and can cause a retirement proposal when the rule is absent from `AGENTS.md`. The body states the obligation, why it matters, what violates it, what complies, scope and exclusions, good and bad examples with real paths or PR references when available, and an Enforcement note. Exclude secrets and unrelated transcript. + +The sibling `.jev` is JSON with `model`, `state.diff`, `state.context`, and exactly two Noul questions, `applicable` and `complies`. Follow an existing pair's model and state placeholders. `applicable` starts `Scope check only; do not judge compliance.` and names included and excluded paths. `complies` starts `Judge obligations only.` and states violations and compliant cases, including deletions and generalizations. Exclude test trees explicitly when the rule is for production code; otherwise tests can generate false violations. + +```json +{ + "model": "jev-latest", + "state": { + "diff": "REPLACE_BEFORE_USE: PR diff", + "context": "REPLACE_BEFORE_USE: repository and PR context" + }, + "questions": { + "applicable": { + "type": "noul", + "instructions": "Scope check only; do not judge compliance. Apply to ; exclude ." + }, + "complies": { + "type": "noul", + "instructions": "Judge obligations only. Flag ; accept ." + } + } +} +``` + +## Propose and inspect + +Only after the user explicitly asks to propose the rule, run: ```sh -archdev rules propose --repository owner/repo --md-file --jev-file --proposed-path --correction -archdev rules candidates --repository owner/repo +archdev rules propose --repository --md-file --jev-file --proposed-path --correction "" +archdev --json rules candidates --repository ``` -These commands require the Rust CLI release containing `rules` and deployed -candidate storage. If unavailable, retain the draft and report that limitation; -do not substitute the frozen TypeScript CLI or install anything without consent. -Use the current signed-in organization and the repository's installed identity. - -Proposals append immutable caller-owned answers. Recall shows the summary, -complete drafts, proposed path, status, and evidence; your unfolded proposals -are marked pending and are visible only to you until automation folds them. -Do not automatically retry an uncertain write. Recall first and report any -uncertainty. Store no secrets or unrelated transcript. - -Candidates do not activate policy. Do not edit, commit, or adopt repository -policy without the user's authorization. Human adoption is a PR adding the -Markdown/Jev pair. After approval, `rules adopt` can record that PR or commit -as adoption evidence; `rules dismiss` records a reason for dismissal. These -commands append human decisions for automation to fold; they do not add files -or change candidate status directly. No backtesting is required. +Keep `--correction` to the user's relevant steer, without secrets or unrelated conversation. The proposal creates a session candidate; it does not edit repository files or activate a check. Confirm an `open` candidate of kind `add`, source `session`, at the proposed path. The CLI prints its candidate, pending answer, and full theme key; the JSON list's `.data[].theme_key` carries that key. The plain list prints full bodies, and an empty list currently exits 1. If a write's outcome is uncertain, inspect candidates before retrying. + +## Open a rules PR + +Only when the user explicitly asks to open the rules PR, pass the exact full theme key from the proposal or JSON list to: + +```sh +archdev rules pr --repository [...] +``` + +The CLI opens one PR as the signed-in user on an `archdev/rules-*` branch, carrying only the selected pairs, with the ArchCode link first. Confirm the candidate becomes `pr_open`. The user reviews and merges the PR; adoption automation then marks the candidate `adopted`, and future PR verdicts can use the rule. Never add the pair to the repository or open a separate adoption PR by hand. + +For status inspection, `rules candidates --status` accepts one of `open`, `pr_open`, `adopted`, or `dismissed` per call; there is no `--status all`. If `rules pr` reports that opening the PR could not be confirmed, do not retry blindly. Report the error and inspect repository branches and candidate status first. diff --git a/plugins/pi/skills/archdev/SKILL.md b/plugins/pi/skills/archdev/SKILL.md index f91b796..c1d8ba8 100644 --- a/plugins/pi/skills/archdev/SKILL.md +++ b/plugins/pi/skills/archdev/SKILL.md @@ -109,12 +109,13 @@ subagents and agents you spawn. - PR reporting requires no local grading, annotations, or stop hold, including Factory and daemon sessions. Follow the host's publication ownership. -## Rule corrections during a session +## Rule candidates from a session -On a standing never/always correction or a repeated correction, follow -[rule candidate capture](references/rule-candidates.md): draft a Markdown/Jev -pair and capture only the supplied correction with the public CLI. Candidates -remain inert until the user authorizes policy adoption through a PR. +When a user asks to turn a correction into a repository rule, follow +[rule candidate capture](references/rule-candidates.md). Discuss a checkable +obligation before drafting. Propose the pair only when the user asks; open a +rules PR only on a separate explicit request. Candidates remain inert until +the user merges a rules PR. ## 1. Bootstrap diff --git a/plugins/pi/skills/archdev/references/rule-candidates.md b/plugins/pi/skills/archdev/references/rule-candidates.md index 4a420d8..f09861c 100644 --- a/plugins/pi/skills/archdev/references/rule-candidates.md +++ b/plugins/pi/skills/archdev/references/rule-candidates.md @@ -1,42 +1,54 @@ # Rule candidate capture -When the user gives a standing never/always correction or repeats a correction, -draft a reusable Markdown/Jev rule pair from that correction. Read -`.archdev/rules.yaml` and inspect existing `.md` + `.jev` pairs matched by its -`include` patterns. Use those pairs as format examples. The `adopt_to` directory -(default `.archdev/rules/`) is the destination for the proposed pair. - -When no existing pairs are available, use this default format: Markdown -frontmatter containing `name`, `description`, and `date`, with cited good/bad -examples; a sibling `.jev` using `jev-latest`, exactly the Noul questions -`applicable` and `complies`, and `state.diff` and `state.context` placeholders -starting `REPLACE_BEFORE_USE:`. Keep the supplied constraint and examples; -do not infer unrelated policy. - -Under `adopt_to`, choose -its appropriate language folder: `elixir`, `go`, `typescript`, `python`, `rust`, -or `technologies`, and a lowercase hyphenated Markdown filename. Offer to add -the pair at that path, then capture the supplied correction: +Use this flow when a user wants to brainstorm a repository rule from a correction. A useful rule states one obligation a reviewer can see violated in a PR diff. A mechanical check may instead inspect the PR title or description. Ask for the concrete failure and expected change when they are missing. Push back on session-process instructions and pure style preferences: a diff reviewer cannot reliably check them. Do not turn an inferred preference into policy. + +## Draft the pair + +Read `.archdev/rules.yaml` in the target repository. Its `adopt_to` directory defaults to `.archdev/rules/`; choose a language or topic folder under it and follow an existing `.md`/`.jev` pair in that folder if available. Keep drafts in a temporary directory, not in the repository. The proposed path is where a later human-approved PR would place the Markdown file. + +The `.md` frontmatter has `name`, `description`, and `date`. Do not write a `sources` key: `archdev rules propose` stamps the session answer source. In particular, `type: instruction_file` would falsely identify this rule as an instruction-file draft and can cause a retirement proposal when the rule is absent from `AGENTS.md`. The body states the obligation, why it matters, what violates it, what complies, scope and exclusions, good and bad examples with real paths or PR references when available, and an Enforcement note. Exclude secrets and unrelated transcript. + +The sibling `.jev` is JSON with `model`, `state.diff`, `state.context`, and exactly two Noul questions, `applicable` and `complies`. Follow an existing pair's model and state placeholders. `applicable` starts `Scope check only; do not judge compliance.` and names included and excluded paths. `complies` starts `Judge obligations only.` and states violations and compliant cases, including deletions and generalizations. Exclude test trees explicitly when the rule is for production code; otherwise tests can generate false violations. + +```json +{ + "model": "jev-latest", + "state": { + "diff": "REPLACE_BEFORE_USE: PR diff", + "context": "REPLACE_BEFORE_USE: repository and PR context" + }, + "questions": { + "applicable": { + "type": "noul", + "instructions": "Scope check only; do not judge compliance. Apply to ; exclude ." + }, + "complies": { + "type": "noul", + "instructions": "Judge obligations only. Flag ; accept ." + } + } +} +``` + +## Propose and inspect + +Only after the user explicitly asks to propose the rule, run: ```sh -archdev rules propose --repository owner/repo --md-file --jev-file --proposed-path --correction -archdev rules candidates --repository owner/repo +archdev rules propose --repository --md-file --jev-file --proposed-path --correction "" +archdev --json rules candidates --repository ``` -These commands require the Rust CLI release containing `rules` and deployed -candidate storage. If unavailable, retain the draft and report that limitation; -do not substitute the frozen TypeScript CLI or install anything without consent. -Use the current signed-in organization and the repository's installed identity. - -Proposals append immutable caller-owned answers. Recall shows the summary, -complete drafts, proposed path, status, and evidence; your unfolded proposals -are marked pending and are visible only to you until automation folds them. -Do not automatically retry an uncertain write. Recall first and report any -uncertainty. Store no secrets or unrelated transcript. - -Candidates do not activate policy. Do not edit, commit, or adopt repository -policy without the user's authorization. Human adoption is a PR adding the -Markdown/Jev pair. After approval, `rules adopt` can record that PR or commit -as adoption evidence; `rules dismiss` records a reason for dismissal. These -commands append human decisions for automation to fold; they do not add files -or change candidate status directly. No backtesting is required. +Keep `--correction` to the user's relevant steer, without secrets or unrelated conversation. The proposal creates a session candidate; it does not edit repository files or activate a check. Confirm an `open` candidate of kind `add`, source `session`, at the proposed path. The CLI prints its candidate, pending answer, and full theme key; the JSON list's `.data[].theme_key` carries that key. The plain list prints full bodies, and an empty list currently exits 1. If a write's outcome is uncertain, inspect candidates before retrying. + +## Open a rules PR + +Only when the user explicitly asks to open the rules PR, pass the exact full theme key from the proposal or JSON list to: + +```sh +archdev rules pr --repository [...] +``` + +The CLI opens one PR as the signed-in user on an `archdev/rules-*` branch, carrying only the selected pairs, with the ArchCode link first. Confirm the candidate becomes `pr_open`. The user reviews and merges the PR; adoption automation then marks the candidate `adopted`, and future PR verdicts can use the rule. Never add the pair to the repository or open a separate adoption PR by hand. + +For status inspection, `rules candidates --status` accepts one of `open`, `pr_open`, `adopted`, or `dismissed` per call; there is no `--status all`. If `rules pr` reports that opening the PR could not be confirmed, do not retry blindly. Report the error and inspect repository branches and candidate status first. From ce78d3f0abe2f3eed25355affc9d1edd7323a237 Mon Sep 17 00:00:00 2001 From: Rob Masson Date: Tue, 13 Oct 2026 14:19:42 -0700 Subject: [PATCH 4/4] Document rule checker visibility limits --- archdev/references/rule-candidates.md | 2 ++ .../antigravity/skills/archdev/references/rule-candidates.md | 2 ++ plugins/claude/skills/archdev/references/rule-candidates.md | 2 ++ plugins/codex/skills/archdev/references/rule-candidates.md | 2 ++ plugins/copilot/skills/archdev/references/rule-candidates.md | 2 ++ plugins/cursor/skills/archdev/references/rule-candidates.md | 2 ++ plugins/grok/skills/archdev/references/rule-candidates.md | 2 ++ plugins/opencode/skills/archdev/references/rule-candidates.md | 2 ++ plugins/pi/skills/archdev/references/rule-candidates.md | 2 ++ 9 files changed, 18 insertions(+) diff --git a/archdev/references/rule-candidates.md b/archdev/references/rule-candidates.md index f09861c..f899cee 100644 --- a/archdev/references/rule-candidates.md +++ b/archdev/references/rule-candidates.md @@ -2,6 +2,8 @@ Use this flow when a user wants to brainstorm a repository rule from a correction. A useful rule states one obligation a reviewer can see violated in a PR diff. A mechanical check may instead inspect the PR title or description. Ask for the concrete failure and expected change when they are missing. Push back on session-process instructions and pure style preferences: a diff reviewer cannot reliably check them. Do not turn an inferred preference into policy. +The checker judges each rule from the PR diff, its title and description, and the list of changed file paths. It does not read unchanged repository files such as CI workflows, build targets, or test runner configuration. Write the obligation so a violation is visible in those inputs. If compliance depends on files the PR usually leaves untouched, or only on what the description claims, narrow the rule to what the diff shows or push back on it. + ## Draft the pair Read `.archdev/rules.yaml` in the target repository. Its `adopt_to` directory defaults to `.archdev/rules/`; choose a language or topic folder under it and follow an existing `.md`/`.jev` pair in that folder if available. Keep drafts in a temporary directory, not in the repository. The proposed path is where a later human-approved PR would place the Markdown file. diff --git a/plugins/antigravity/skills/archdev/references/rule-candidates.md b/plugins/antigravity/skills/archdev/references/rule-candidates.md index f09861c..f899cee 100644 --- a/plugins/antigravity/skills/archdev/references/rule-candidates.md +++ b/plugins/antigravity/skills/archdev/references/rule-candidates.md @@ -2,6 +2,8 @@ Use this flow when a user wants to brainstorm a repository rule from a correction. A useful rule states one obligation a reviewer can see violated in a PR diff. A mechanical check may instead inspect the PR title or description. Ask for the concrete failure and expected change when they are missing. Push back on session-process instructions and pure style preferences: a diff reviewer cannot reliably check them. Do not turn an inferred preference into policy. +The checker judges each rule from the PR diff, its title and description, and the list of changed file paths. It does not read unchanged repository files such as CI workflows, build targets, or test runner configuration. Write the obligation so a violation is visible in those inputs. If compliance depends on files the PR usually leaves untouched, or only on what the description claims, narrow the rule to what the diff shows or push back on it. + ## Draft the pair Read `.archdev/rules.yaml` in the target repository. Its `adopt_to` directory defaults to `.archdev/rules/`; choose a language or topic folder under it and follow an existing `.md`/`.jev` pair in that folder if available. Keep drafts in a temporary directory, not in the repository. The proposed path is where a later human-approved PR would place the Markdown file. diff --git a/plugins/claude/skills/archdev/references/rule-candidates.md b/plugins/claude/skills/archdev/references/rule-candidates.md index f09861c..f899cee 100644 --- a/plugins/claude/skills/archdev/references/rule-candidates.md +++ b/plugins/claude/skills/archdev/references/rule-candidates.md @@ -2,6 +2,8 @@ Use this flow when a user wants to brainstorm a repository rule from a correction. A useful rule states one obligation a reviewer can see violated in a PR diff. A mechanical check may instead inspect the PR title or description. Ask for the concrete failure and expected change when they are missing. Push back on session-process instructions and pure style preferences: a diff reviewer cannot reliably check them. Do not turn an inferred preference into policy. +The checker judges each rule from the PR diff, its title and description, and the list of changed file paths. It does not read unchanged repository files such as CI workflows, build targets, or test runner configuration. Write the obligation so a violation is visible in those inputs. If compliance depends on files the PR usually leaves untouched, or only on what the description claims, narrow the rule to what the diff shows or push back on it. + ## Draft the pair Read `.archdev/rules.yaml` in the target repository. Its `adopt_to` directory defaults to `.archdev/rules/`; choose a language or topic folder under it and follow an existing `.md`/`.jev` pair in that folder if available. Keep drafts in a temporary directory, not in the repository. The proposed path is where a later human-approved PR would place the Markdown file. diff --git a/plugins/codex/skills/archdev/references/rule-candidates.md b/plugins/codex/skills/archdev/references/rule-candidates.md index f09861c..f899cee 100644 --- a/plugins/codex/skills/archdev/references/rule-candidates.md +++ b/plugins/codex/skills/archdev/references/rule-candidates.md @@ -2,6 +2,8 @@ Use this flow when a user wants to brainstorm a repository rule from a correction. A useful rule states one obligation a reviewer can see violated in a PR diff. A mechanical check may instead inspect the PR title or description. Ask for the concrete failure and expected change when they are missing. Push back on session-process instructions and pure style preferences: a diff reviewer cannot reliably check them. Do not turn an inferred preference into policy. +The checker judges each rule from the PR diff, its title and description, and the list of changed file paths. It does not read unchanged repository files such as CI workflows, build targets, or test runner configuration. Write the obligation so a violation is visible in those inputs. If compliance depends on files the PR usually leaves untouched, or only on what the description claims, narrow the rule to what the diff shows or push back on it. + ## Draft the pair Read `.archdev/rules.yaml` in the target repository. Its `adopt_to` directory defaults to `.archdev/rules/`; choose a language or topic folder under it and follow an existing `.md`/`.jev` pair in that folder if available. Keep drafts in a temporary directory, not in the repository. The proposed path is where a later human-approved PR would place the Markdown file. diff --git a/plugins/copilot/skills/archdev/references/rule-candidates.md b/plugins/copilot/skills/archdev/references/rule-candidates.md index f09861c..f899cee 100644 --- a/plugins/copilot/skills/archdev/references/rule-candidates.md +++ b/plugins/copilot/skills/archdev/references/rule-candidates.md @@ -2,6 +2,8 @@ Use this flow when a user wants to brainstorm a repository rule from a correction. A useful rule states one obligation a reviewer can see violated in a PR diff. A mechanical check may instead inspect the PR title or description. Ask for the concrete failure and expected change when they are missing. Push back on session-process instructions and pure style preferences: a diff reviewer cannot reliably check them. Do not turn an inferred preference into policy. +The checker judges each rule from the PR diff, its title and description, and the list of changed file paths. It does not read unchanged repository files such as CI workflows, build targets, or test runner configuration. Write the obligation so a violation is visible in those inputs. If compliance depends on files the PR usually leaves untouched, or only on what the description claims, narrow the rule to what the diff shows or push back on it. + ## Draft the pair Read `.archdev/rules.yaml` in the target repository. Its `adopt_to` directory defaults to `.archdev/rules/`; choose a language or topic folder under it and follow an existing `.md`/`.jev` pair in that folder if available. Keep drafts in a temporary directory, not in the repository. The proposed path is where a later human-approved PR would place the Markdown file. diff --git a/plugins/cursor/skills/archdev/references/rule-candidates.md b/plugins/cursor/skills/archdev/references/rule-candidates.md index f09861c..f899cee 100644 --- a/plugins/cursor/skills/archdev/references/rule-candidates.md +++ b/plugins/cursor/skills/archdev/references/rule-candidates.md @@ -2,6 +2,8 @@ Use this flow when a user wants to brainstorm a repository rule from a correction. A useful rule states one obligation a reviewer can see violated in a PR diff. A mechanical check may instead inspect the PR title or description. Ask for the concrete failure and expected change when they are missing. Push back on session-process instructions and pure style preferences: a diff reviewer cannot reliably check them. Do not turn an inferred preference into policy. +The checker judges each rule from the PR diff, its title and description, and the list of changed file paths. It does not read unchanged repository files such as CI workflows, build targets, or test runner configuration. Write the obligation so a violation is visible in those inputs. If compliance depends on files the PR usually leaves untouched, or only on what the description claims, narrow the rule to what the diff shows or push back on it. + ## Draft the pair Read `.archdev/rules.yaml` in the target repository. Its `adopt_to` directory defaults to `.archdev/rules/`; choose a language or topic folder under it and follow an existing `.md`/`.jev` pair in that folder if available. Keep drafts in a temporary directory, not in the repository. The proposed path is where a later human-approved PR would place the Markdown file. diff --git a/plugins/grok/skills/archdev/references/rule-candidates.md b/plugins/grok/skills/archdev/references/rule-candidates.md index f09861c..f899cee 100644 --- a/plugins/grok/skills/archdev/references/rule-candidates.md +++ b/plugins/grok/skills/archdev/references/rule-candidates.md @@ -2,6 +2,8 @@ Use this flow when a user wants to brainstorm a repository rule from a correction. A useful rule states one obligation a reviewer can see violated in a PR diff. A mechanical check may instead inspect the PR title or description. Ask for the concrete failure and expected change when they are missing. Push back on session-process instructions and pure style preferences: a diff reviewer cannot reliably check them. Do not turn an inferred preference into policy. +The checker judges each rule from the PR diff, its title and description, and the list of changed file paths. It does not read unchanged repository files such as CI workflows, build targets, or test runner configuration. Write the obligation so a violation is visible in those inputs. If compliance depends on files the PR usually leaves untouched, or only on what the description claims, narrow the rule to what the diff shows or push back on it. + ## Draft the pair Read `.archdev/rules.yaml` in the target repository. Its `adopt_to` directory defaults to `.archdev/rules/`; choose a language or topic folder under it and follow an existing `.md`/`.jev` pair in that folder if available. Keep drafts in a temporary directory, not in the repository. The proposed path is where a later human-approved PR would place the Markdown file. diff --git a/plugins/opencode/skills/archdev/references/rule-candidates.md b/plugins/opencode/skills/archdev/references/rule-candidates.md index f09861c..f899cee 100644 --- a/plugins/opencode/skills/archdev/references/rule-candidates.md +++ b/plugins/opencode/skills/archdev/references/rule-candidates.md @@ -2,6 +2,8 @@ Use this flow when a user wants to brainstorm a repository rule from a correction. A useful rule states one obligation a reviewer can see violated in a PR diff. A mechanical check may instead inspect the PR title or description. Ask for the concrete failure and expected change when they are missing. Push back on session-process instructions and pure style preferences: a diff reviewer cannot reliably check them. Do not turn an inferred preference into policy. +The checker judges each rule from the PR diff, its title and description, and the list of changed file paths. It does not read unchanged repository files such as CI workflows, build targets, or test runner configuration. Write the obligation so a violation is visible in those inputs. If compliance depends on files the PR usually leaves untouched, or only on what the description claims, narrow the rule to what the diff shows or push back on it. + ## Draft the pair Read `.archdev/rules.yaml` in the target repository. Its `adopt_to` directory defaults to `.archdev/rules/`; choose a language or topic folder under it and follow an existing `.md`/`.jev` pair in that folder if available. Keep drafts in a temporary directory, not in the repository. The proposed path is where a later human-approved PR would place the Markdown file. diff --git a/plugins/pi/skills/archdev/references/rule-candidates.md b/plugins/pi/skills/archdev/references/rule-candidates.md index f09861c..f899cee 100644 --- a/plugins/pi/skills/archdev/references/rule-candidates.md +++ b/plugins/pi/skills/archdev/references/rule-candidates.md @@ -2,6 +2,8 @@ Use this flow when a user wants to brainstorm a repository rule from a correction. A useful rule states one obligation a reviewer can see violated in a PR diff. A mechanical check may instead inspect the PR title or description. Ask for the concrete failure and expected change when they are missing. Push back on session-process instructions and pure style preferences: a diff reviewer cannot reliably check them. Do not turn an inferred preference into policy. +The checker judges each rule from the PR diff, its title and description, and the list of changed file paths. It does not read unchanged repository files such as CI workflows, build targets, or test runner configuration. Write the obligation so a violation is visible in those inputs. If compliance depends on files the PR usually leaves untouched, or only on what the description claims, narrow the rule to what the diff shows or push back on it. + ## Draft the pair Read `.archdev/rules.yaml` in the target repository. Its `adopt_to` directory defaults to `.archdev/rules/`; choose a language or topic folder under it and follow an existing `.md`/`.jev` pair in that folder if available. Keep drafts in a temporary directory, not in the repository. The proposed path is where a later human-approved PR would place the Markdown file.