Bump @julian/openspec-adversary to 2.3.0 and add add-facet-visibility-to-manifest specs, tasks, and adversarial review artifacts

Author: eXamadeus

facets.json

@@ -3,6 +3,6 @@
     "viper-plans": "0.2.0",
     "cowsay": "0.2.0",
     "@julian/review-openspec-design": "1.1.0",
-    "@julian/openspec-adversary": "2.2.1"
+    "@julian/openspec-adversary": "2.3.0"
   }
 }

facets.lock

@@ -6,8 +6,8 @@
         "kind": "registry",
         "registry": "https://api.facet.cafe"
       },
-      "version": "2.2.1",
-      "integrity": "sha256:c89f3a38e0deade748ab63c6e8d74ae65eee717fa2ccd8cc69ebca96c0caf189",
+      "version": "2.3.0",
+      "integrity": "sha256:12f91506d77467081816cd89412828df91a25d2de2ab897803a7dbc468dc1c1b",
       "assets": [
         {
           "scope": "project",
@@ -27,7 +27,7 @@
         {
           "scope": "project",
           "type": "agent",
-          "name": "opencode-adversary"
+          "name": "openspec-adversary"
         },
         {
           "scope": "project",

openspec/changes/add-facet-visibility-to-manifest/adversarial/artifacts/specs/authoring__facets/spec.md

@@ -0,0 +1,157 @@
+## MODIFIED Requirements
+
+### 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 (skills, agents, commands, or composed facets). The name SHALL be either an unscoped kebab-case facet identity (`name`) or a scoped facet identity (`@scope/name`). All three text asset types — skills, agents, and commands — use the same descriptor model: a map of asset name to a descriptor with a required description and optional platform metadata. Descriptors SHALL NOT contain prompt references — prompt content is inferred from the file-path convention. Skills use the Agent Skills directory convention `skills/<name>/SKILL.md`. Agents and commands use the flat file convention `agents/<name>.md` and `commands/<name>.md` respectively. All three descriptor types SHALL require a `description` field. Asset names SHALL remain local kebab-case identifiers and SHALL NOT be scoped facet identities.
+
+The system SHALL accept and preserve an optional top-level `private` boolean in a valid manifest. `private: true` SHALL identify that the author intends the facet to be private when published. `private: false` and omission SHALL preserve public-by-default behavior for existing projects.
+
+#### Scenario: Minimal valid manifest with a skill
+
+- **WHEN** an author provides a manifest with a name, version, and a single skill descriptor that includes a description
+- **THEN** the system SHALL accept the manifest
+
+#### Scenario: Valid manifest with a scoped facet identity
+
+- **WHEN** an author provides a manifest whose `name` is `@julian/cowsay`, with a version and a single skill descriptor that includes a description
+- **THEN** the system SHALL accept the manifest
+
+#### Scenario: Manifest with all sections
+
+- **WHEN** an author provides a manifest with identity fields, skill descriptors with descriptions, agent descriptors with descriptions, command descriptors with descriptions, composed facets, and server references
+- **THEN** the system SHALL accept the manifest
+
+#### Scenario: Manifest with only composed facets is valid
+
+- **WHEN** an author provides a manifest with `name`, `version`, and a `facets` section but no local skills, agents, or commands
+- **THEN** the system SHALL accept the manifest
+
+#### Scenario: Private manifest is accepted and preserved
+
+- **WHEN** an author provides a valid manifest containing `private: true`
+- **THEN** the system SHALL accept the manifest
+- **AND** the loaded manifest data SHALL preserve `private: true`
+
+#### Scenario: Public-by-default manifests remain valid
+
+- **WHEN** an author provides a valid manifest with `private` omitted or set to `false`
+- **THEN** the system SHALL accept the manifest
+- **AND** downstream tooling SHALL interpret the manifest as public for publishing intent
+
+### Requirement: Invalid facet manifests are rejected with actionable errors
+
+The system SHALL reject a facet manifest that does not conform to the manifest schema. Each error SHALL identify the location of the problem (field path) and describe what was expected, so the author can fix it without guessing.
+
+#### Scenario: Missing required identity field
+
+- **WHEN** an author provides a manifest without a `name` or `version` field
+- **THEN** the system SHALL reject the manifest
+- **AND** the error SHALL identify which required field is missing
+
+#### Scenario: No text assets
+
+- **WHEN** an author provides a manifest with identity fields and server references but no skills, agents, commands, or composed facets
+- **THEN** the system SHALL reject the manifest
+- **AND** the error SHALL indicate that at least one text asset is required
+
+#### Scenario: Agent missing its description
+
+- **WHEN** an author defines an agent without a `description` field
+- **THEN** the system SHALL reject the manifest
+- **AND** the error SHALL identify the agent by name and the missing field
+
+#### Scenario: Selective facets entry with no asset selection
+
+- **WHEN** an author writes a selective facets entry with `name` and `version` but no `skills`, `agents`, or `commands`
+- **THEN** the system SHALL reject the manifest
+- **AND** the error SHALL indicate that at least one asset type must be selected
+
+#### Scenario: Server reference object without image field
+
+- **WHEN** an author writes a server reference as an object but omits the `image` field
+- **THEN** the system SHALL reject the manifest
+- **AND** the error SHALL identify the server by name
+
+#### Scenario: Non-boolean privacy declaration
+
+- **WHEN** an author provides a manifest whose top-level `private` field is not a boolean
+- **THEN** the system SHALL reject the manifest
+- **AND** the error SHALL identify `private` and state that a boolean value was expected
+
+### Requirement: Authors can build a facet locally for validation and inspection
+
+The system SHALL compile a facet project into a build output directory. The build command SHALL read the manifest, validate it, verify that every declared asset file exists, is non-empty, and contains no YAML front matter, resolve all file-based prompts to their content, run all validation checks, assemble the resolved output into a deterministic compressed archive, compute content hashes, and write the archive and build manifest to a `dist/` directory. The build command SHALL NOT modify the manifest or any content files. The build command SHALL NOT be interactive — it SHALL behave identically in all environments.
+
+The build output SHALL contain a compressed archive (`.facet` file) with the manifest and all text asset files with prompts resolved to their final string content, and a build manifest (`build-manifest.json`) recording content hashes. If the source manifest contains `private`, the embedded manifest in the archive SHALL contain the same boolean value. If the source manifest omits `private`, the build output SHALL preserve omission and SHALL NOT inject a default field. For a scoped facet identity, whose name renders as a nested path under `dist/`, the system SHALL create any required parent directories under `dist/` before writing the built archive. The build-output write boundary SHALL create parent directories for any slash-containing archive path, so the same fix also repairs the pre-existing failure for any nested archive filename.
+
+The build command SHALL render its progress as a step-by-step display, showing each pipeline stage as it completes — including the archive assembly stage. On success, the system SHALL display the archive contents listing and the archive content hash. On failure, the system SHALL indicate which stage failed and display errors with their field paths, and SHALL suggest running the editing command to fix the issues. After the display exits, the system SHALL print a brief plain-text summary to stdout — including the content hash — so it persists in terminal scroll-back.
+
+#### Scenario: Successful build of a valid facet
+
+- **WHEN** the author runs the build command in a directory with a valid manifest, all referenced files exist, and no files contain front matter
+- **THEN** the system SHALL write a compressed archive and build manifest to `dist/`
+- **AND** the archive SHALL contain the facet manifest and all text asset files with prompts resolved to their string content
+- **AND** the build manifest SHALL contain the archive content hash and per-asset content hashes
+- **AND** the system SHALL display the archive contents and content hash
+- **AND** the system SHALL print a brief success summary to stdout including the content hash
+
+#### Scenario: Successful build preserves private publishing intent
+
+- **WHEN** the author runs the build command for a valid manifest containing `private: true`
+- **THEN** the built archive SHALL contain an embedded manifest with `private: true`
+- **AND** verification of the built archive SHALL treat that value as part of the manifest content
+
+#### Scenario: Successful build preserves public-by-default omission
+
+- **WHEN** the author runs the build command for a valid manifest that omits `private`
+- **THEN** the built archive SHALL contain an embedded manifest with `private` omitted
+- **AND** the archive SHALL remain publishable as a public facet when all other requirements are satisfied
+
+#### Scenario: Successful build of a scoped facet identity
+
+- **WHEN** the author runs the build command for a valid facet whose name is `@julian/cowsay`
+- **THEN** the system SHALL write the built archive under `dist/` without failing on the scoped name separator
+- **AND** the archive SHALL contain `facet.json` at the archive root with `name` set to `@julian/cowsay`
+- **AND** the archive's internal asset paths SHALL continue to be derived from asset names, not from the facet identity
+
+#### Scenario: Build-output write boundary creates parent directories for a nested archive path
+
+- **WHEN** the build-output write boundary writes an archive whose filename renders as a nested path under `dist/` (for example a scoped `@scope/name` identity, or any other slash-containing archive filename)
+- **THEN** the system SHALL create the required parent directories under `dist/` before writing the archive
+- **AND** the write SHALL NOT fail with a missing-directory error
+
+#### Scenario: Build fails on invalid manifest
+
+- **WHEN** the author runs the build command and the manifest fails schema validation
+- **THEN** the system SHALL report the validation errors with field paths
+- **AND** the system SHALL suggest running the editing command to fix the issues
+- **AND** the system SHALL NOT write any output to `dist/`
+
+#### Scenario: Build fails on missing asset file
+
+- **WHEN** the author runs the build command and any asset references a file that does not exist
+- **THEN** the system SHALL report which file is missing and which asset references it
+- **AND** the system SHALL suggest running the editing command to fix the issues
+- **AND** the system SHALL NOT write any output to `dist/`
+
+#### Scenario: Build fails on file containing front matter
+
+- **WHEN** the build command encounters a content file containing YAML front matter
+- **THEN** the build SHALL fail with an error identifying the file and indicating that front matter must be removed
+
+#### Scenario: Build fails on empty content file
+
+- **WHEN** the author runs the build command and a content file referenced by the manifest is empty (zero bytes or only whitespace)
+- **THEN** the system SHALL report which file is empty and which asset references it
+- **AND** the system SHALL suggest running the editing command to add content
+- **AND** the system SHALL NOT write any output to `dist/`
+
+#### Scenario: Build with no manifest
+
+- **WHEN** the author runs the build command in a directory with no manifest
+- **THEN** the system SHALL report that no manifest was found
+
+#### Scenario: Build cleans previous output
+
+- **WHEN** the author runs the build command and a `dist/` directory already exists from a previous build
+- **THEN** the system SHALL remove the previous `dist/` directory before writing new output

openspec/changes/add-facet-visibility-to-manifest/adversarial/artifacts/specs/protocol__schemas/spec.md

@@ -0,0 +1,72 @@
+## MODIFIED Requirements
+
+### Requirement: A facet manifest schema is published as part of the protocol
+
+The shape of a facet manifest (`facet.json`) SHALL be published as a normative schema. Any system that produces a facet manifest SHALL produce one conforming to the published schema. Any system that consumes a facet manifest SHALL validate it against the published schema before treating any value as trusted. The schema SHALL define the required fields, the permitted shapes for skills/agents/commands, the accepted facet identity grammar, the optional privacy declaration, and the rules for unrecognized fields.
+
+A facet identity name SHALL be either an unscoped name (`<slug>`) or a scoped name (`@<scope>/<slug>`). Each `slug` and `scope` component SHALL satisfy the same component grammar: it MUST be at least 2 characters and at most 64 characters, MUST start with a lowercase ASCII letter, MUST end with a lowercase ASCII letter or ASCII digit, MUST contain only lowercase ASCII letters, ASCII digits, and hyphens, and MUST NOT contain consecutive hyphens. Uppercase letters, non-ASCII characters, underscores, dots, spaces, plus signs, tildes, emoji, and any other character outside the component grammar SHALL be rejected rather than normalized. A facet manifest whose `name` is malformed SHALL be rejected as invalid. Asset names SHALL remain independently validated as local asset identifiers and SHALL NOT become scoped names.
+
+The facet manifest schema SHALL define an optional top-level `private` field. When present, `private` SHALL be a boolean. `private: true` SHALL declare that the author intends the facet to be published as private. `private: false` and an omitted `private` field SHALL both declare the default public publishing intent. Values of any non-boolean type SHALL be rejected rather than treated as unknown extension data or coerced to booleans.
+
+The facet manifest schema SHALL NOT document unsupported composition or server-reference fields as part of the current user-facing manifest contract. Current user-facing manifest documentation SHALL describe only supported manifest behavior and SHALL use the manifest specification page as the canonical place for facet-name grammar and manifest privacy semantics.
+
+#### Scenario: A producer emits a manifest conforming to the published schema
+
+- **WHEN** a system produces a `facet.json` for distribution
+- **THEN** the produced manifest SHALL satisfy every requirement of the published schema
+- **AND** another facet-compatible system SHALL accept the manifest after validating it
+
+#### Scenario: A consumer accepts valid unscoped facet identities
+
+- **WHEN** a system receives a `facet.json` whose `name` is `ab`, `cowsay`, `julian`, `admin-tester`, `apple-b34r`, or `f-o-s-s-o`
+- **THEN** the system SHALL accept the facet identity as valid
+- **AND** the accepted identity SHALL remain the facet's canonical name without normalization
+
+#### Scenario: A consumer accepts a valid scoped facet identity
+
+- **WHEN** a system receives a `facet.json` whose `name` is `@julian/cowsay`
+- **THEN** the system SHALL accept the facet identity as valid
+- **AND** both scoped identity components SHALL satisfy the same component grammar as unscoped facet names
+- **AND** the scoped identity SHALL remain the facet's canonical name
+
+#### Scenario: A consumer accepts a private publishing declaration
+
+- **WHEN** a system receives a `facet.json` containing `private: true`
+- **THEN** the system SHALL accept the privacy declaration as schema-valid
+- **AND** the validated manifest SHALL preserve `private: true` as the facet's publishing intent
+
+#### Scenario: A consumer accepts public-by-default manifests
+
+- **WHEN** a system receives a `facet.json` where `private` is omitted or set to `false`
+- **THEN** the system SHALL accept the manifest as schema-valid when all other schema requirements are satisfied
+- **AND** the manifest SHALL be interpreted as public for publishing intent
+
+#### Scenario: A consumer rejects invalid slug components
+
+- **WHEN** a system receives a `facet.json` whose `name` is empty, `a`, `z`, `A`, `Cowsay`, `1abc`, `-abc`, `abc-`, `abc--def`, `abc_def`, `abc.def`, `abc def`, `éclair`, `gооgle` with Cyrillic homoglyphs, or any component longer than 64 characters
+- **THEN** the system SHALL reject the manifest as invalid
+- **AND** the system SHALL surface a structured error indicating that the facet identity is malformed
+
+#### Scenario: A consumer rejects malformed scoped facet identities
+
+- **WHEN** a system receives a `facet.json` whose `name` is `@scope`, `@/name`, `@scope/`, `@scope/name/extra`, or `scope/name`
+- **THEN** the system SHALL reject the manifest as invalid
+- **AND** the system SHALL surface a structured error indicating that the facet identity is malformed
+
+#### Scenario: A consumer rejects a non-boolean privacy declaration
+
+- **WHEN** a system receives a `facet.json` whose `private` field is a string, number, object, array, or null
+- **THEN** the system SHALL reject the manifest as invalid
+- **AND** the system SHALL surface a structured error indicating that `private` must be a boolean
+
+#### Scenario: A consumer rejects a manifest that violates the published schema
+
+- **WHEN** a system receives a `facet.json` that omits a required field or contains a field with the wrong type
+- **THEN** the system SHALL reject the manifest as invalid
+- **AND** the system SHALL surface a structured error indicating which constraint was violated
+
+#### Scenario: A consumer tolerates unrecognized fields
+
+- **WHEN** a system receives a `facet.json` containing a field not defined in the schema
+- **THEN** the system SHALL accept the manifest as valid
+- **AND** the system SHALL preserve the unknown field if it later re-emits the manifest