From f6d0efdfc030c95c375d7bd3b7ef350713b18ad9 Mon Sep 17 00:00:00 2001 From: tmk241 Date: Wed, 12 Aug 2026 01:05:49 +0200 Subject: [PATCH] Align Ink skills with frozen delegation contracts --- AGENTS.md | 2 +- skills/audit-ink-cli/SKILL.md | 8 +++---- skills/configure-ink-agent/SKILL.md | 4 ++-- skills/create-ink-tool/SKILL.md | 34 ++++++++++++++--------------- 4 files changed, 24 insertions(+), 24 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 592dc95..babebee 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,7 @@ ## Rules - A skill owns reusable judgment, never runtime policy or repeatable mechanics. -- Ink source and `REQUIREMENTS.md` own host behavior; `toolset` owns external executables. +- Ink source and `SPEC.md` own host behavior; `toolset` owns external executables. - Keep skill names lowercase and hyphenated; directory and frontmatter name must match. - `link` only creates symlinks. `import` may materialize only a caller-supplied, SHA-256-verified local archive in the content-addressed store. Do not add URL, diff --git a/skills/audit-ink-cli/SKILL.md b/skills/audit-ink-cli/SKILL.md index 32b63fe..faf6953 100644 --- a/skills/audit-ink-cli/SKILL.md +++ b/skills/audit-ink-cli/SKILL.md @@ -37,14 +37,14 @@ changes belong to Ink's repository authority and implementation workflow. - A human/operator may invoke Ink outside the governed agent. Give a copyable operator command only when the user asks and its public help contract is proven. - Use user-provided runtime output as runtime evidence. Otherwise inspect the - installed artifact identity and a demonstrably matching checkout's requirements, + installed artifact identity and a demonstrably matching checkout's specification, tests, public help text, and source; label those findings as contract/source evidence rather than executed runtime proof. - Global and project policy files explain only their contribution. Effective authority also depends on all policy layers, pinned executable and contract bytes, startup freezing, and session decisions. - Treat handovers, READMEs, examples, hidden source branches, and remembered argv - as leads. Public help owns operator-facing commands; requirements own intended + as leads. Public help owns operator-facing commands; the specification owns intended behavior; tests and source establish current checkout behavior. Distinguish three surfaces explicitly: @@ -71,7 +71,7 @@ the frozen `tool delegate` subject. **source-confirmed**, **missing**, **stale claim**, or **not proven**. 4. For an operator action, explain that the user—not the hosted agent—must run it. Do not inspect or mutate session state as a substitute. -5. For a missing capability, require Ink's requirements authority before source +5. For a missing capability, require Ink's specification authority before source implementation. Do not model it as a new external executable merely to bypass the host boundary. @@ -93,7 +93,7 @@ the frozen `tool delegate` subject. EVIDENCE: SURFACE: FINDING: -ACTION: +ACTION: ``` Positive smoke: “Does Ink have a sessions command, and why can’t you run it?” diff --git a/skills/configure-ink-agent/SKILL.md b/skills/configure-ink-agent/SKILL.md index cb28555..48dd3eb 100644 --- a/skills/configure-ink-agent/SKILL.md +++ b/skills/configure-ink-agent/SKILL.md @@ -63,7 +63,7 @@ no ancestor-chain project-agent discovery. - `read` children may overlap and receive an immutable host floor with no command, file-mutation, lifecycle-mutation, or delegation authority. - `write` children are exclusive, operate in the canonical parent cwd, pause - parent effects, and still receive only their effective frozen policy. + parent mutations, and still receive only their effective frozen policy. Never infer effective authority from `access`, prompt text, or a `policy:` label. Use the child policy snapshot and a real allowed/denied smoke. @@ -87,7 +87,7 @@ referenced bytes are pinned and conjoined into the child effective policy. ## Decision loop -1. Choose `read` unless the child must produce a real effect. +1. Choose `read` unless the child must perform a real mutation. 2. Choose the smallest model alias that fits the specialist job. 3. Put the definition in user scope or exact project cwd according to intended precedence. diff --git a/skills/create-ink-tool/SKILL.md b/skills/create-ink-tool/SKILL.md index a68a1be..b9a269f 100644 --- a/skills/create-ink-tool/SKILL.md +++ b/skills/create-ink-tool/SKILL.md @@ -13,7 +13,7 @@ description: >- ## One job Design a **permission-sized executable** whose name and argv expose its reachable -effects so Ink can discover, digest-pin, and grant it without granting a platform. +reads and mutations so Ink can discover, digest-pin, and grant it without granting a platform. One executable need not mean one source file: share private build-time modules when that does not widen runtime authority. @@ -21,26 +21,26 @@ when that does not widen runtime authority. Read only what can change the boundary: -- the exact job and every reachable side effect; -- Ink's current requirements, policy grammar, and mutation protocol; +- the exact job and every reachable mutation; +- Ink's current specification, policy grammar, and mutation protocol; - neighboring tools and existing executables that may already satisfy the job; - resource, credential, selector, target, packaging, and proof contracts; -- repository requirements and tests. +- repository specification and tests. Project authority outranks this skill. Missing selector semantics, credentials, recovery rules, or external contracts are blockers—not adapter opportunities. ```text -JOB -> REUSE? -> EFFECTS -> BOUNDARY -> CONTRACT -> ARTIFACT -> PROOF +JOB -> REUSE? -> READS/MUTATIONS -> BOUNDARY -> CONTRACT -> ARTIFACT -> PROOF ``` 1. Reuse a directly inspectable executable only when granting its whole reachable surface is honest; otherwise build the coherent missing boundary, not a wrapper. -2. Enumerate reads, mutations, network effects, secrets, state, children, and +2. Enumerate reads, mutations, network calls, secrets, state, children, and config/plugin discovery; split where approval, blast radius, or recovery differ. 3. Define argv, selectors, streams, errors, dependencies, exhaustive versus bounded output, and any tool-owned semantic presentation without recreating - shell grammar or a host-wide effect ontology. + shell grammar or a host-wide mutation ontology. 4. State the runtime artifact honestly, then falsify its boundary, behavior, presentation, and portability claims through Ink's real run entry point. @@ -108,7 +108,7 @@ Shell globs, path filters, and content patterns are different contracts. `find`/`fd` forms that execute or delete and `rg` forms that launch preprocessors are not read boundaries merely because one intended invocation only searches. A -narrow native search tool is justified when it removes reachable effects, adds +narrow native search tool is justified when it removes reachable mutations, adds canonical path selectors, or supplies the required static portable artifact. Implement the coherent missing subset, not a compatibility facade or renamed wrapper. @@ -125,8 +125,8 @@ tool apply # revalidate; perform once Required properties: -- `stage` performs no external effect and resolves no secrets; -- the manifest pins executable identity, canonical effect, authority subject, +- `stage` performs no mutation and resolves no secrets; +- the manifest pins executable identity, canonical mutation, authority subject, non-secret inputs, and drift-sensitive hashes; - selectors are variable semantic facts, never argv prefixes, shell text, or executable invariants; @@ -149,7 +149,7 @@ layout; the tool owns meaning. Use the repository's elected projection envelope and bounds exactly; never invent per-tool presentation formats. Within that contract, use a small display -vocabulary rather than universal effect kinds: +vocabulary rather than universal mutation kinds: - headline and canonical target; - ordered key/value facts; @@ -159,7 +159,7 @@ vocabulary rather than universal effect kinds: Filesystem, HTTP, cloud, and infrastructure tools express their own semantics with those primitives. For example, an HTTP mutator supplies method, canonical origin/path, bounded body summary, status, and final URL as facts; it does not ask -Ink to understand an `http` effect type. An infrastructure tool supplies account, +Ink to understand an `http` mutation type. An infrastructure tool supplies account, resource, region, and requested change as facts; it does not create a renderer branch for its provider. @@ -169,7 +169,7 @@ The projection is presentation evidence, never authority: - derive projection records purely from that value and hash their exact semantic bytes with the manifest; - render approval from the exact staged projection stored under that identity; -- apply accepts only staged id plus hash, never replacement target, body, effect, +- apply accepts only staged id plus hash, never replacement target, body, mutation, or projection inputs; - the receipt identifies the exact staged manifest and may add only outcome and evidence facts; it cannot rewrite approved records; @@ -189,7 +189,7 @@ otherwise expose manifests, hashes, encoded payloads, or provider internals. ## CLI and stream contract -`tool --help` is the tested human contract: effects, argv, streams, ordering, +`tool --help` is the tested human contract: mutations, argv, streams, ordering, exits, environment/config precedence, credential timing, dependencies, pattern semantics, and one realistic pipeline. Explicit help succeeds on stdout; usage errors fail on stderr. Selector help gives value grammar, canonicalization, and a @@ -250,7 +250,7 @@ interpreters, or generated-client machinery unless they are the named job. Use the smallest matrix that can falsify the actual claims: - help/contract agree with accepted argv and selectors; -- main path and one forbidden near miss with zero unintended effect; +- main path and one forbidden near miss with zero unintended mutation; - each reader selector has an adjacent no-match before access; - each mutator has admitted, approval-required, refused, drift, duplicate, and indeterminate/recovery outcomes as applicable; @@ -278,7 +278,7 @@ Do not: - wrap or partially clone a utility whose whole admitted surface already fits; - combine read and mutation for code reuse; - expose a generic request/admin/registry platform; -- invent invariant selectors, a universal effect ontology, or executable-name +- invent invariant selectors, a universal mutation ontology, or executable-name branches in Ink's renderer; - let tools choose terminal styling or let presentation metadata grant authority; - treat argv prefixes, globs, or regexes as canonical path authority; @@ -312,7 +312,7 @@ Report only: - **Presentation:** an HTTP mutator derives method, canonical target, and bounded body summary from one staged operation; Ink renders the exact stored projection without an `httpsend` branch and overlays receipt-bound status/final URL only. -- **Presentation sprawl:** “support AWS changes” does not add an AWS effect enum or +- **Presentation sprawl:** “support AWS changes” does not add an AWS mutation enum or renderer branch; the permission-sized infrastructure tool projects account, region, resource, requested change, outcome, and evidence through the elected generic vocabulary.