@hassangameryt/freeflow 0.7.3 → 0.8.0

package/skills/write-plan/SKILL.md

@@ -7,86 +7,86 @@ description: "Use when writing or revising an implementation plan, execution pla
 
 Write a supported ordered strategy for an agreed outcome. Make its dependencies, actions, checks, and invalidation conditions clear without inventing requirements or pretending unknown later work is settled.
 
-A Plan describes intended execution. The Working Record preserves actual work, evolving state, and the next useful action. Neither creates authority by existing.
+A Plan describes intended execution. The Working Record preserves actual work, evolving state, and the next useful action.
 
-## Plan Only What Is Understood Enough To Order
+The **Rules** below are binding; if one cannot be met, stop and say why. Everything else is **judgment**: follow its stated goal, and adapt when a different choice serves that goal better.
 
-Use a durable Plan when the intended outcome and material decisions are settled, the approach and dependencies can be ordered without guessing, and the strategy needs to survive independently.
+## Rules
 
-Not every task needs one. A small correction can proceed from its request and supported approach. An evolving route with substantial branching belongs in [Track Work](../track-work/SKILL.md) as provisional Slices, not a confident long-form Plan.
+- A Plan creates no authority. Accepting it as a strategy is not permission to execute it. Explicit approval to execute it may cover its listed work, checks, selected reviews, record maintenance, and local commits (still subject to fresh evidence and [Commit Work](../commit-work/SKILL.md) inspection); it never implies push, integration, migration, deprecation, release, or launch.
+- Never invent product behavior, compatibility, public interfaces, failure semantics, sensitive policy, migration, scale, retries, recovery, or extension machinery, and never replace agreed scope with an unapproved MVP or later-version split.
+- Never encode a hoped-for answer or an unsettled owner choice as a planning assumption. Use [Discuss](../discuss/SKILL.md) for unresolved direction or material alternatives, [Decision Gate](../decision-gate/SKILL.md) for a blocking owner choice or source conflict, and [Diagnose Failure](../diagnose-failure/SKILL.md) for a fix whose cause is unsupported.
+- Never let available tests redefine acceptance, or claim whole-system completion from a narrow observer.
+- Writing or revising a Plan does not trigger independent review, and neither self-review nor independent review grants user acceptance or execution authority.
 
-Use [Discuss](../discuss/SKILL.md) for unresolved direction or material alternatives, [Decision Gate](../decision-gate/SKILL.md) for a blocking owner choice or source conflict, and [Diagnose Failure](../diagnose-failure/SKILL.md) for a fix whose cause is unsupported. Do not encode the hoped-for answer as a planning assumption.
+## Plan Only What Is Understood Enough To Order
 
-If the user asks about a Plan, answer rather than write one. If execution of the task is already authorized and a Plan is useful preparation, writing it need not create another approval stop. Preserve any review or user-return boundary actually selected.
+Goal: write a durable Plan only when the strategy can be ordered honestly and needs to survive on its own.
 
-## Establish The Current Basis
+Use a durable Plan when the intended outcome and material decisions are settled, the approach and dependencies can be ordered without guessing, and the strategy needs to survive independently. Not every task needs one: a small correction can proceed from its request and supported approach, and an evolving route with substantial branching belongs in [Track Work](../track-work/SKILL.md) as provisional Slices, not a confident long-form Plan.
 
-A separate Spec is not required when the request and accepted understanding are sufficiently clear. Otherwise consume the relevant Spec, issue, design, diagnosis, decision, or requirements, together with current code, tests, policies, ADRs, and external constraints where needed.
+If the user asks about a Plan, answer rather than write one. If execution is already authorized and a Plan is useful preparation, writing it need not create another approval stop; preserve any review or user-return boundary actually selected.
+
+## Establish The Current Basis
 
-Identify which accepted source version or amendment the Plan implements. A Working Record can locate those sources but cannot override them. Do not use an older experimental or design baseline merely because a prior Plan was reviewed.
+Goal: the Plan implements current accepted sources, not an older baseline.
 
-Separate:
+A separate Spec is not required when the request and accepted understanding are clear enough. Otherwise consume the relevant Spec, issue, design, diagnosis, decision, or requirements, together with current code, tests, policies, ADRs, and external constraints where needed.
 
-- the required outcome and non-goals;
-- accepted design choices and constraints;
-- the supported implementation approach;
-- assumptions whose failure would invalidate dependent work;
-- unresolved or intentionally deferred work outside this Plan's promise.
+Identify which accepted source version or amendment the Plan implements. A Working Record can locate those sources but cannot override them, and a previously reviewed baseline does not excuse ignoring a later accepted change.
 
