@rse/ase 0.9.62 → 0.9.64

package/plugin/skills/ase-sync-export/SKILL.md

@@ -1,17 +1,13 @@
 ---
 name: ase-sync-export
-argument-hint: "[--help|-h] [--source|-s <source>[,...]] [<hint>]"
+argument-hint: "[--help|-h] [--output|-o <output>[,...]]"
 description: >
-    Export artifact content into side-by-side, ready-to-consume files,
-    one per artifact that declares an export. Use when the user wants to
-    "export", "render", or "materialize" artifacts like SPEC or ARCH into
-    derived files such as diagrams or tables.
+    Export the SpecBook-based specification (SPEC) into ready-to-consume
+    renderings like HTML, PDF, normalized Markdown, or JSON. Use when the
+    user wants to "export", "render", or "materialize" the specification.
 user-invocable: true
 disable-model-invocation: false
 effort: xhigh
-allowed-tools:
-    - "Read"
-    - "Write"
 ---
 
 @${CLAUDE_SKILL_DIR}/../../meta/ase-control.md
@@ -19,174 +15,134 @@ allowed-tools:
 @${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md
 
 <purpose name="ase-sync-export">
-Export Artifact Set to Side-by-Side Files
+Export Specification into Rendered Files
 </purpose>
 
 <expand name="getopt"
     arg1="ase-sync-export"
-    arg2="--source|-s=SPEC,ARCH">
+    arg2="--output|-o=">
     $ARGUMENTS
 </expand>
 
 <objective>
-*Export* the *source* artifact kinds (optionally filtered by
-<hint/>) into side-by-side files, by reading the source artifacts
-and materializing, for every artifact that declares an export,
-the corresponding derived file next to the artifact itself.
-<hint><getopt-arguments/></hint>.
+*Export* the `SPEC` artifact set -- the SpecBook-based specification --
+into the requested output files, by validating the specification and
+rendering it through the SpecBook export.
 </objective>
 
 @${CLAUDE_SKILL_DIR}/../../meta/ase-format-meta.md
-@${CLAUDE_SKILL_DIR}/../../meta/ase-format-spec.md
-@${CLAUDE_SKILL_DIR}/../../meta/ase-format-arch.md
 
 Procedure
 ---------
 
 <flow>
 
-1.  <step id="STEP 1: Determine Source">
+1.  <step id="STEP 1: Determine Outputs">
 
-    1.  The recognized artifact kinds are the seven tokens `TASK`,
-        `SPEC`, `ARCH`, `CODE`, `DOCS`, `INFR`, and `OTHR`. Parse
-        <getopt-option-source/> as the comma-separated <source/> kind list.
-        Upper-case and trim every parsed kind token. Do not output
-        anything.
+    1.  Parse <getopt-option-output/> as the comma-separated <outputs/>
+        list of `[<format>:]<file>` entries, with <format/> one of
+        `json`, `json5`, `yaml`, `toon`, `html`, `pdf`, or `md`, and
+        <file/> a project-relative output file path. Trim every parsed
+        entry. Do not output anything.
 
-    2.  <if condition="<source/> is empty">
+    2.  <if condition="<outputs/> is empty">
 
-        Only output the following <template/> and then immediately *STOP*
-        processing the entire current skill:
-
-        <template>
-        ⧉ **ASE**: ☻ skill: **ase-sync-export**, ▶ ERROR: empty source artifact list
-        </template>
+        Determine the default output by calling the
+        `ase_artifact_name(filename: "index.html", kind: "spec")` tool
+        of the `ase` MCP server and set <outputs/> to the single entry
+        of its returned `name`. Do not output anything.
 
         </if>
 
-    3.  If any token in <source/> is *not* one of the seven recognized
-        kinds, only output the following <template/> (with <kind/> set to
-        the first offending token) and then immediately *STOP* processing
-        the entire current skill:
+    3.  If any entry in <outputs/> is `-` (the standard output sentinel),
+        only output the following <template/> and then immediately *STOP*
+        processing the entire current skill:
 
         <template>
-        ⧉ **ASE**: ☻ skill: **ase-sync-export**, ▶ ERROR: unknown artifact kind: **<kind/>**
+        ⧉ **ASE**: ☻ skill: **ase-sync-export**, ▶ ERROR: output `-` is not supported -- give an output file
         </template>
 
-    4.  Report the resolved source with the following <template/>:
+    4.  Report the resolved outputs with the following <template/>:
 
         <template>
-        <ase-tpl-bullet-signal/> **SOURCE**: <source/>
+        <ase-tpl-bullet-signal/> **OUTPUTS**: <outputs/>
         </template>
 
     </step>
 
-2.  <step id="STEP 2: Resolve and Read Artifacts">
+2.  <step id="STEP 2: Validate Specification">
 
-    1.  Do not output anything in this STEP 2.
+    1.  Call the `ase_specbook_lint()` tool of the `ase` MCP server
+        *once* and read its returned `diagnostics` array of `{ file,
+        line, column, message }` objects. Do not output anything.
 
-    2.  For all kinds in <source/> except `TASK`, call the
-        `ase_artifact_list(kind: [ ... ])` tool of the `ase` MCP server
-        *once*, passing the lower-cased `kind` tokens, and read the
-        returned `artifacts` array of `{ kind, files }` objects to obtain
-        the project-relative file list per kind. The `TASK` kind is *not*
-        resolvable via `ase_artifact_list` (task plans are managed by the
-        `ase_task_*` tools) and declares no export, so *silently skip* it.
+    2.  <if condition="<diagnostics/> is not empty">
 
-    3.  <if condition="<hint/> is not empty">
+        Only output the following <template/> (listing one bullet line
+        per diagnostic), give the closing hint by expanding the
+        `<ase-tpl-hint/>` below it, and then immediately *STOP*
+        processing the entire current skill:
 
-        Honor the filtering <hint/> to reduce the source artifacts
-        and/or the aspects of those artifacts you should take into
-        account.
+        <template>
+        ⧉ **ASE**: ☻ skill: **ase-sync-export**, ▶ ERROR: specification invalid -- nothing exported
 
-        </if>
+        -   `<file/>:<line/>:<column/>`: <message/>
+        [...]
+        </template>
 
-    4.  Internalize and honor the artifact-format conventions:
+        <ase-tpl-hint level="minimal">
+        Fix the reported diagnostics in the `SPEC` artifacts (e.g. via `/ase-sync-reconcile -t SPEC`), then re-run this skill.
+        </ase-tpl-hint>
 
-        -   the artifact-set/artifact/aspect/export meta information (`ase-format-meta.md`),
-        -   the `SPEC` format (`ase-format-spec.md`),
-        -   the `ARCH` format (`ase-format-arch.md`).
+        </if>
 
-        In particular, internalize the generic *Artifact Export*
-        contract of `ase-format-meta.md` (the `-   Export:` bullet, the
-        side-by-side file-name convention, and the rule that an artifact
-        without an `-   Export:` bullet is *not* exported), and which
-        artifacts declare an export in the `SPEC` and `ARCH` formats.
+    </step>
 
-    5.  Read all resolved source artifacts and build a precise
-        understanding of the content of each artifact that declares an
-        export.
+3.  <step id="STEP 3: Export Specification">
 
-    </step>
+    1.  For *each* <output/> in <outputs/>, call the
+        `ase_specbook_export(output: "<output/>")` tool of the `ase` MCP
+        server, which infers the format from the `[<format>:]<file>`
+        entry, writes the rendering to the file, and returns a
+        confirmation `text` carrying the written byte size plus a
+        `notices` array of environment notices. Set <notices/> to the
+        *distinct* notices of all calls. Do not output anything.
 
-3.  <step id="STEP 3: Materialize Exports">
-
-    1.  For *each* read source artifact that declares an `-   Export:`
-        bullet in its format definition, *materialize* the declared
-        export:
-
-        -   *Build* the derived rendering exactly as described by the
-            artifact's <export-transform/>, faithfully reflecting the
-            artifact's current content -- no more, no less. Honor **No
-            Fabrication**: never invent content the artifact does not
-            support.
-
-        -   For an export whose <export-transform/> is a *Mermaid
-            diagram converted to SVG*, build the Mermaid specification
-            from the artifact content and render it to an SVG document by
-            calling the `ase_diagram(diagram: "<mermaid-spec/>", format:
-            "svg")` tool of the `ase` MCP server, using its `text` output
-            field as the SVG document. For a textual export (e.g. a
-            Markdown table), build the content directly. For Markdown
-            *tables*, honor the table-alignment rule of `ase-skill.md`.
-
-        -   *Determine* the side-by-side target file name
-            <export-filename/>
-            as `<artifact-set-id/>-<artifact-no/>-<artifact-id/>-<artifact-slug/>-<export-name/>.<export-ext/>`
-            and resolve it to a project-relative path inside the
-            artifact's own base directory (`<basedir/>`) by calling the
-            `ase_artifact_name(filename: "<export-filename/>", kind:
-            "<artifact-kind/>")` tool of the `ase` MCP server, with
-            <artifact-kind/> the artifact's own lower-cased kind.
-
-        -   *Write* the derived rendering to that resolved path via the
-            `Write` tool, overwriting any pre-existing export file of the
-            same name.
-
-    2.  Report the materialized exports with the following <template/>,
+    2.  Report the exported files with the following <template/>,
         listing one bullet line per written file (with <file/> its
-        project-relative path and <note/> an ultra-brief description of
-        what was exported):
+        project-relative path and <note/> the format and the byte size):
 
         <template>
