Add OpenSpec proposal for non-asset file support in facet archives - #428
Conversation
|
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds an OpenSpec change proposing explicitly declared supplementary non-asset files in facet archives. It defines deterministic packaging, canonical path validation, per-entry integrity checks, versioned archive and lockfile schemas, strict verification, and legacy compatibility. Skill-directory companions are materialized atomically through adapter bundles, while other supplementary files remain archive-only. Authoring workflows add README support, edit reconciliation, scaffolding, and transactional application. Adversarial reviews and task artifacts record compatibility, security, ownership, rollout, and validation requirements. Sequence Diagram(s)sequenceDiagram
participant Author
participant FacetEditor
participant BuildCommand
participant ArchiveVerifier
participant Installer
participant Adapter
Author->>FacetEditor: declare supplementary files
FacetEditor->>BuildCommand: apply validated manifest
BuildCommand->>ArchiveVerifier: produce verifiable archive
ArchiveVerifier->>Installer: return verified asset plan
Installer->>Adapter: install skills with companion bytes
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
This stack of pull requests is managed by Graphite. Learn more about stacking. |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e934247f55
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
e934247 to
caa58a2
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: caa58a2979
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8f4c3a6271
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: b1b2e90d-57bd-493a-9bb1-b8da55805771
📒 Files selected for processing (20)
openspec/changes/support-non-asset-files/adversarial/artifacts/design.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/adapter__assets/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/authoring__facets/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/installation/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/protocol/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/protocol__content-hashing/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/protocol__integrity/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/protocol__schemas/spec.mdopenspec/changes/support-non-asset-files/adversarial/reviews/design-review.mdopenspec/changes/support-non-asset-files/adversarial/reviews/specs-review.mdopenspec/changes/support-non-asset-files/adversarial/state.jsonopenspec/changes/support-non-asset-files/design.mdopenspec/changes/support-non-asset-files/proposal.mdopenspec/changes/support-non-asset-files/specs/adapter__assets/spec.mdopenspec/changes/support-non-asset-files/specs/authoring__facets/spec.mdopenspec/changes/support-non-asset-files/specs/installation/spec.mdopenspec/changes/support-non-asset-files/specs/protocol/spec.mdopenspec/changes/support-non-asset-files/specs/protocol__content-hashing/spec.mdopenspec/changes/support-non-asset-files/specs/protocol__integrity/spec.mdopenspec/changes/support-non-asset-files/specs/protocol__schemas/spec.md
8f4c3a6 to
0bc8f53
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0bc8f53444
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
0bc8f53 to
4f71fd8
Compare
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (1)
openspec/changes/support-non-asset-files/adversarial/state.json (1)
27-27:⚠️ Potential issue | 🟠 MajorAlign the reconciliation state with the finalized specification artifacts.
The recorded reconciliation notes in
state.jsoncontradict the contents of the final artifacts. The notes claim that "protocol package and adapter SDK each marked as new major releases" and "scaffold writes README undeclared during rollout window". However, the design and thetasks.mdexecution plan explicitly retain the minor-release policy and the default README scaffolding.Please correct the reconciliation notes to accurately reflect the final decisions, as they currently falsely claim that major releases and a disabled README scaffold were adopted.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 2dc0fc9b-94ce-4945-961d-211dd2cc1ed5
📒 Files selected for processing (23)
openspec/changes/support-non-asset-files/adversarial/artifacts/design.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/adapter__assets/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/authoring__facets/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/installation/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/protocol/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/protocol__content-hashing/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/protocol__integrity/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/protocol__schemas/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/tasks.mdopenspec/changes/support-non-asset-files/adversarial/reviews/design-review.mdopenspec/changes/support-non-asset-files/adversarial/reviews/specs-review.mdopenspec/changes/support-non-asset-files/adversarial/reviews/tasks-review.mdopenspec/changes/support-non-asset-files/adversarial/state.jsonopenspec/changes/support-non-asset-files/design.mdopenspec/changes/support-non-asset-files/proposal.mdopenspec/changes/support-non-asset-files/specs/adapter__assets/spec.mdopenspec/changes/support-non-asset-files/specs/authoring__facets/spec.mdopenspec/changes/support-non-asset-files/specs/installation/spec.mdopenspec/changes/support-non-asset-files/specs/protocol/spec.mdopenspec/changes/support-non-asset-files/specs/protocol__content-hashing/spec.mdopenspec/changes/support-non-asset-files/specs/protocol__integrity/spec.mdopenspec/changes/support-non-asset-files/specs/protocol__schemas/spec.mdopenspec/changes/support-non-asset-files/tasks.md
🚧 Files skipped from review as they are similar to previous changes (8)
- openspec/changes/support-non-asset-files/specs/protocol/spec.md
- openspec/changes/support-non-asset-files/specs/adapter__assets/spec.md
- openspec/changes/support-non-asset-files/specs/protocol__content-hashing/spec.md
- openspec/changes/support-non-asset-files/adversarial/artifacts/specs/protocol__integrity/spec.md
- openspec/changes/support-non-asset-files/proposal.md
- openspec/changes/support-non-asset-files/adversarial/artifacts/specs/installation/spec.md
- openspec/changes/support-non-asset-files/specs/installation/spec.md
- openspec/changes/support-non-asset-files/specs/protocol__integrity/spec.md
513f3b9 to
7b89aad
Compare
4f71fd8 to
a7d09e2
Compare
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using high effort and found 3 potential issues.
There are 4 total unresolved issues (including 1 from previous review).
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit a7d09e2. Configure here.
There was a problem hiding this comment.
Actionable comments posted: 8
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: f1057f96-8e02-4e9d-8eb6-a51da3236217
📒 Files selected for processing (26)
openspec/changes/support-non-asset-files/.openspec.yamlopenspec/changes/support-non-asset-files/adversarial/artifacts/design.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/proposal.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/adapter__assets/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/authoring__facets/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/installation/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/protocol/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/protocol__content-hashing/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/protocol__integrity/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/protocol__schemas/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/tasks.mdopenspec/changes/support-non-asset-files/adversarial/reviews/design-review.mdopenspec/changes/support-non-asset-files/adversarial/reviews/proposal-review.mdopenspec/changes/support-non-asset-files/adversarial/reviews/specs-review.mdopenspec/changes/support-non-asset-files/adversarial/reviews/tasks-review.mdopenspec/changes/support-non-asset-files/adversarial/state.jsonopenspec/changes/support-non-asset-files/design.mdopenspec/changes/support-non-asset-files/proposal.mdopenspec/changes/support-non-asset-files/specs/adapter__assets/spec.mdopenspec/changes/support-non-asset-files/specs/authoring__facets/spec.mdopenspec/changes/support-non-asset-files/specs/installation/spec.mdopenspec/changes/support-non-asset-files/specs/protocol/spec.mdopenspec/changes/support-non-asset-files/specs/protocol__content-hashing/spec.mdopenspec/changes/support-non-asset-files/specs/protocol__integrity/spec.mdopenspec/changes/support-non-asset-files/specs/protocol__schemas/spec.mdopenspec/changes/support-non-asset-files/tasks.md
🚧 Files skipped from review as they are similar to previous changes (12)
- openspec/changes/support-non-asset-files/specs/protocol/spec.md
- openspec/changes/support-non-asset-files/.openspec.yaml
- openspec/changes/support-non-asset-files/specs/adapter__assets/spec.md
- openspec/changes/support-non-asset-files/adversarial/reviews/proposal-review.md
- openspec/changes/support-non-asset-files/adversarial/artifacts/specs/installation/spec.md
- openspec/changes/support-non-asset-files/adversarial/state.json
- openspec/changes/support-non-asset-files/specs/protocol__integrity/spec.md
- openspec/changes/support-non-asset-files/tasks.md
- openspec/changes/support-non-asset-files/adversarial/artifacts/tasks.md
- openspec/changes/support-non-asset-files/specs/protocol__content-hashing/spec.md
- openspec/changes/support-non-asset-files/specs/installation/spec.md
- openspec/changes/support-non-asset-files/adversarial/artifacts/specs/protocol__integrity/spec.md
a7d09e2 to
1c5a6dc
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1c5a6dc339
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
2eada07 to
69b1df3
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 69b1df35d4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| An adapter SHALL accept an installation request whose content shape is determined by asset type. Every installation request SHALL identify its scope and asset name. A skill request SHALL carry the primary `SKILL.md` text, per-asset metadata, a canonical map from companion paths relative to the skill root to opaque bytes, and the caller-verified set of previously-owned companion paths; an empty companion map and an empty previously-owned set SHALL each be valid. Adapters SHALL NOT persist ownership metadata or infer ownership from disk contents; ownership data arrives in each request from the caller's lockfile and receipt records. Agent and command requests SHALL each carry one text content value and per-asset metadata and SHALL NOT carry companions or ownership sets. No installation request SHALL represent archive-only supplementary files. | ||
|
|
||
| The adapter SHALL own path resolution, containment, directory creation, metadata assembly, storage format, and rollback. Before any filesystem access, every supplied companion path — new or previously owned — SHALL be validated as relative, canonical, and confined below the resolved skill root; a request containing a malformed or escaping path SHALL be rejected without reading, writing, or deleting anything. Skill installation SHALL replace the complete owned bundle atomically: the new primary and companions SHALL all commit, with previously-owned companion paths absent from the new request removed, or the prior bundle SHALL remain intact. Removal during replacement SHALL be limited to the supplied previously-owned set. Companion bytes SHALL be stored verbatim; metadata or front-matter transformation SHALL apply only to the primary file. Unowned files SHALL NOT be removed. Expected failures SHALL be returned as structured results. Atomicity SHALL cover handled failures within one operation; recovery from an interrupted operation is the caller's idempotent re-install, so installation SHALL remain idempotent and convergent. |
There was a problem hiding this comment.
SKILL.md
A skill request whose companion map contains SKILL.md passes the stated relative/canonical/contained validation but targets the same file as the primary. Such a request cannot satisfy both guarantees that the primary receives metadata transformation and companions are stored verbatim; depending on write ordering, it overwrites the primary or companion and makes the bundle invalid. Require adapter-side rejection of SKILL.md (and path conflicts with the primary) before any filesystem access.
Useful? React with 👍 / 👎.
69b1df3 to
673386f
Compare
673386f to
f5e650e
Compare
65d98f4 to
c3520e0
Compare
f5e650e to
43cb4de
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 43cb4de459
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| **Documentation (Article III)** | ||
|
|
||
| This proposal was informed by `docs/specification/archive.mdx` (content rules: path safety, manifest completeness, outer exclusivity), `docs/specification/build.mdx` (steps 2 and 5), `docs/specification/manifest.mdx` (text-asset conventional paths), and `docs/specification/integrity.mdx` (hash definitions, receipt asset tuples). All four SHALL be updated as scoped work in this change, together with the authoring and installation guides (`docs/guides/create-your-first-facet.mdx`, `docs/guides/install-facets.mdx`) and root `README.md`, which describe facets in asset-only terms today. `docs/specification/lockfile.mdx` SHALL be updated for lockfile `0.2`, per-materialized-file integrity, legacy-alpha-1 migration, and the distinction between version-controlled canonical hashes and machine-local receipt ownership. `docs/specification/commit.mdx` SHALL be updated for receipt file-ownership records and transactional reconciliation, and `docs/guides/custom-adapters.mdx` SHALL be updated for the breaking tagged adapter contract so third-party adapter authors are not left with the single-content instructions. |
There was a problem hiding this comment.
Add docs/cli/authoring/create.mdx and docs/cli/authoring/edit.mdx to the scoped updates. They are user-facing command references, not either of the named guides, and currently say the wizard creates only facet.json plus asset files and that source front matter survives builds; the proposed default README and primary-file front-matter rejection make both statements stale. Leaving them outside the explicit Article III scope can ship the new workflow with contradictory CLI documentation.
Useful? React with 👍 / 👎.
|
|
||
| ## 14. Documentation and Release Readiness — Implementation | ||
|
|
||
| - [ ] 14.1 Implement: Update archive, build, manifest, integrity, lockfile, commit, install, publish, and terminology documentation for supplementary membership, strict versions, path safety, per-file hashes, and atomic skill bundles |
There was a problem hiding this comment.
Scope a delta for openspec/specs/publishing/spec.md, not only its documentation page. Its publish-verification requirement currently permits checking the build manifest's per-asset hashes, while 0.2 replaces that map with files and requires archive-only supplementary entries to be verified too. Without a publishing capability/spec update, an implementation following the unchanged publish spec can accept an archive whose README or other archive-only file was tampered with, contrary to the new integrity requirements.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Actionable comments posted: 4
♻️ Duplicate comments (3)
openspec/changes/support-non-asset-files/adversarial/artifacts/design.md (3)
30-43: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy liftAlign the declaration model with the normative specs.
This still defines one top-level
filesarray and permitsskills/<name>/...entries there, whileopenspec/changes/support-non-asset-files/specs/authoring__facets/spec.mdLines 271-302 andopenspec/changes/support-non-asset-files/specs/protocol__schemas/spec.mdLines 11-13 require separate per-skillfilesarrays and reject top-level declarations underskills/. Resolve this before implementation or producers and consumers will disagree on manifest shape and ownership.
53-67: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy liftReconcile the archive-version contract.
This section assigns supplementary archives
facetVersion: 1, butopenspec/changes/support-non-asset-files/specs/protocol__schemas/spec.mdLines 203-209 and the PR objective define the current format asfacetVersion: 0.2. Version dispatch, fixtures, and release compatibility cannot be implemented consistently until one value is authoritative.
107-115: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy liftReconcile lockfile ownership with the schema contract.
The design says the lockfile remains unchanged and companion ownership is receipt-only, but
openspec/changes/support-non-asset-files/specs/protocol__schemas/spec.mdLines 139-147 requires lockfile0.2asset entries with per-file integrity records. Decide whether those records are normative lockfile data or remove that requirement from the schema and dependent workflows.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 352d60d5-9049-4a98-967a-3f6dd715c71b
📒 Files selected for processing (26)
openspec/changes/support-non-asset-files/.openspec.yamlopenspec/changes/support-non-asset-files/adversarial/artifacts/design.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/proposal.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/adapter__assets/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/authoring__facets/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/installation/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/protocol/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/protocol__content-hashing/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/protocol__integrity/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/specs/protocol__schemas/spec.mdopenspec/changes/support-non-asset-files/adversarial/artifacts/tasks.mdopenspec/changes/support-non-asset-files/adversarial/reviews/design-review.mdopenspec/changes/support-non-asset-files/adversarial/reviews/proposal-review.mdopenspec/changes/support-non-asset-files/adversarial/reviews/specs-review.mdopenspec/changes/support-non-asset-files/adversarial/reviews/tasks-review.mdopenspec/changes/support-non-asset-files/adversarial/state.jsonopenspec/changes/support-non-asset-files/design.mdopenspec/changes/support-non-asset-files/proposal.mdopenspec/changes/support-non-asset-files/specs/adapter__assets/spec.mdopenspec/changes/support-non-asset-files/specs/authoring__facets/spec.mdopenspec/changes/support-non-asset-files/specs/installation/spec.mdopenspec/changes/support-non-asset-files/specs/protocol/spec.mdopenspec/changes/support-non-asset-files/specs/protocol__content-hashing/spec.mdopenspec/changes/support-non-asset-files/specs/protocol__integrity/spec.mdopenspec/changes/support-non-asset-files/specs/protocol__schemas/spec.mdopenspec/changes/support-non-asset-files/tasks.md
🚧 Files skipped from review as they are similar to previous changes (12)
- openspec/changes/support-non-asset-files/.openspec.yaml
- openspec/changes/support-non-asset-files/specs/protocol/spec.md
- openspec/changes/support-non-asset-files/adversarial/reviews/proposal-review.md
- openspec/changes/support-non-asset-files/adversarial/state.json
- openspec/changes/support-non-asset-files/adversarial/artifacts/tasks.md
- openspec/changes/support-non-asset-files/adversarial/artifacts/specs/protocol__integrity/spec.md
- openspec/changes/support-non-asset-files/specs/protocol__integrity/spec.md
- openspec/changes/support-non-asset-files/specs/protocol__content-hashing/spec.md
- openspec/changes/support-non-asset-files/tasks.md
- openspec/changes/support-non-asset-files/specs/adapter__assets/spec.md
- openspec/changes/support-non-asset-files/adversarial/artifacts/specs/installation/spec.md
- openspec/changes/support-non-asset-files/specs/installation/spec.md
|
|
||
| ### Requirement: Build output is assembled into a compressed archive | ||
|
|
||
| The system SHALL assemble all resolved build output into a two-layer archive file with the extension `.facet`. The outer layer SHALL be an uncompressed tar containing exactly two entries: `build-manifest.json` and `archive.tar.gz`. The inner `archive.tar.gz` SHALL be a gzip-compressed tar containing the facet manifest, all resolved text asset files, all declared skill companion files at their paths beneath their skill's directory, and all declared archive-only supplementary files at their declared paths. Every inner entry SHALL be derivable from a declaration in the facet manifest; the system SHALL NOT include any file that is not so derivable. The archive filename SHALL follow the pattern `<name>-<version>.facet` where `name` and `version` come from the facet manifest. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Define the implicit facet-manifest entry.
The inner archive contains facet.json, but line [31] says every entry must derive from a declaration inside that same manifest. Explicitly exempt the authoritative facet.json entry as an implicit fixed entry, with only assets and supplementary files derived from declarations; otherwise builders and verifiers have no non-circular membership rule.
| ### Requirement: Valid facet manifests are accepted | ||
|
|
||
| The system SHALL accept a facet manifest that conforms to the manifest schema. A valid manifest has a name, a version, and at least one text asset or composed facet. The name SHALL be either an unscoped kebab-case facet identity or a scoped `@scope/name` identity. A manifest MAY include an optional top-level `private` boolean and supplementary-file declarations. Skills, agents, and commands SHALL use descriptors with required descriptions and optional platform metadata; prompt content SHALL be inferred from conventional paths rather than descriptor references. | ||
|
|
||
| Current-format skill, agent, and command names SHALL be single segments of 1–64 lowercase ASCII letters, digits, or hyphens, with no leading, trailing, or consecutive hyphens. Skills SHALL use `skills/<name>/SKILL.md`, agents `agents/<name>.md`, and commands `commands/<name>.md`. Skills and commands SHALL use disjoint names; agents MAY share a name with either. | ||
|
|
||
| #### Scenario: Minimal valid manifest with a skill | ||
|
|
||
| - **WHEN** an author provides a name, version, and one valid skill descriptor with a description | ||
| - **THEN** the system SHALL accept the manifest | ||
|
|
||
| #### Scenario: Valid manifest with a scoped facet identity | ||
|
|
||
| - **WHEN** an author provides name `@julian/cowsay`, a version, and one valid skill descriptor | ||
| - **THEN** the system SHALL accept the manifest | ||
|
|
||
| #### Scenario: Manifest with all sections | ||
|
|
||
| - **WHEN** an author provides identity fields, skill, agent, and command descriptors, composed facets, server references, and supplementary declarations | ||
| - **THEN** the system SHALL accept the manifest |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Remove or explicitly scope unsupported composition and server-reference fields.
This authoring requirement says manifests containing composed facets and server references are valid, but protocol__schemas explicitly excludes those fields from the current user-facing manifest contract. Either remove this scenario and the acceptance language, or mark these fields as legacy/out-of-scope with a defined compatibility rule; otherwise authoring can produce manifests that the published schema rejects.
43cb4de to
a17d95c
Compare
Merge activity
|
1 participant
Why
Facet authors cannot currently include documentation, licenses, development notes, or companion skill resources in a built facet. The build pipeline collects only conventional asset paths, and archive verification rejects every entry that is not a declared skill, agent, command, or manifest ("outer exclusivity"). These files are silently dropped at build time and hard-rejected at verification, so authors cannot ship them at all. Facets need a safe way to carry supporting files without falsely treating them as independently installable assets.
Details
This change introduces an OpenSpec proposal and its adversarial review for
support-non-asset-files, reconciling findings from both into a final proposal. Key decisions captured:skills/<name>/are installed and removed atomically with their owning skill through the adapter contract, with receipt data sufficient for drift removal. This is a breaking change to the adapter SDK's single-file-per-asset contract.README.md,LICENSEat the root) are shipped and integrity-protected but never written to disk at install time. They gain no asset type, adapter metadata, independent install scope, or lockfile asset tuples.assetsmap.Affected domains:
protocol__schemas,protocol__content-hashing,protocol__integrity,authoring__facets,installation, andadapter__assets. No new capability domain is introduced.Documentation updates are scoped to
docs/specification/archive.mdx,docs/specification/build.mdx,docs/specification/manifest.mdx,docs/specification/integrity.mdx,docs/guides/create-your-first-facet.mdx,docs/guides/install-facets.mdx, and rootREADME.md.docs/specification/lockfile.mdxmust be reviewed and updated if receipt or lockfile semantics change for multi-file skills.Note
Low Risk
This PR only adds specification and planning artifacts under
openspec/; no protocol, engine, adapter, or CLI runtime behavior changes until follow-up implementation lands.Overview
Adds the reconciled OpenSpec change
support-non-asset-files(plus adversarial artifacts, comparison reviews, and task breakdown) so facet archives can carry explicitly declared supplementary files—not only skills, agents, and commands.The planned behavior relaxes outer exclusivity while keeping membership derivable from
facet.json: declared root files (e.g.README.md,LICENSE) and skill companions ship in the archive with per-entry and whole-archive integrity, but only skill-directory companions materialize on install; other supplementary bytes stay archive-only (no lockfile asset tuples or adapter installs).Breaking boundaries are spelled out:
facetVersion/ build-manifest0.2with a single all-entryfileshash map (legacy0.1still accepted), lockfile0.2with per-materialized-file integrity, a shared archive-plan for build and verification (path-safety and tar-entry checks), tagged adapter API0.1for atomic multi-file skill bundles, and receipt-owned companion paths for safe removal/drift.Authoring deltas include first-class README flows in create/edit, supplementary-file validation before
dist/cleanup, and a consumer-first rollout (verifiers/registry before producers). Implementation is deferred to the linked VIPER task list and doc updates across protocol, guides, and README.Reviewed by Cursor Bugbot for commit a17d95c. Bugbot is set up for automated code reviews on this repo. Configure here.
Summary by CodeRabbit