-An experiment produces evidence, not an automatic requirement. Include its consequences only where selected for this outcome; do not omit consequences the user subsequently accepted.
+Separate the required outcome and non-goals, accepted design choices and constraints, the supported implementation approach, assumptions whose failure would invalidate dependent work, and unresolved or deferred work outside the Plan's promise. An experiment produces evidence, not an automatic requirement: include its consequences only where selected for this outcome, and do not omit consequences the user later accepted.
 
 ## Write The Smallest Useful Strategy
 
+Goal: enough to inspect and execute the strategy, and no more.
+
 Read [Plan Shapes](references/plan-shapes.md) before choosing the artifact shape.
 
-Include relevant goal, sources, scope, decisions, assumptions, dependencies, ordered coherent outcomes, focused checks, integration, completion conditions, and what would invalidate the strategy. Use exact paths and commands when known and useful; do not invent them to make the Plan look executable.
+Include the relevant goal, sources, scope, decisions, assumptions, dependencies, ordered coherent outcomes, focused checks, integration, completion conditions, and what would invalidate the strategy. Use exact paths and commands when known and useful; do not invent them to make the Plan look executable.
 
-Size outcomes for manageable working context, dependencies, uncertainty, and checking. Do not divide mechanically by file, bug count, test, or method. The complete task may require several Slices, but each should have a coherent result and a clear dependency on earlier work where one exists.
+Size outcomes for manageable working context, dependencies, uncertainty, and checking, not mechanically by file, bug count, test, or method. Each Slice should have a coherent result and a clear dependency on earlier work where one exists.
 
-A validation step may stop the Plan if a bounded assumption fails. If its result is expected to select among materially different strategies, keep dependent work provisional in the Working Record rather than presenting the later sequence as decided.
+A validation step may stop the Plan if a bounded assumption fails. If its result would select among materially different strategies, keep dependent work provisional in the Working Record rather than presenting the later sequence as decided.
 
-The Plan is not a context inventory. Specify only the sources and relationships needed to explain or execute its steps, leaving ordinary local choices to the executing agent.
+The Plan is not a context inventory: specify only the sources and relationships needed to explain or execute its steps, and leave ordinary local choices to the executing agent.
 
 ## Preserve Acceptance And Return Conditions
 
-Tie each material outcome and final check to the accepted behavior it serves. Do not let available tests redefine acceptance or claim whole-system completion from a narrow observer.
-
-Keep the agreed user-facing return condition visible: return a proposed strategy, implement one Slice, finish the described task, or stop at a specified boundary. Internal delegation handbacks and context cycles are not automatic user checkpoints.
-
-A Plan must not invent product behavior, compatibility, public interfaces, failure semantics, sensitive policy, migration, scale, retries, recovery, or extension machinery. Do not replace agreed scope with an unapproved MVP or later-version split.
+Goal: every planned outcome traces to accepted behavior, and the user-facing return point stays visible.
 
-Before a new prerequisite becomes a planned obligation, determine whether it serves an accepted requirement or only preserves a particular approach. Resolve consequential alternatives instead of hiding them in confident steps.
+Tie each material outcome and final check to the accepted behavior it serves. Keep the agreed return condition visible: return a proposed strategy, implement one Slice, finish the task, or stop at a specified boundary. Internal delegation handbacks and context cycles are not user checkpoints.
 
-## Select Checkpoints Without Making A Schedule Of Ceremonies
+Before a new prerequisite becomes a planned obligation, determine whether it serves an accepted requirement or only preserves a particular approach, and resolve consequential alternatives instead of hiding them in confident steps.
 
-Ordinary verification and silent self-review belong to producing each supported result. Do not restate them as independent gates unless a particular evidence boundary needs explanation.
+## Select Checkpoints Without A Schedule Of Ceremonies
 
-Include independent review, a local commit, a user decision, or continuity transfer only when selected to protect a concrete dependency, risk, rollback, or delivery boundary. A Slice ending or a fixed count is insufficient.
+Goal: checkpoints protect real boundaries, not a routine.
 
-Accepting a Plan as a strategy is not permission to execute it. Explicit approval to execute the Plan may cover its listed work, checks, selected reviews, record maintenance, and local commits. It does not imply push, integration, migration, deprecation, release, or launch. Planned commits remain conditional on fresh evidence and [Commit Work](../commit-work/SKILL.md) inspection.
+Ordinary verification and silent self-review belong to producing each result; do not restate them as gates unless a particular evidence boundary needs explanation. Include independent review, a local commit, a user decision, or a continuity transfer only when selected to protect a concrete dependency, risk, rollback, or delivery boundary; a Slice ending or a fixed count is not enough.
 
 When an existing agreement already covers the work, preserve that source instead of asking the user to approve the same scope again because it is now written down.
 
 ## Revise Only The Affected Strategy
 