-        <ase-tpl-bullet-signal/> **EXPORTED ARTIFACTS**:
+        <ase-tpl-bullet-signal/> **EXPORTED SPECIFICATION**:
 
         -   `<file/>`: <note/>
         [...]
         </template>
 
-        <if condition="no source artifact declares an export">
+    3.  <if condition="<notices/> is not empty">
 
-        Only output the following <template/>:
+        Report the environment notices *verbatim* with the following
+        <template/>, listing one bullet line per notice:
 
         <template>
-        <ase-tpl-bullet-normal/> **EXPORTED ARTIFACTS**: none -- no source artifact declares an export
+        <ase-tpl-bullet-signal/> **ENVIRONMENT NOTICES**:
+
+        -   <notice/>
+        [...]
         </template>
 
         </if>
 
-    3.  Finally, give the closing hints by expanding the following
+    4.  Finally, give the closing hints by expanding the following
         (which, depending on the configured <ase-guidance-level/>, may
         each expand into nothing and hence emit no output at all):
 
-        <if condition="at least one export file was written">
         <ase-tpl-hint level="normal">
-        Exports are *derived* and go stale as their source artifacts drift -- use `/ase-sync-reconcile` to align the artifacts first, then re-run this skill.
+        Exports are *derived* and go stale as the specification drifts -- use `/ase-sync-reconcile` to align the artifacts first, then re-run this skill.
         </ase-tpl-hint>
