feat(aidd-context): assess existing rules before writing (#1006)

* feat(aidd-context): assess existing rules before writing

Compare complete candidate policies and applicable project guidance before publication. Require an explicit resolution and preserve the approved body through the existing writer.

Refs #791

* fix(aidd-context): include applicable claude project guidance

Include local Claude policies and conditionally loaded AGENTS sources in the discovery contract. Record a Claude-only conflict assessment that leaves every project byte unchanged.

Refs #791

* docs(aidd-context): record rule assessment review and evidence

Record independent review and outcome challenge, mark the plan reviewed, and preserve reproducible native receipts and fixture teardown evidence.

Refs #791

* docs(aidd-context): remove rule contract timestamp

* docs(aidd-context): record concise skill verification

* refactor(aidd-context): keep rule generation minimal

Keep delivery evidence local; retain plugin-source writing separately from host publication.

* refactor(aidd-context): remove duplicate publication guidance

* refactor(aidd-context): simplify rule assessment actions

* refactor(aidd-context): fold rule assessment into capture

* fix(aidd-context): preserve rule capture contracts

Keep category and workflow semantics lost during compression. Make assessed
approval, explicit artifact language and host applicability unambiguous.

Refs #791

* refactor(aidd-context): clarify rule generation handoffs

Keep routing in the skill and detailed contracts in existing references.
Give each action an explicit input and output without repeating the frame
or assessment fields in its process.

Refs #791

* fix(aidd-context): restore host selection discovery

Preserve installed-tool discovery when destinations are unspecified.
Shared AGENTS guidance alone cannot identify an installed host.

Refs #791

* fix(aidd-context): clarify capture decision order

Await missing destination confirmation before assessing candidates.
Give unresolved applicability priority over conflict resolution so
unknown Copilot interfaces cannot justify changing imported policies.
Scope that uncertainty to existing-policy comparisons rather than
requiring activation proof for future publications.

Refs #791

* docs(aidd-context): name rule generation action files

Resolve installed action filenames without guessing numeric prefixes.

Refs #791

* docs(aidd-context): trim rule generation references

Keep agent decisions and usable publication contracts concise while leaving
mechanical diagnostics with the existing writer.

Refs #791

* docs(aidd-context): restore concrete rule generation actions

Keep the workflow in actions and reusable contracts in references so the
agent can follow the process without chasing procedural redirects.

Refs #791

* docs(aidd-context): clarify review before resolution

Put clarification and reassessment before policy-change choices when
comparison evidence is missing; keep label definitions in the reference.

Refs #791

* docs(aidd-context): shorten rule actions and split responsibilities

Keep the action flow readable while loading assessment, discovery and publication contracts only when needed. Preserve approval and host-format safeguards.

Refs #791

* docs(aidd-context): align rule generation with the lean skill style

Give each action a one-line purpose and bold-led imperative steps, keep the approval gate in the router, and phrase rules positively. References stay self-contained.

Refs #791

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* feat(aidd-context): plan and verify rule publication in the writer

Add --plan (dry run listing exact paths, same refusals) and --check --publish (drift report, non-zero on drift) to the standalone writer. Rule generation drops its validate action: capture plans before approval, write verifies after publishing.

Refs #791

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(aidd-context): a resolution is not an approval in rule generation

Present ends the turn, replans after any change and waits for a later explicit approval. The writer path is resolved absolute once, in capture.

Refs #791

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(aidd-context): define approval where rule generation writes

Write requires a user message that approves the displayed candidate unchanged; a choice, edit or rename is a resolution.

Refs #791

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(aidd-context): drop the redundant relative-path warning from write-rule

Refs #791

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* refactor(aidd-context): lean rule-generate wording and single approval rule

Drop redundant bold step labels and filler across the skill, state the
approval rule once in the transversal rules, show description, scope and
hosts in the presented candidate, and reuse the existing rule's hosts.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>

Author: blafourcade

aidd_docs/tasks/2026_10/2026_10_11_rule-contracts/official-contracts.md

@@ -22,4 +22,4 @@ Native instruction text guides model behavior; it does not guarantee compliance.
 
 [6] [Codex 0.162.1 implementation](https://github.com/openai/codex/blob/092d3acd6bec3e3a14bdc7e7a2810ab628ab759d/codex-rs/core/src/agents_md.rs#L63) and [0.160.1 implementation](https://github.com/openai/codex/blob/d27764b82f7118f674371e6d6e76271d9d606edb/codex-rs/core/src/agents_md.rs#L63): separate global assembly and project budget. [HTTP receipts and hashes](evidence/official/http-receipts.json).
 
-[7] [Skill host contract](../../../../plugins/aidd-context/skills/05-rule-generate/references/tool-paths.md) and [publication script](../../../../plugins/aidd-context/skills/05-rule-generate/scripts/write-rule.cjs): restricted serialization, body ownership and shared publication.
+[7] [Skill host contract](../../../../plugins/aidd-context/skills/05-rule-generate/references/rule-publication.md) and [publication script](../../../../plugins/aidd-context/skills/05-rule-generate/scripts/write-rule.cjs): restricted serialization, body ownership and shared publication.

docs/CATALOG.md

@@ -25,7 +25,7 @@ Bootstrap, project init, context-artifact generation, diagrams, learning, and ex
 | `02-project-memory`    | Give the AI a memory of the project, wired into the tools you use              | `01-scan`, `02-write`, `03-check`, `04-sync`                                                             |
 | `03-context-generate`  | Router that dispatches an artifact-generation request to the dedicated generator below | delegates to `04`–`08` (and plugins / marketplaces)                                            |
 | `04-skill-generate`    | Generate a router-based skill across the host AI tool(s)                       | `01-scope`, `02-plan`, `03-write`, `04-validate`                                                         |
-| `05-rule-generate`     | Generate a coding rule that governs editor and agent behavior                 | `01-capture-rule`, `02-write-rule`, `03-validate`                                                        |
+| `05-rule-generate`     | Generate a coding rule that governs editor and agent behavior                 | `01-capture-rule`, `02-write-rule`                                                                       |
 | `06-agent-generate`    | Generate an agent across the host AI tool(s)                                   | `01-capture-agent`, `02-write-agent`, `03-validate`                                                      |
 | `07-command-generate`  | Generate a flat slash command across the host AI tool(s)                       | `01-capture-command`, `02-write-command`, `03-validate`                                                  |
 | `08-hook-generate`     | Generate a lifecycle hook across the host AI tool(s)                           | `01-capture-hook`, `02-write-hook`, `03-validate`                                                        |

plugins/aidd-context/CATALOG.md

@@ -118,10 +118,11 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 |-------|------|---|
 | `actions` | [01-capture-rule.md](skills/05-rule-generate/actions/01-capture-rule.md) | - |
 | `actions` | [02-write-rule.md](skills/05-rule-generate/actions/02-write-rule.md) | - |
-| `actions` | [03-validate.md](skills/05-rule-generate/actions/03-validate.md) | - |
 | `assets` | [rule-template.md](skills/05-rule-generate/assets/rule-template.md) | - |
+| `references` | [rule-assessment.md](skills/05-rule-generate/references/rule-assessment.md) | - |
 | `references` | [rule-authoring.md](skills/05-rule-generate/references/rule-authoring.md) | - |
-| `references` | [tool-paths.md](skills/05-rule-generate/references/tool-paths.md) | - |
+| `references` | [rule-discovery.md](skills/05-rule-generate/references/rule-discovery.md) | - |
+| `references` | [rule-publication.md](skills/05-rule-generate/references/rule-publication.md) | - |
 | `-` | [SKILL.md](skills/05-rule-generate/SKILL.md) | `Create, update, publish or delete a coding rule across host AI tools. Use when adding, changing or removing a rule, convention or coding standard. Not for skills, agents or hooks.` |
 
 #### `skills/06-agent-generate`

plugins/aidd-context/skills/05-rule-generate/SKILL.md

@@ -6,24 +6,32 @@ argument-hint: topic | auto
 
 # Rule Generate
 
-Manage canonical rules and their active publications per confirmed host, or author a plugin source.
+```mermaid
+flowchart TD
+  request[Rule request] --> capture-rule
+  capture-rule -->|create/update| decision[Assessed candidate]
+  decision -->|revise/clarify| capture-rule
+  decision -->|keep/cancel| stop
+  decision -->|approved| write-rule
+  capture-rule -->|publish/delete confirmed| write-rule
+  write-rule -->|revised| capture-rule
+  write-rule -->|refused| stop
+  write-rule -->|verified| result
+```
 
 ## Actions
 
-| #   | Action         | Role                                      | Input        |
-| --- | -------------- | ----------------------------------------- | ------------ |
-| 01  | `capture-rule` | Capture the topic, pick category and slug | user request |
-| 02  | `write-rule`   | Write the rule file per supported tool    | the topic    |
-| 03  | `validate`     | Check each rule file                      | the files    |
+Follow the flow. Read only the next action and its references.
 
-Run the actions in order, `01 → 03`, and run each action's `## Test` before the next.
-Before running an action, read its file in `actions/`, not only the table or assets.
+| Action | Does |
+| --- | --- |
+| capture-rule | frame, compare, plan, decide |
+| write-rule | write the approved result, verify |
 
-## References
+## Transversal rules
 
-- `references/rule-authoring.md`: the contract (taxonomy, naming, frontmatter, content).
-- `references/tool-paths.md`: per-tool rules path, frontmatter, unsupported tools, the gate.
-
-## Assets
-
-- `assets/rule-template.md`: rule file scaffold.
+- Report unsupported hosts with alternatives; a lone AGENTS file identifies no installed host.
+- Stop and name any installed reference that cannot be read.
+- Change existing sources or publications only with explicit permission naming them.
+- Write only after the user approves the candidate shown last. A choice, merge, edit or rename is not an approval: show the revision and wait.
+- Keep or cancel leaves project bytes unchanged.

plugins/aidd-context/skills/05-rule-generate/actions/01-capture-rule.md

@@ -1,29 +1,26 @@
 # 01 - Capture rule
 
-Settle the rule's topic and place before writing.
+Frame the request, compare it with existing policies, plan the publication, decide with the user.
 
 ## Input
 
-A rule topic (e.g. "TypeScript naming"), or `auto` to scan the codebase and propose rules. Empty means manual.
+Request: a topic, `auto`, or a publish/delete. Default manual.
 
 ## Output
 
-In-context: the topic, its category and slug, the file scope, a one-line description, and the write mode (host with supported tools, or plugin source).
+Approved candidates with planned paths, or confirmed sources, operation and destinations.
 
 ## Process
 
-1. **Gate.** Run the asset-access precheck ([tool-paths.md](../references/tool-paths.md)).
-   For an explicitly confirmed host publish/delete, identify the existing rule or rule set and hosts, then continue to Render in action 02; no new topic or body is needed.
-2. **Auto or manual.** Ask whether to run auto or manual mode:
-   - **Auto**: scan the codebase, propose a rules architecture, wait for approval.
-   - **Manual**: ask the topic (blocking). Confirm any candidate first.
-3. **Place.** Pick the category and slug from [rule-authoring.md](../references/rule-authoring.md). The category index drives the slug prefix.
-4. **Scope.** State the glob the rule applies to, or note it applies to all files. Note a one-line description of what the rule governs, for tools whose scope frontmatter needs it.
-5. **Write mode.** Ask where the rule goes:
-   - **Host project**: detect the installed tools ([tool-paths.md](../references/tool-paths.md)), propose the supported ones, and confirm which to target. Never pick one silently.
-   - **Plugin source**: confirm or create `plugins/<plugin>/rules/`.
-
-## Test
-
-- The topic, category and slug, or existing publish/delete selection, are confirmed in writing.
-- Unsupported tools are named with what to do instead.
+1. Confirm the operation and [destination](../references/rule-publication.md).
+   - Hosts: reuse the existing rule's hosts, else ask. Missing hosts: detect, propose installation, await selection before drafting.
+2. Frame the topic.
+   - Manual: ask for it.
+   - Auto: scan, propose topics, await selection.
+   - Publish/delete: confirm sources and whole publications, then plan.
+3. Draft with the [template](../assets/rule-template.md) and [authoring](../references/rule-authoring.md), once topic and [fields](../references/rule-publication.md#operations) are confirmed.
+4. Compare: [discover policies](../references/rule-discovery.md) read-only in the project and loaded ancestors, never home or account scans, then [assess](../references/rule-assessment.md) each candidate.
+5. Plan: for a host, resolve the installed writer to an absolute path, write the request outside the destinations, run it with `--plan` per [publication](../references/rule-publication.md). A refusal returns to step 3.
+6. Present each candidate in full (body, description, scope, hosts), the planned paths and every finding (new rules too), then end the turn.
+   - Needs review: ask for evidence, reassess before offering source changes.
+   - Resolved: replan, present the revised candidate, end the turn again.

plugins/aidd-context/skills/05-rule-generate/actions/02-write-rule.md

@@ -1,26 +1,27 @@
 # 02 - Write rule
 
-Build one canonical rule and publish it for each confirmed supported host.
+Write the approved result and verify it.
 
 ## Input
 
-From 01: the topic, category, slug, scope, and write mode.
+Approval: a user message approving the last displayed candidate unchanged.
+
+Capture: the approved capture and its request.
 
 ## Output
 
-The canonical source, generated targets, and any unsupported tool with its reason.
+The written files, verified, or the refusal.
 
 ## Process
 
-1. **Build.** For create/update, use [rule-template.md](../assets/rule-template.md); strip the scaffold. For publish/delete, skip to Render.
-2. **Request.** For host create/update, put category, slug, description, optional paths and complete Markdown body into the JSON request in [tool-paths.md](../references/tool-paths.md). Keep YAML frontmatter out of the body.
-3. **Render.** Per the write mode ([tool-paths.md](../references/tool-paths.md)):
-   - **Host**: resolve `scripts/write-rule.cjs` beside the loaded installed `SKILL.md`. Invoke its absolute path with explicit project, tools and the operation's arguments in [tool-paths.md](../references/tool-paths.md). Use it for create/update, publish and delete; never replace or remove generated files manually. It preflights all outputs. Report refusals verbatim; skip unsupported tools with their reason.
-   - **Plugin source**: write one canonical `.md` rule. No per-tool fan-out.
-4. **Split.** When examples warrant it, write several rule files rather than one crowded one.
-5. **Validate.** Check the script's reported targets against [tool-paths.md](../references/tool-paths.md). It must not require the AIDD CLI.
+1. Match: for create/update, require that approval and compare body, fields, paths, resolution and evidence with the approved candidate. Without approval or on any difference, return to capture-rule, present the revision, end the turn, write nothing.
+2. Write the approved result.
+   - Host: run the writer by the absolute path resolved in capture-rule, with the approved request.
+   - Plugin: write or delete the approved source only.
+3. Verify: for a host, run the same absolute writer with `--check --publish`. Require no drift, deletions included.
+4. Report the written files. On refusal or drift, stop and quote it verbatim.
 
-## Test
+## Rules
 
-- Create/update/publish: canonical sources and active publications exist with the intended scope.
-- Delete: the selected source and its publications are absent; remaining rules and user bytes survive.
+- Leave generated files to the writer: canonical metadata and outputs are writer-owned, legacy rules unchanged.
+- Claim consumption only with matching and nonmatching file evidence from fresh host sessions.

plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md

@@ -1,8 +1,5 @@
-# <Rule title>
+<!-- Replace placeholders; delete this comment and unused lines. -->
 
-<One line: what this rule enforces.>
+# <Title>
 
-- <Concise rule preserving exact requirements.>
-- <Another.>
-
-<!-- Several themes? Group the bullets under `## headings` (skip groups for a short rule). One tiny example per group, only if it removes ambiguity. -->
+- <Requirement.>

plugins/aidd-context/skills/05-rule-generate/assets/rule-template.md

@@ -0,0 +1,22 @@
+# Rule assessment
+
+## Labels
+
+| Label | Means |
+| --- | --- |
+| needs review | uncertainty that could change the comparison; overrides every other label |
+| new | no coverage, overlap or conflict |
+| covered | existing policies supply every obligation throughout the scope |
+| overlap | compatible partial repetition or extension |
+| conflict | incompatible obligations, or an unjustified weakening |
+
+## Comparison
+
+- Compare obligations, prohibitions, scopes, conditions, exceptions and priority, prior sources on update and future files included.
+- Exclude only scopes proven disjoint.
+- Cite source paths, decisive quotes and scope reasons in every finding.
+
+## Choices
+
+- Offer create, keep, update, merge, scope, priority or cancel as applicable.
+- Needs review: request evidence, reassess before offering source changes. Keep and cancel stay available.

plugins/aidd-context/skills/05-rule-generate/references/rule-assessment.md

@@ -1,37 +1,30 @@
 # Rule authoring
 
-The contract every generated rule must satisfy. A rule governs editor and agent behavior for a set of files.
-
 ## Rules
 
-- **R1.** One rule file, one topic. Split a crowded rule into several files.
-- **R2.** Bullets only. Keep each concise; preserve requested literals, conditions and exceptions over word limits.
-- **R3.** Scope every rule to the files it applies to, or mark it as applying to all.
-- **R4.** English only, regardless of conversation language.
-- **R5.** Do not add a rule bullet that repeats, weakens, or contradicts another active bullet in the same rule.
-
-## File naming
-
-Format `#-slug[@version][-specificity]`. The `#` is the category index, single digit, no zero-pad. Examples: `2-typescript-naming`, `3-react@19-hooks`.
+- R1. One topic per file; split multiple topics.
+- R2. Concise bullets; keep literals, conditions and exceptions.
+- R3. Explicit scope or all files.
+- R4. English unless asked otherwise.
+- R5. Distinct bullets: none repeats, weakens or contradicts another.
 
-## Category taxonomy
+## Naming
 
-| #   | Category                   | Covers                                        |
-| --- | -------------------------- | --------------------------------------------- |
-| 00  | `architecture`             | system patterns (Clean, Hexagonal, API design) |
-| 01  | `standards`                | code style, naming (camelCase, imports)       |
-| 02  | `programming-languages`    | language-specific rules (TS strict mode)      |
-| 03  | `frameworks-and-libraries` | framework/lib patterns (React, Prisma)        |
-| 04  | `tooling`                  | tool/infra config (ESLint, Docker, CI)        |
-| 05  | `testing`                  | test patterns (fixtures, mocking)             |
-| 06  | `design-patterns`          | code design (Repository, Factory)             |
-| 07  | `quality`                  | perf and security (caching, auth)             |
-| 08  | `domain`                   | business logic (entities, DTOs)               |
-| 09  | `other`                    | miscellaneous                                 |
+`#-slug[@version][-specificity]`: single-digit category prefix, no zero-padding.
 
-Pick the most specific match: framework `03`, language syntax `02`, agnostic style `01`, architecture `00`, then `04`-`08` in order, else `09`.
+| Index | Category | Covers |
+| --- | --- | --- |
+| 00 | architecture | system design |
+| 01 | standards | style/naming |
+| 02 | programming-languages | language rules |
+| 03 | frameworks-and-libraries | framework/library patterns |
+| 04 | tooling | tools/configuration |
+| 05 | testing | test patterns |
+| 06 | design-patterns | code design patterns |
+| 07 | quality | performance/security |
+| 08 | domain | business logic |
+| 09 | other | miscellaneous |
 
-## Content
+Pick in order: `03`, `02`, `01`, `00`, `04`–`08`, else `09`.
 
-- Group related bullets under a `## group` heading when the rule has several themes. Skip groups for a short rule.
-- Add one tiny example per group only when it removes ambiguity. Good code only.
+- Themes: `## group`, at most one tiny good-code example each.