-Do not update a Plan for completed steps, ordinary local choices, test counts, or routine status. Record material actual state through Track Work when present.
+Goal: the Plan changes when its strategy changes, not when work progresses.
 
-Revise or supersede the affected strategy when accepted intent or supported evidence changes its scope, design, ordering, dependencies, checks, or mechanism. Preserve valid earlier work and rationale. A clerical correction does not reopen the strategy, and reaching a review cap is not evidence that the Plan needs rewriting.
+Do not update a Plan for completed steps, ordinary local choices, test counts, or routine status; record actual state through Track Work. Revise or supersede the affected strategy when accepted intent or supported evidence changes its scope, design, ordering, dependencies, checks, or mechanism, preserving valid earlier work and rationale. A clerical correction does not reopen the strategy, and reaching a review cap is not evidence the Plan needs rewriting.
 
-Identify affected upstream and downstream artifacts. Revise only content whose owned meaning changed and whose mutation is authorized. If an upstream contract remains unresolved, mark dependent steps contingent before they are used. Do not repair consistency by silently changing the required outcome.
+Identify affected upstream and downstream artifacts and revise only content whose owned meaning changed and whose mutation is authorized. If an upstream contract remains unresolved, mark dependent steps contingent before they are used. Do not repair consistency by silently changing the required outcome.
 
 ## Self-Review Before Treating The Plan As Usable
 
-After factual source checks, use [Review Artifact](../review-artifact/SKILL.md) for one silent author self-review of the complete Plan, accepted sources, and intended execution boundary.
+Goal: the Plan can achieve the accepted outcome before anyone relies on it.
 
-Check whether the ordered work can achieve the accepted outcome, dependencies are supported, later uncertainty is honest, final checks match acceptance, and selected checkpoints are proportionate. Correct clear covered defects and recheck affected facts and lenses.
+After factual source checks, use [Review Artifact](../review-artifact/SKILL.md) for one silent author self-review of the complete Plan, its accepted sources, and the intended execution boundary. Check that the ordered work can achieve the accepted outcome, dependencies are supported, later uncertainty is honest, final checks match acceptance, and selected checkpoints are proportionate. Correct clear covered defects and recheck affected facts and lenses.
 
-Do not automatically dispatch an independent reviewer after writing or revising a Plan. Use Review Artifact's independent route only when separately selected and authorized to protect a concrete boundary. Supply complete sources, dependencies, and limits; adjudicate the returned report before acting on its findings.
-
-Neither self-review nor independent review grants user acceptance or execution authority. Conversely, an already-covered execution agreement does not need another approval turn solely because planning produced an artifact.
+Use Review Artifact's independent route only when separately selected and authorized to protect a concrete boundary; supply complete sources, dependencies, and limits, and adjudicate the returned report before acting on it.
 
 ## Report And Return
 
-Report the Plan path and intended use, source basis, material assumptions or contingent work, invalidation conditions, selected checkpoints, and actual review/acceptance/execution-authority status.
+Report the Plan path and intended use, source basis, material assumptions or contingent work, invalidation conditions, selected checkpoints, and actual review, acceptance, and execution-authority status.
+
+When a Working Record exists and the Plan is accepted for its task, list it under the record's `What defines this task` through Track Work so every recovery reads it.
 
-Return the supported strategy to the requesting activity. If the agreement covers implementation, the agent can continue through the normal execution route; if it asks for a Plan first, stop there. Do not begin work outside that agreement or claim an unresolved strategy is ready.
+Return the supported strategy to the requesting activity. If the agreement covers implementation, continue through the normal execution route; if it asks for a Plan first, stop there. Do not begin work outside that agreement or claim an unresolved strategy is ready.

package/skills/write-plan/references/plan-shapes.md

@@ -1,6 +1,6 @@
 # Plan Shapes
 
-Read this when choosing the structure, destination, identity, or revision shape of an ordered Plan. Use only the sections the Plan needs.
+Read this when choosing the structure, destination, identity, or revision shape of an ordered Plan. This reference is judgment: use only the sections the Plan needs.
 
 ## Destination And Durable Identity
 

package/skills/write-skill/SKILL.md

@@ -9,10 +9,25 @@ Write the smallest agent-first skill package that changes one coherent behaviora
 
 A skill is a prompt intervention, not merely a document. A host may read its body once and retain it across later messages and tool interactions until context projection or loss. Design the first useful read, retained influence, dependencies, and recovery paths; do not assume the body will be reread before every use.
 