-        </if>
 
         <ase-tpl-hint level="verbose">
-        Use `/ase-sync-export --source` to narrow the exported artifact kinds, and a trailing filtering hint to narrow the exports themselves.
+        Use `/ase-sync-export --output` with a comma-separated list of `[<format>:]<file>` entries to export several renderings at once (e.g. `-o docs/spec.html,docs/spec.pdf`).
         </ase-tpl-hint>
 
     </step>

package/plugin/skills/ase-sync-export/help.md

@@ -1,73 +1,76 @@
 
 ##  NAME
 
-`ase-sync-export` - Export Artifact Set to Side-by-Side Files
+`ase-sync-export` - Export Specification into Rendered Files
 
 ##  SYNOPSIS
 
 `ase-sync-export`
     [`--help`|`-h`]
-    [`--source`|`-s` *source*[,...]]
-    [*filter*]
+    [`--output`|`-o` *output*[,...]]
 
 ##  DESCRIPTION
 
-The `ase-sync-export` skill exports the content of a set of artifact
-kinds (the *source*) into *derived*, ready-to-consume files placed
-*side-by-side* with the artifacts themselves. For every source artifact
-that declares an *export* in its format definition, the skill builds the
-declared rendering and writes it to a sibling file.
-
-The *source* is a comma-separated list over the seven recognized
-artifact kinds `SPEC` (Specification), `ARCH` (Architecture), `CODE`
-(Source Code), `DOCS` (Documentation), `TASK` (Task Plans), `INFR`
-(Infrastructure), and `OTHR` (catch-all). The file lists for the
-involved kinds are resolved via the `ase_artifact_list` MCP tool of the
-`ase` MCP server.
-
-An *export* is declared by a `-   Export:` bullet point in an artifact's
-format definition (see `ase-format-meta.md`, `ase-format-spec.md`, and
-`ase-format-arch.md`); an artifact *without* such a bullet is *not*
-exported. Each exported file is named
-`<set>-<no>-<id>-<slug>-<export-name>.<ext>` (e.g.
-`SPEC-07-DM-Data-Model-export.svg`) and stored in the artifact's own
-base directory. Initially, the *Data Model* (`SPEC-DM`) exports as a
-Mermaid UML diagram converted to SVG, and the *Technology Stack*
-(`ARCH-TS`) exports as a compact Markdown table.
+The `ase-sync-export` skill exports the `SPEC` artifact set -- the
+*SpecBook*-based specification of the project, located via the
+`project.artifact.spec.basedir` configuration -- into *derived*,
+ready-to-consume renderings. The specification is first validated
+against the SpecBook schema configuration via the `ase_specbook_lint`
+MCP tool of the `ase` MCP server; on any diagnostic the skill errors out
+and exports nothing, as a partial or invalid specification must never be
+rendered. Otherwise every requested *output* is rendered via the
+`ase_specbook_export` MCP tool.
+
+Each *output* is an `[<format>:]<file>` entry, where the format is one
+of `json`, `json5`, `yaml`, `toon` (the specification object model),
+`html` (self-contained single document with table of contents, full-text
+search, and light/dark theme), `pdf` (paginated print document), or `md`
+(normalized single Markdown document). The format is inferred from the
+filename extension unless it is explicitly given as a prefix. The
+standard output sentinel `-` is not supported.
+
+The `pdf` format is the only one with an external prerequisite: it
+prints the rendering through a Chromium-class browser. Neither `npm
+install -g @rse/ase` nor `ase setup install` downloads one, so unless a
+*Google Chrome* is installed system-wide, the Playwright Chromium has to
+be fetched once via `npx playwright install chromium`. Without any such
+browser the export fails up-front, before the specification is parsed,
+and reports that very command; when it falls back onto a system-installed
+*Google Chrome*, the skill reports this as an environment notice.
 
 ##  OPTIONS
 
