opsx-gherkin 2.0.0 → 2.0.2

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.0.2](https://github.com/aquine-kujaruk/opsx-gherkin/compare/v2.0.1...v2.0.2) (2026-10-22)
+
+
+### Bug Fixes
+
+* **skill:** update SKILL.md to clarify Gherkin table formatting and conversion requirements ([377026d](https://github.com/aquine-kujaruk/opsx-gherkin/commit/377026dea6a581beeba23cdbebded59e505555db))
+
+## [2.0.1](https://github.com/aquine-kujaruk/opsx-gherkin/compare/v2.0.0...v2.0.1) (2026-10-21)
+
+
+### Bug Fixes
+
+* **skill:** state that inline step comments are preserved step text ([7e49eae](https://github.com/aquine-kujaruk/opsx-gherkin/commit/7e49eae1fe3beb7049f7817ce84309e216ea1745))
+
 # [2.0.0](https://github.com/aquine-kujaruk/opsx-gherkin/compare/v1.0.1...v2.0.0) (2026-10-20)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opsx-gherkin",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Deterministic OpenSpec and Gherkin conversion with a self-contained syntax compatibility skill.",
   "repository": {
     "type": "git",

package/skills/opsx-gherkin/SKILL.md

@@ -69,6 +69,8 @@ These examples apply the canonical contract to their own domains.
   and none is required: a new document may omit them, but conversion preserves
   every supplied tag unchanged. Authoring conventions do not narrow syntax
   acceptance.
+- An HTML comment at the end of a step is step text: every conversion
+  preserves it verbatim, and it has no meaning to the converter.
 - In MDG, put each tag in its own backtick span immediately above the tagged
   heading. In native Gherkin, use bare tags. Reserve `@openspec-*` and `@mdg-*`
   names for the structural roles defined by the contract.
@@ -88,6 +90,12 @@ Examples cases or Data Table values. Use `\|` for a literal pipe, `\\` for a
 literal backslash, and `\n` for a newline inside a cell. Do not apply cell
 escaping to Doc Strings.
 
+A Markdown table is a Gherkin table only while every row keeps its two-space
+indentation. A project Markdown formatter, such as oxfmt or prettier, removes it,
+and conversion then fails with `Examples "<heading>" has no table`, while
+`validate-spec --format openspec` can still accept the file. Exclude
+`openspec/**` from formatting before the first conversion.
+
 Keep a Markdown Doc String in a triple-backtick block indented by two spaces
 under its step; put its optional media type immediately after the opening fence.
 Preserve the content's indentation relative to the fence. In an outline, each
@@ -96,16 +104,26 @@ verify the expanded cases.
 
 ## Convert and verify
 
-Each converter accepts one path, `--text`, or stdin. Use stdout to inspect a
-result; use `-o <destination>` for an explicit output file. Existing outputs
-require `--force`. Respect the user's destination and overwrite intent.
+When an OpenSpec spec exists, it is the source. A Gherkin rendering of it
+(`.feature`, `.feature.md`) is derived and exists only as a stream: convert to
+stdout and pipe the result into its consumer. Never write the rendering next to
+the spec or anywhere else in the working tree; a copy drifts as soon as the spec
+changes. Use `-o <destination>` only to author a spec from Markdown with Gherkin
+the user supplied (`mdg-to-opsx`), or for a rendering the user explicitly asked
+for by name and destination. Existing outputs require `--force`. Respect the
+user's destination and overwrite intent.
 
 ```sh
+opsx-gherkin opsx-to-feature spec.md | <consumer> --stdin
+opsx-gherkin opsx-to-mdg spec.md | <consumer> --stdin
 opsx-gherkin mdg-to-opsx input.feature.md -o spec.md
-opsx-gherkin opsx-to-mdg spec.md -o output.feature.md
-opsx-gherkin opsx-to-feature spec.md -o output.feature
 ```
 
+Each converter accepts one path, `--text`, or stdin. Read the consumer's own
+help for how it takes standard input. If conversion reports that an Examples
+group has no table, see the formatter caveat under "Keep table and argument
+values intact".
+
 Use `--name` when OpenSpec text has no title or usable source-path context.
 `--project-root` supplies existing main-spec context for delta validation when
 needed. Consult a converter's `--help` for its exact options.
@@ -122,7 +140,7 @@ checks model preservation.
 ```sh
 validate-spec --format openspec spec.md
 validate-spec --format mdg input.feature.md
-validate-spec --format feature output.feature
+opsx-gherkin opsx-to-feature spec.md | validate-spec --format feature /dev/stdin
 ```
 
 Passing these checks establishes example syntax and conversion preservation.

package/skills/opsx-gherkin/references/OPENSPEC_MDG_PROFILE.feature.md

@@ -165,7 +165,7 @@ The converter SHALL map a Gherkin Feature to an OpenSpec title and Purpose, and
 
 ## Rule: Preserve behavioral Gherkin constructs
 
-The converter SHALL preserve Scenario and Scenario Outline structure, typed steps, tags, Examples, Data Tables, and Doc Strings without treating them as opaque prose.
+The converter SHALL preserve Scenario and Scenario Outline structure, typed steps, tags, Examples, Data Tables, and Doc Strings without treating them as opaque prose. An inline HTML comment inside a step's text is step text and SHALL be preserved verbatim.
 
 Canonical MDG and OpenSpec tables SHALL carry one Markdown separator row directly after their indented header; canonical plain Gherkin tables SHALL omit it. Compatible MDG inputs with or without separators SHALL preserve the same interpreted rows and values.
 
@@ -230,6 +230,21 @@ Canonical MDG and OpenSpec tables SHALL carry one Markdown separator row directl
   | MDG | OpenSpec |
   | OpenSpec | MDG |
 
+### Scenario Outline: Preserve an inline step comment in `<target_format>`
+
+* Given a compatible `<source_format>` main spec or delta whose step text ends with an inline HTML comment such as `<!-- addUnits -->`
+* When it is converted to `<target_format>`
+* Then the step text, including the comment, is unchanged
+* And the converter attaches no meaning to the comment
+
+#### Examples: Comment conversion directions
+
+  | source_format | target_format |
+  | --- | --- |
+  | OpenSpec | MDG |
+  | MDG | OpenSpec |
+  | OpenSpec | plain Gherkin |
+
 ## Rule: Project OpenSpec to a plain Gherkin feature
 
 The `opsx-to-feature` command SHALL preserve the same normalized behavioral model as `opsx-to-mdg` and MUST emit plain-text Gherkin accepted by the official parser.