-Smallest means behaviorally minimal—not shortest. A detailed skill is justified when each instruction changes action or judgment, makes a dependency executable, protects a behavioral boundary whose failure is supported by evidence, or establishes an evidence, return, or stop condition.
+Smallest means behaviorally minimal, not shortest. A detailed skill is justified when each instruction changes action or judgment, makes a dependency executable, protects a behavioral boundary whose failure is supported by evidence, or establishes an evidence, return, or stop condition.
+
+The **Rules** below are binding; if one cannot be met, stop and say why. Everything else is **judgment**: follow its stated goal, and adapt when a different choice serves that goal better.
+
+## Rules
+
+- Before substantially revising an existing skill, preserve the complete current package (`SKILL.md`, references, scripts, assets) in a recoverable Git ref or in task evidence outside the package. A small correction needs no new snapshot when the exact previous state is already recoverable and behavior, activation, dependencies, and resources are unchanged. A baseline supports recovery and comparison; it does not show that either version behaves correctly.
+- If accepted behavior, public dependencies, safety, compatibility, or another user-owned boundary is unsettled, stop and resolve it before encoding it.
+- Never rely on an unread skill or reference to cause its own read. The first read must come from context the agent already has: a description, guaranteed base guidance, an already-loaded skill, a capability cue, or another declared route.
+- Rely only on context guaranteed on every valid activation path, never on an optional sibling, a common but unguaranteed route, or an accidental earlier read.
+- Link every agent-facing reference, asset, script, and package dependency from the body, with the condition that requires it. The body and the resource state the same read condition.
+- Keep authoring status, evaluation summaries, evidence gaps, changelog notes, readiness claims, and author debate out of the executing package; they belong in the evaluation artifact, task record, or delivery report.
+- Claim only what the evidence observed. Structural checks prove structure. Explicit body delivery does not prove activation, one turn does not prove retained use, ambient context does not prove dependency behavior, prose review does not prove unchanged behavior, and one favorable example does not prove readiness.
+- Run `validate` after any structural or dependency change and before claiming the package is valid. Never use deprecated authoring tooling.
 
 ## Establish The Behavioral Claim
 
+Goal: know what the skill must change before deciding how it reads.
+
 Before writing, identify:
 
 - the behavior the skill should produce;
@@ -24,62 +39,26 @@ Before writing, identify:
 - how the skill should stop influencing behavior after its method no longer applies;
 - the evidence that could support or contradict the intended effect.
 
-Do not begin with sections, wording, examples, or file layout. Begin with the behavioral intervention.
-
-If accepted behavior, public dependencies, safety, compatibility, or another user-owned boundary remains unsettled, stop and resolve it before encoding a runtime rule.
-
-## Preserve The Exact Baseline
-
-Before substantially revising an existing skill, preserve the complete current package:
-
-- `SKILL.md`;
-- references;
-- scripts;
-- assets and other owned resources;
-- exact package identity.
-
-Use a recoverable Git ref or task evidence outside the active package so the revision cannot replace its own baseline.
-
-A small local correction does not require another snapshot when the exact previous state is already recoverable and the change does not alter behavior, activation, dependencies, resource structure, or compatibility.
-
-Preserving a baseline supports recovery and comparison. It does not prove that the baseline or candidate behaves correctly.
+Begin with the behavioral intervention, not with sections, wording, examples, or file layout.
 
 ## Design The First Read
 
-A skill cannot activate itself. Its first read must be caused by context already available to the agent:
+Goal: the skill is read at the earliest decision it can improve, and reading it on a nearby case does no harm.
 
-- an observable skill description;
-- guaranteed base or system guidance;
-- an already-loaded owner or sibling;
-- an effective capability cue;
-- another declared upstream route.
-
-Do not rely on an instruction inside the unread skill to cause that skill to be read.
-
-Optimize activation for the earliest useful decision. Missing that decision may be much more harmful than a harmless early read.
-
-A nearby case can pass by:
-
-- not loading the skill; or
-- loading it safely, recognizing that its method does not apply, and exiting without later hijacking retained behavior.
-
-False-positive activation is cheap only when the body remains safe after retention. A skill that exits on the first turn but continues distorting later work is not a safe read.
+Missing that decision is usually far more harmful than an unnecessary early read. A nearby case can pass by not loading the skill, or by loading it, recognizing that its method does not apply, and exiting without distorting later work. An early read is cheap only when the retained body stays safe; a skill that exits on the first turn but keeps distorting later work is not a safe read.
 
 Read [Activation Boundaries](references/activation-boundaries.md) when activation is unclear or evidence shows missed, late, early, task-hijacking, or retained-interference behavior.
 
 ## Write The Description For Recall
 