-`--source`|`-s` *source*[,...]:
-    The comma-separated list of artifact kinds to export. Defaults to
-    `SPEC,ARCH` (the skill errors out on an empty source).
+`--output`|`-o` *output*[,...]:
+    The comma-separated list of `[<format>:]<file>` entries to render,
+    with each file path relative to the project root. Defaults to the
+    single HTML rendering `index.html` inside the `SPEC` base directory
+    (e.g. `docs/specbook/index.html`).
 
-##  ARGUMENTS
+##  SCENARIOS
 
-*filter*:
-    An optional free-form filtering hint that narrows the source
-    artifacts, or the aspects of those artifacts, to take into account
-    when materializing the exports. If omitted, every export declared by
-    a source artifact is materialized.
+-   You want the specification rendered as HTML, PDF, Markdown, or JSON
+-   You want a shareable, ready-to-consume export of the `SPEC` artifacts
+-   You want the specification validated and then materialized into files
 
 ##  EXAMPLES
 
-Export the specification and architecture artifacts to their
-side-by-side files (the default):
+Export the specification to its default HTML rendering:
 
 ```text
 ❯ /ase-sync-export
 ```
 
-Export only the specification artifacts:
+Export the specification as HTML and PDF:
 
 ```text
-❯ /ase-sync-export -s SPEC
+❯ /ase-sync-export -o docs/spec.html,docs/spec.pdf
 ```
 
-Export only the data-model artifact:
+Export the specification object model as YAML into a file without a
+telling extension:
 
 ```text
-❯ /ase-sync-export -s SPEC data model
+❯ /ase-sync-export -o yaml:docs/spec.model
 ```
 
 ##  SEE ALSO

package/plugin/skills/ase-sync-import/SKILL.md

@@ -6,7 +6,7 @@ description: >
     (the target), generating or updating them to reflect the imported
     information. Use when the user wants to "import", "ingest", or
     "bring in" external sources like files, URLs, or pasted text into
