docs(spec): document skill safe_mode, resource taxonomy, and script execution gate #164

New issue

Open

opened 2026-11-09 16:21:37 +00:00 by CoreRasurae · 0 comments

CoreRasurae commented

2026-11-09 16:21:37 +00:00

Member

Metadata

Commit Message: docs(spec): document skill safe_mode, resource taxonomy, and script execution gate
Branch: feature/m1-skill-resource-spec-update

Background and context

ADR-2034's original follow-up required the Skill Package Schema and the skills
field to be folded into the standards. The revision of 2026-11-09 adds D-8
(resource taxonomy), D-9 (safe_mode and the double-safety gate), and D-10
(script execution). The Actor Configuration Standard and the Package Registry
Standard do not yet describe these capabilities, so implementations cannot be
declared conformant against them.

Current behavior

docs/actor-registry-standard.md §16.1 documents the original Skill Package
Schema only.
§16.3 shows only scripts/ and references/ resource examples.
docs/index.md §4.4 does not document the skills field at all.
The standard revision history has no entry for the D-8–D-10 extension.

Expected behavior

Update docs/actor-registry-standard.md §16.1 with the optional safe_mode
field and the references/, assets/, scripts/, non-standard, and root-file
taxonomy.
Update §16.3 with an example containing an asset, a script, and a non-standard
folder, and show safe_mode: false only where privileged operations are
intended.
Add a §15.1 revision-history row for a minor version bump to 1.2.0 attributing
the change to ADR-2034 D-8–D-10.
Update docs/index.md §4.4 with the optional skills field, its reference
schemes, the progressive-disclosure loading model, and the double-safety gate
for scripts and non-standard folders; add the corresponding revision-history
entry.
State explicitly that safe mode is the default and unsafe is opt-in, matching
ADR-2030/ADR-2035.

Acceptance criteria

§16.1 lists safe_mode with type, default, and canonical-absence rules.
§16.1 and §16.3 describe every resource class and state that assets are
readable in every mode, scripts are readable but executable only under the
gate, and non-standard folders are gated for both read and execution.
The Package Registry Standard version is bumped to 1.2.0 with a §15.1 row
referencing ADR-2034.
docs/index.md §4.4 documents skills, the three reference schemes, and the
double-safety gate, with a §21.1 revision-history entry.
No existing normative requirement is weakened; the additions are expressed as
a §1.3 extension.
MkDocs builds cleanly (nox -s docs or the project's documented docs build
session).
New Behave/Robot tests are not required for a documentation-only change.

Supporting information

ADR-2034 (revision 2026-11-09), D-8, D-9, D-10
docs/actor-registry-standard.md §15.1, §16.1, §16.3
docs/index.md §4.4 and §21.1
Agent Skills specification: https://agentskills.io/specification

Subtasks

Update Package Registry Standard §16.1, §16.3, and §15.1
Update Actor Configuration Standard §4.4 and §21.1
Verify cross-links to ADR-2034 are correct
Build the documentation and fix any warnings/errors
Verify all specification examples remain valid YAML

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line matches the Commit Message in
Metadata exactly.
The commit is pushed to the branch matching Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged.

## Metadata - **Commit Message**: `docs(spec): document skill safe_mode, resource taxonomy, and script execution gate` - **Branch**: `feature/m1-skill-resource-spec-update` ## Background and context ADR-2034's original follow-up required the Skill Package Schema and the `skills` field to be folded into the standards. The revision of 2026-11-09 adds D-8 (resource taxonomy), D-9 (`safe_mode` and the double-safety gate), and D-10 (script execution). The Actor Configuration Standard and the Package Registry Standard do not yet describe these capabilities, so implementations cannot be declared conformant against them. ## Current behavior - `docs/actor-registry-standard.md` §16.1 documents the original Skill Package Schema only. - §16.3 shows only `scripts/` and `references/` resource examples. - `docs/index.md` §4.4 does not document the `skills` field at all. - The standard revision history has no entry for the D-8–D-10 extension. ## Expected behavior - Update `docs/actor-registry-standard.md` §16.1 with the optional `safe_mode` field and the `references/`, `assets/`, `scripts/`, non-standard, and root-file taxonomy. - Update §16.3 with an example containing an asset, a script, and a non-standard folder, and show `safe_mode: false` only where privileged operations are intended. - Add a §15.1 revision-history row for a minor version bump to 1.2.0 attributing the change to ADR-2034 D-8–D-10. - Update `docs/index.md` §4.4 with the optional `skills` field, its reference schemes, the progressive-disclosure loading model, and the double-safety gate for scripts and non-standard folders; add the corresponding revision-history entry. - State explicitly that safe mode is the default and unsafe is opt-in, matching ADR-2030/ADR-2035. ## Acceptance criteria - §16.1 lists `safe_mode` with type, default, and canonical-absence rules. - §16.1 and §16.3 describe every resource class and state that assets are readable in every mode, scripts are readable but executable only under the gate, and non-standard folders are gated for both read and execution. - The Package Registry Standard version is bumped to 1.2.0 with a §15.1 row referencing ADR-2034. - `docs/index.md` §4.4 documents `skills`, the three reference schemes, and the double-safety gate, with a §21.1 revision-history entry. - No existing normative requirement is weakened; the additions are expressed as a §1.3 extension. - MkDocs builds cleanly (`nox -s docs` or the project's documented docs build session). - New Behave/Robot tests are not required for a documentation-only change. ## Supporting information - ADR-2034 (revision 2026-11-09), D-8, D-9, D-10 - `docs/actor-registry-standard.md` §15.1, §16.1, §16.3 - `docs/index.md` §4.4 and §21.1 - Agent Skills specification: https://agentskills.io/specification ## Subtasks - [ ] Update Package Registry Standard §16.1, §16.3, and §15.1 - [ ] Update Actor Configuration Standard §4.4 and §21.1 - [ ] Verify cross-links to ADR-2034 are correct - [ ] Build the documentation and fix any warnings/errors - [ ] Verify all specification examples remain valid YAML ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the first line matches the Commit Message in Metadata exactly. - The commit is pushed to the branch matching Branch in Metadata exactly. - The commit is submitted as a pull request to `master`, reviewed, and merged.

CoreRasurae added this to the v2.1.0 milestone

2026-11-09 16:21:37 +00:00

CoreRasurae added the

labels

2026-11-09 16:21:37 +00:00

CoreRasurae added a new dependency