-Treat the description as a routing interface, not a summary of the body.
+The description is a routing interface, not a summary of the body.
 
-- State the broad core job in plain language.
-- Use natural user verbs or task conditions visible before activation.
-- Prefer recall when nearby reads are safe and missed activation is materially worse.
-- Do not require terminology or classifications introduced only inside the skill or an optional dependency.
-- Do not encode future-duration guesses, named internal phases, exhaustive trigger catalogs, or marketing claims.
-- Do not compress the body into the description.
-- Treat “Use when…” as useful wording, not mandatory grammar.
+- State the broad core job in plain language, with natural user verbs or task conditions visible before activation.
+- Avoid terminology or classifications introduced only inside the skill or an optional dependency.
+- Avoid future-duration guesses, named internal phases, exhaustive trigger catalogs, marketing claims, and compressed copies of the body.
+- "Use when…" is useful wording, not mandatory grammar.
 
-Optimize for the first useful read, not repeated reads. Do not narrow a description solely to prevent harmless activation. Do not broaden it when retained guidance routinely overrides another owner or method.
+Favor recall when nearby reads are safe and a missed read is materially worse. Narrow the description when retained guidance routinely overrides another owner or method, not merely to prevent harmless reads.
 
 ## Write For The Executing Agent
 
@@ -87,16 +66,34 @@ Write for an agent seeing the skill for the first time with only guaranteed cont
 
 1. Establish the job immediately.
 2. Define necessary terms before using them.
-3. Put each rule where the agent first makes the affected choice.
+3. Put each instruction where the agent first makes the affected choice.
 4. Keep the normal route understandable from `SKILL.md`.
 5. State what to do, what not to do, and when to stop, return, or route.
-6. Prefer a positive route; use negative instructions to block plausible or observed failure.
-7. Pair a negative rule with the correct action or owner whenever possible.
-8. State why only when it helps the agent generalize or avoid a harmful literal reading.
-9. Keep the skill focused on one coherent job. Do not copy the surrounding workflow’s authority, routing, continuity, review, or completion method into a focused skill; repeat only the local guard needed at the affected choice.
-10. Keep authoring status, evaluation summaries, evidence gaps, changelog notes, and readiness prose out of the executing package.
+6. Prefer a positive route; use negative instructions to block plausible or observed failure, paired with the correct action or owner.
+7. State why only when it helps the agent generalize or avoid a harmful literal reading.
+8. Keep the skill to one coherent job. Repeat only the local guard needed from the surrounding workflow's authority, routing, continuity, review, or completion method, not the method itself.
+9. Use plain words. Every coined term is something the agent must decode before it can act, so coin one only when it marks a distinction the agent has to act on, define it once, and use it the same way throughout.
+
+Use discussion, research, and author reasoning to understand the behavior, then compile that understanding into runtime instructions. The conversation, rejected drafts, fixture narration, and any explanation whose only reader is the author stay out.
+
+Read [Agent-First Instructions](references/agent-first-instructions.md) when a concrete first-read or retained-use failure involves wording, placement, undeclared context, author explanation, or competing instructions.
+
+## Separate Rules From Judgment
+
+A skill gives two kinds of instruction, and agents need to tell them apart.
+
+- **Rules** are binding. Breaking one is wrong in every situation: authority, safety, evidence honesty, data integrity, or an invariant that a tool or another skill depends on.
+- **Judgment** guides the choice among allowed actions: placement, granularity, timing, effort, what to record, how much to delegate. A better choice sometimes means departing from the default.
 
-A useful rule normally identifies:
+Classify each instruction with one question:
+
+> If an agent pursued the goal well but broke this sentence, would the outcome be wrong in every case?
+
+If yes, it is a Rule. If the agent would sometimes do better, it is judgment.
+
+Agents follow imperative lists literally. A judgment written as an imperative becomes a Rule by accident: "Delegate routine record maintenance to Helper" makes an agent hand off a two-line update and then do the rest itself.
+
+Write a Rule as a short imperative that names its trigger and its stop:
 
 ```text
 observable pressure
@@ -104,133 +101,103 @@ observable pressure
 -> evidence, return, or stop condition
 ```
 
-Use discussion, research, and author reasoning to understand the behavior. Compile that understanding into runtime instructions. Do not copy conversation history, rejected drafts, author debate, fixture narration, or explanation whose only reader is the author.
+Keep Rules few, testable, and together near the top, and say what to do when one cannot be met.
 
-A skill may rely on guaranteed base context and dependencies explicitly required before use. It may not rely on an unread optional sibling or reference, a common-but-unguaranteed route, or an accidental earlier read.
+Write judgment as a trade-off the agent can reason from:
 