-    artifacts like SPEC, ARCH, CODE, DOCS, TASK, INFR, or OTHR.
+    artifacts like SPEC, CODE, DOCS, TASK, INFR, or OTHR.
 user-invocable: true
 disable-model-invocation: false
 effort: xhigh
@@ -22,7 +22,7 @@ Import Foreign Sources into Artifact Set
 
 <expand name="getopt"
     arg1="ase-sync-import"
-    arg2="--target|-t=SPEC,ARCH">
+    arg2="--target|-t=SPEC">
     $ARGUMENTS
 </expand>
 
@@ -36,7 +36,6 @@ reflect the imported information:
 
 @${CLAUDE_SKILL_DIR}/../../meta/ase-format-meta.md
 @${CLAUDE_SKILL_DIR}/../../meta/ase-format-spec.md
-@${CLAUDE_SKILL_DIR}/../../meta/ase-format-arch.md
 @${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md
 @${CLAUDE_SKILL_DIR}/../../meta/ase-tenets.md
 
@@ -47,8 +46,8 @@ Procedure
 
 1.  <step id="STEP 1: Determine Target">
 
-    1.  The recognized artifact kinds are the seven tokens `TASK`,
-        `SPEC`, `ARCH`, `CODE`, `DOCS`, `INFR`, and `OTHR`. Parse
+    1.  The recognized artifact kinds are the six tokens `TASK`,
+        `SPEC`, `CODE`, `DOCS`, `INFR`, and `OTHR`. Parse
         <getopt-option-target/> as the comma-separated <target/> kind list.
         Upper-case and trim every parsed kind token. Do not output
         anything.
@@ -64,7 +63,7 @@ Procedure
 
         </if>
 
-    3.  If any token in <target/> is *not* one of the seven recognized
+    3.  If any token in <target/> is *not* one of the six recognized
         kinds, only output the following <template/> (with <kind/> set to
         the first offending token) and then immediately *STOP* processing
         the entire current skill:
@@ -123,16 +122,18 @@ Procedure
 
     2.  Internalize and honor the artifact-format conventions:
 
-        -   the artifact-set/artifact/aspect meta information (`ase-format-meta.md`),
-        -   the `SPEC` format (`ase-format-spec.md`),
-        -   the `ARCH` format (`ase-format-arch.md`),
+        -   the artifact-set meta information (`ase-format-meta.md`),
+        -   the `SPEC` format, i.e. the SpecBook models and formats plus
+            the SpecBook schema configuration of the project
+            (`ase-format-spec.md`),
         -   the `TASK` format (`ase-format-task.md`).
 
         Whenever a target artifact belongs to one of these kinds, it
         *MUST* be kept (or made) conformant to the corresponding format
-        (headings, structure, identifiers, and the `<timestamp-modified/>`
-        rule). The kinds `CODE`, `DOCS`, `INFR`, and `OTHR` have no
-        dedicated format contract and are treated as free-form.
+        (headings, structure, identifiers, references, and the
+        `Modified:` timestamp rule). The kinds `CODE`, `DOCS`, `INFR`,
+        and `OTHR` have no dedicated format contract and are treated as
+        free-form.
 
     3.  You *MUST* internalize and strictly honor the **GENERIC TENETS**,
         the **CRAFTING TENETS**, and the **RECONCILIATION TENETS** of the
@@ -163,14 +164,35 @@ Procedure
         sources do not support; if the sources are silent or ambiguous on
         something the target needs, surface the gap rather than guessing.
         Re-express the imported facts at the *target's* level of
-        abstraction (a SPEC states intent, an ARCH states structure).
+        abstraction (a SPEC states intent and structure).
 
         Apply the generation/update directly to the target artifacts via
         the `Write`/`Edit` tools. For a `TASK` target, apply it via the
         `ase_task_save` MCP tool instead -- *NEVER* write a task plan
         file via `Write`/`Edit` or by executing a shell command.
 
-    6.  Report the performed changes with the following <template/>, listing
+    6.  <if condition="at least one `SPEC` artifact was generated or updated">
+
+        Validate the specification by calling the `ase_specbook_lint()`
+        tool of the `ase` MCP server and reading its returned
+        `diagnostics` array of `{ file, line, column, message }`
+        objects. If it is not empty, fix the reported problems in the
+        affected `SPEC` artifacts via the `Write`/`Edit` tools and call
+        the tool again -- for at most *three* rounds in total. Do not
+        output anything, unless diagnostics remain after the last round,
+        in which case output the following <template/>, listing one
+        bullet line per remaining diagnostic:
+
+        <template>
+        <ase-tpl-bullet-signal/> **REMAINING DIAGNOSTICS**:
+
+        -   `<file/>:<line/>:<column/>`: <message/>
+        [...]
+        </template>
+
+        </if>
+
+    7.  Report the performed changes with the following <template/>, listing
         one bullet line per generated or updated file (with <file/> its
         project-relative path and <note/> an ultra-brief description of
         what was imported):
@@ -192,7 +214,7 @@ Procedure
 
         </if>
 
-    7.  Finally, give the closing hint by expanding the following (which,
+    8.  Finally, give the closing hint by expanding the following (which,
         depending on the configured <ase-guidance-level/>, may expand
         into nothing and hence emit no output at all):
 

package/plugin/skills/ase-sync-import/help.md

@@ -24,26 +24,30 @@ be local files or directories, remote URLs, pasted text passages, or
 references to other documents. Local files are read via the `Read` tool
 and remote URLs are fetched via the available web tools.
 
-The *target* is a comma-separated list over the seven recognized
-artifact kinds `SPEC` (Specification), `ARCH` (Architecture), `CODE`
-(Source Code), `DOCS` (Documentation), `TASK` (Task Plans), `INFR`
-(Infrastructure), and `OTHR` (catch-all). It defaults to `SPEC,ARCH`.
-The file lists for the involved kinds are resolved via the
-`ase_artifact_list` MCP tool of the `ase` MCP server.
+The *target* is a comma-separated list over the six recognized
+artifact kinds `SPEC` (Specification, covering both requirements and
+architecture), `CODE` (Source Code), `DOCS` (Documentation), `TASK`
+(Task Plans), `INFR` (Infrastructure), and `OTHR` (catch-all). It
+defaults to `SPEC`. The file lists for the involved kinds are resolved
+via the `ase_artifact_list` MCP tool of the `ase` MCP server.
 
 While importing, the skill honors the artifact-format conventions of
-`ase-format-meta.md`, `ase-format-spec.md`, `ase-format-arch.md`, and
+`ase-format-meta.md`, `ase-format-spec.md` (the *SpecBook* models and
+formats plus the SpecBook schema configuration), and
 `ase-format-task.md`; the kinds `CODE`, `DOCS`, `INFR`, and `OTHR` have
 no dedicated format contract and are treated as free-form. A target
 artifact that does not yet exist but is warranted by the imported
 information is *generated* from scratch, while an existing target
 artifact is *surgically updated* to reflect the imported information.
+Generated or updated `SPEC` artifacts are validated via the
+`ase_specbook_lint` MCP tool and the reported diagnostics are fixed in
+at most three rounds; any remaining diagnostics are surfaced.
 
 ##  OPTIONS
 
 `--target`|`-t` *target*[,...]:
     The comma-separated list of artifact kinds to generate or update.
-    Defaults to `SPEC,ARCH`. The skill errors out on an empty target or
+    Defaults to `SPEC`. The skill errors out on an empty target or
     an unknown/unsupported kind.
 
 ##  ARGUMENTS
@@ -53,6 +57,13 @@ artifact is *surgically updated* to reflect the imported information.
     from (e.g. a file path, directory, URL, or pasted text). The skill
     errors out on an empty hint.
 
+##  SCENARIOS
+
+-   You want external sources brought into the project artifacts
+-   You want a foreign document, URL, or pasted text reflected in the `SPEC`
+-   You want requirements from outside imported into a task plan
+-   You want legacy material ingested into the specification
+
 ##  EXAMPLES
 
 Import a foreign requirements document into the specification:
@@ -61,8 +72,8 @@ Import a foreign requirements document into the specification:
 ❯ /ase-sync-import -t SPEC docs/legacy/requirements.txt
 ```
 
-Import an external design write-up into the architecture, defaulting to
-both specification and architecture as targets:
+Import an external design write-up into the specification (the default
+target), which covers the architecture, too:
 
 ```text
 ❯ /ase-sync-import https://example.com/design-notes.html