-Read [Agent-First Instructions](references/agent-first-instructions.md) when a concrete first-read or retained-use failure involves wording, placement, undeclared context, author explanation, or competing instructions.
+```text
+goal
+-> default and why it usually serves the goal
+-> signals that a different choice serves it better
+```
 
-## Use Examples Deliberately
+Examples inside judgment are illustrations, not triggers:
 
-Add a compact example when prose alone leaves a likely behavioral misclassification.
+> Delegate a unit when a cheaper profile can do it without significant quality loss and the handoff costs less than it saves. A separate record update across several entries often qualifies; a one-line update in the middle of your own work does not.
 
-Show:
+When a skill contains both kinds, say so once near the top: which instructions are binding, and that everything else is judgment the agent may adapt to its goal. A skill may be mostly Rules, like a release protocol, or mostly judgment, like work placement; the label keeps each one from being read as the other.
 
-- the observable situation;
-- the required action or judgment;
-- the relevant stop, exit, or return.
+References follow the same split. A reference that defines a contract, such as a file format, schema, command interface, or protocol, is binding as written. A reference that deepens a method is judgment. A reference that is mostly one kind says so in its opening line, and states any Rule it adds; one that only restates a skill Rule as a local guard needs no label.
 
-Keep examples transferable. Do not turn the body into a transcript, fixture library, or scenario catalog.
+## Use Examples Deliberately
 
-Inline examples teach the subject and are part of the candidate intervention. They are not independent evidence that the skill works.
+Add a compact example when prose alone leaves a likely misclassification. Show the observable situation, the required action or judgment, and the relevant stop, exit, or return.
 
-## Plan Terminology And Dependencies
+Keep examples transferable; the body is not a transcript, fixture library, or scenario catalog. Inline examples teach the subject and are part of the candidate intervention, not independent evidence that the skill works.
 
-For one self-contained skill, declare only the dependencies its normal and conditional routes need.
+## Plan Terminology And Dependencies
 
-Before creating or revising multiple related skills, shared terminology, cross-skill links, capability activation, direct or routed entry paths, or context-loss recovery, read [Skill Dependency Graphs](references/skill-dependency-graphs.md).
+Goal: every term and dependency is available on every path that reaches the skill.
 
-For every skill:
+For one self-contained skill, declare only the dependencies its normal and conditional routes need. Before creating or revising several related skills, shared terminology, cross-skill links, capability activation, direct or routed entry paths, or context-loss recovery, read [Skill Dependency Graphs](references/skill-dependency-graphs.md).
 
-- identify every valid direct and routed activation path;
-- rely only on context guaranteed across all valid paths;
-- place shared vocabulary in the nearest upstream context guaranteed before every consumer;
-- keep leaf-specific terms local;
-- distinguish owner routes, method composition, environment interactions, references, capability cues, and retained context;
-- ensure critical skills have an upstream activation or recovery edge;
-- do not assume a commonly preceding skill is guaranteed.
+- Identify every valid direct and routed activation path.
+- Place shared vocabulary in the nearest upstream context guaranteed before every consumer; keep leaf-specific terms local.
+- Distinguish owner routes, method composition, environment interactions, references, capability cues, and retained context.
+- Give critical skills an upstream activation or recovery edge.
 
-A Markdown link declares a package dependency. It does not automatically select the target owner or execute the linked skill.
+A Markdown link declares a package dependency. It does not select the target owner or execute the linked skill.
 
 ## Compact Without Erasing Behavior
 
-Compact after the behavioral policy, dependencies, and failure boundaries are understood.
+Goal: remove what does not change behavior, and nothing that does.
 
-For each instruction, ask:
+Compact after the behavioral policy, dependencies, and failure boundaries are understood. For each instruction, ask:
 
 > Can this be removed without losing required behavior, introducing ambiguity, obscuring a dependency, or reintroducing a previously observed failure?
 
-If yes, remove or merge it. If uncertain, preserve it until evidence distinguishes the variants.
+If yes, remove or merge it.
 
-Do not compact by:
+Keep an instruction because it protects measured behavior or prevents a specific failure you can name, not because it might help. An instruction with neither is a candidate for removal: remove it, or test whether it changes behavior, rather than keeping it by default. Skills otherwise only grow, as each incident adds instructions and none is ever shown safe to remove.
 
-- deleting the positive route while retaining only prohibitions;
-- moving normal required behavior into an always-read reference;
-- merging rules whose triggers or stop conditions differ;
-- replacing a concrete instruction with generic quality language;
-- removing terminology required by a direct activation path;
-- deleting repetition that protects a distinct decision or recovery boundary.
+Compaction goes wrong when it:
 
-Length is a diagnostic fact, not a quality verdict. A long skill may be minimal. A short skill may force the agent to reconstruct missing judgment through reasoning or environment interactions.
+- deletes the positive route while keeping only prohibitions;
+- reduces a judgment to a bare imperative by dropping its goal or its signals for deviating;
+- moves normal required behavior into an always-read reference;
+- merges instructions whose triggers or stop conditions differ;
+- replaces a concrete instruction with generic quality language;
+- removes terminology a direct activation path needs;
+- deletes repetition that protects a distinct decision or recovery boundary.
 
-## Repeat Rules Deliberately
+Length is a diagnostic fact, not a quality verdict. A long skill may be minimal; a short one may force the agent to reconstruct missing judgment.
 
-Repetition is justified when local presence protects:
+## Repeat Instructions Deliberately
 
-- an independently activated skill;
-- a distinct decision point;
-- a context-loss or host path;
-- a dangerous literal interpretation;
-- a previously observed failure;
-- a required body-to-reference read condition.
+Goal: each behavior has one owner, with a local guard wherever an agent could otherwise act without it.
 
-Use one canonical owner for the full definition or method. Repeat only the compact local guard needed at the affected choice.
+Repetition earns its place when local presence protects an independently activated skill, a distinct decision point, a context-loss or host path, a dangerous literal reading, a previously observed failure, or a required read condition. Keep the full definition or method with one canonical owner and repeat only the compact guard at the affected choice.
 
-> Repeat the behavioral invariant, not the owning skill’s entire explanation.
+> Repeat the behavioral invariant, not the owning skill's entire explanation.
 
-Do not repeat rules merely for emphasis, author reassurance, or stylistic consistency. Check that repeated wording preserves the same meaning and route.
-
-When removing, merging, moving, or rewording a rule that protects measured behavior, treat the candidate as a behavioral change and evaluate the affected boundary.
+Repetition for emphasis, author reassurance, or stylistic consistency does not earn its place. Check that repeated wording keeps the same meaning and route. Removing, merging, moving, or rewording an instruction that protects measured behavior is a behavioral change; evaluate the affected boundary.
 
 ## Add Resources Only When They Change Loading Or Ownership
 
 Before adding or reorganizing references, assets, or scripts, read [Progressive Disclosure](references/progressive-disclosure.md).
 
-Start with one `SKILL.md`. Remove accidental complexity before splitting files.
+Start with one `SKILL.md` and remove accidental complexity before splitting files.
 
 - Keep normal first-read behavior inline.
-- Add an activity-required reference when one named normal activity genuinely needs separately owned depth but the skill may exit before that activity.
-- Add a conditional reference when an observable branch requires depth that would obscure the normal route.
-- Use an entry-required reference only when separation has independent value, such as canonical reuse, separate ownership or lifecycle, generated contracts, compatibility, or host constraints.
-- Inline entry-required content when every useful activation reads it and separation provides no distinct value.
+- Add an activity-required reference when one named normal activity needs separately owned depth but the skill may exit before that activity.
+- Add a conditional reference when an observable branch needs depth that would obscure the normal route.
+- Use an entry-required reference only when separation has independent value, such as canonical reuse, separate ownership or lifecycle, generated contracts, compatibility, or host constraints; otherwise inline it.
 - Add a script when deterministic repeated work owned by the skill is safer, clearer, or materially less wasteful than model-generated operations.
-- Link every agent-facing resource, package dependency, and executable entrypoint from the body at its first useful decision.
 - Keep owned resources inside the package unless canonical cross-package ownership is required.
 
-The body and reference must name the same read condition. A reference cannot activate itself.
-
 There is no universal body template, line limit, reference count, or requirement that a script follow an earlier failure.
 
 ## Evaluate The Behavioral Claim
 
-Static inspection and package validation prove structure, not behavior.
-
-Name the exact claim being tested:
-
-- description activation;
-- first-read body behavior;
-- nearby behavior;
-- dependency composition;
-- retained use;
-- artifact outcome;
-- cross-host behavior.
-
-Use [Evaluate Skill](../evaluate-skill/SKILL.md) to compare exact baseline and candidate environments under fixed declared inputs.
-
-Preserve adequate existing evidence. Revise one measured pressure point at a time. After a behavior-sensitive change, rerun the complete fixed group with both variants.
+Goal: evidence that the skill changes behavior as intended, at the boundary being claimed.
 
-Do not claim:
+Name the exact claim: description activation, first-read body behavior, nearby behavior, dependency composition, retained use, artifact outcome, or cross-host behavior. Use [Evaluate Skill](../evaluate-skill/SKILL.md) to compare exact baseline and candidate environments under fixed declared inputs.
 
-- activation from explicit body injection;
-- retained use from one turn;
-- dependency behavior from ambient context;
-- unchanged behavior from prose review;
-- improvement from structural validation;
-- readiness from one favorable example.
+Evaluate the two kinds differently. A Rule passes when it is never broken, including under pressure to break it. Judgment passes on outcome, and its evidence should include a case where following the default literally is the worse choice, so a candidate that only obeys cannot pass.
 
-Small wording, ordering, vocabulary, repetition, and structural changes may alter model behavior. Human review can establish intended meaning; behavioral evidence establishes observed effect.
+Preserve adequate existing evidence. Revise one measured pressure point at a time, and after a behavior-sensitive change rerun the complete fixed group with both variants.
 
-Keep evaluation conclusions and missing evidence in the evaluation artifact, task record, or delivery report—not in the executing skill.
+Small wording, ordering, vocabulary, repetition, and structural changes can alter model behavior. Human review establishes intended meaning; behavioral evidence establishes observed effect.
 
 ## Check The Package
 
@@ -240,37 +207,30 @@ Use the bundled [skill author](scripts/skill-author.mjs) for deterministic packa
 node <write-skill-directory>/scripts/skill-author.mjs init <directory> --name <name> --description <text>
 node <write-skill-directory>/scripts/skill-author.mjs validate <directory> [--package-root <directory>]
 node <write-skill-directory>/scripts/skill-author.mjs inspect <directory> [--package-root <directory>]
+node <write-skill-directory>/scripts/skill-author.mjs similarity <directory> [--threshold <0-1>]
 ```
 
-Choose the operation by its evidence:
-
-- `init`: create a new minimal package; never overwrite an existing one.
+- `init`: create a new minimal package; it never overwrites an existing one.
 - `validate`: check frontmatter, heading shape, recursive links, declared package dependencies, and containment.
-- `inspect`: report body sizes, resource classes, scripts, unlinked files, and validation findings.
-
-Run `validate` after structural or dependency changes and before claiming package validity. Use `inspect` when factual inventory or package composition matters.
-
-Commands emit JSON. Invalid structure still emits a report and exits nonzero; command errors emit structured error JSON.
+- `inspect`: report body sizes, resource classes, scripts, unlinked files, and validation findings, when factual inventory matters.
+- `similarity`: report Markdown files under a directory that share copied or lightly edited passages. Run it across related skills before keeping repetition; it cannot detect paraphrase, so a clean report does not prove an instruction is stated once.
 
-Package root defaults to the nearest `package.json` ancestor, then the skill directory’s parent. Use `--package-root` when validating a candidate in an overlay or another package context.
+Commands emit JSON. Invalid structure still emits a report and exits nonzero; command errors emit structured error JSON. Package root defaults to the nearest `package.json` ancestor, then the skill directory's parent; use `--package-root` for a candidate in an overlay or another package context.
 
 Frontmatter accepts flat plain strings or JSON-compatible double-quoted strings. Quote ambiguous punctuation, number-like, boolean-like, or null-like values.
 
-Package validity does not prove behavioral quality. Never use deprecated authoring tooling.
-
 ## Stop
 
 Stop when the requested package:
 
 - expresses one coherent behavioral policy;
+- separates binding Rules from judgment;
 - activates at the earliest useful boundary;
 - remains safe on nearby and retained use;
 - works from guaranteed context on every valid path;
 - keeps its normal route executable on first read;
 - declares dependencies and resource conditions honestly;
-- contains no unsupported author-facing residue;
+- contains no author-facing residue;
 - passes required structural checks.
 
-Stop and ask when accepted behavior, activation, dependencies, safety, compatibility, or another user-owned boundary cannot be settled from evidence.
-
-Do not add sections, references, examples, scripts, or procedure merely to make the package look complete.
+Stop and ask when accepted behavior, activation, dependencies, safety, compatibility, or another user-owned boundary cannot be settled from evidence. Do not add sections, references, examples, scripts, or procedure merely to make the package look complete.

package/skills/write-skill/references/activation-boundaries.md

@@ -2,6 +2,8 @@
 
 Read this when activation is unclear or evidence shows missed, late, early, task-hijacking, or retained-interference behavior.
 
+This reference is judgment: adapt it to the skill's goal. Its binding statements restate [Write Skill](../SKILL.md) Rules.
+
 A description should make the skill available at the earliest useful decision without requiring language introduced by the skill itself.
 
 ## Diagnose The First Read