@supersuit/superskill 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.2.2 (2026-09-29)
+
+- An inline flow map (`scope: { form: essay, audience: builders, purpose: persuade }`, `check: {
+  station: every segment carries a label }`) now reads as an object instead of the whole `{ ...
+  }` coming back as a string. Nested inline maps and inline lists inside inline maps work too
+  (`speech: { uses: [a, b], never: [c] }`).
+- An inline flow list followed by a same-line comment (`conditions: [r1, r2, r3]   # 5 to 10
+  ids`) now reads as a list. Before this, the inline-list check required the raw value to END in
+  `]`, and a trailing comment broke that, so the whole line came back as a string.
+- Both are read by a quote-aware character scanner rather than a naive split, so a comma,
+  bracket, brace or hash inside a quoted value inside a flow collection stays text
+  (`{ note: "a, b] } # c" }`). Malformed flow syntax (unbalanced brackets) still never throws: it
+  falls back to the raw string, same as an unrecognized value always has.
+- A block list item that is itself a bare inline flow map or list (`- { station: fine, severity:
+  fail }`, `- [a, b]`) now reads as an object or a list. Before this, the KEY regex that decides
+  whether `- key: value` opens a block submap matched on the first colon inside the braces
+  (reading `"{ station"` as the key), so the item came back as `{ "{ station": "fine, severity:
+  fail }" }`. `- key: { ... }` still opens a block submap as before.
+
+## 0.2.1 (2026-09-28)
+
+- An unquoted value that is only a comment now reads as empty, which is what YAML means. Before
+  this, `source: # TODO` came back as the string "# TODO" and a list item written as `- # none
+  yet` came back as "# none yet", so a downstream linter counted a comment placeholder as a
+  filled-in field and passed specs it should have failed. A comment-only value followed by a
+  more-indented block still opens that nested map or list, exactly as it did with no comment.
+  Quoted values are untouched: `key: "# literal"` still reads as "# literal".
+
 ## 0.2.0 (2026-09-28)
 
 - The frontmatter reader reads nesting: maps inside maps, lists of maps, lists inside maps, and

package/SPEC.md

@@ -1,6 +1,6 @@
 # The superskill standard
 
-**Version 0.2.0** (2026-09-28). The reference checker is `@supersuit/superskill`; where this
+**Version 0.2.2** (2026-09-29). The reference checker is `@supersuit/superskill`; where this
 document and the checker disagree, the checker has a bug.
 
 A **superskill** runs on frontier intelligence, is checked against examples a person approved,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/superskill",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Score any agent skill folder as skill, tested, or superskill. An open standard and a zero-dependency CLI.",
   "type": "module",
   "bin": { "superskill": "bin/superskill.mjs" },

package/src/frontmatter.mjs

@@ -27,6 +27,17 @@ const indentOf = (l) => l.length - l.trimStart().length;
 // at any depth, read by indentation. Until then the reader stopped at one level and IGNORED
 // anything deeper, so a list of maps came back as nothing and no error said so. Values still
 // stay strings. A stray indented line at the top level is still tolerated, as before.
+// 0.2.1: an unquoted value or list item that is only a comment (`key: # TODO`, `- # none yet`)
+// reads as empty, the same as no value at all, which is what YAML means. A comment-only value
+// that is followed by a more-indented block still opens that nested map or list, exactly as
+// `key:` with nothing after it does.
+// 0.2.2: an inline flow map (`scope: { form: essay, audience: builders }`) reads as an object,
+// nested to any depth (a flow map inside a flow map, a flow list inside a flow map). And an
+// inline flow list followed by a same-line comment (`conditions: [r1, r2, r3]   # 5 to 10 ids`)
+// reads as a list instead of the whole `[...]  # ...` text, because the flow value is now parsed
+// character-by-character (quote-aware) instead of by checking whether the raw value ends in `]`.
+// Malformed flow syntax (unbalanced brackets) never throws: it falls back to the raw string, the
+// same as an unrecognized value always has.
 export function parseYamlSubset(lines) {
   return parseMap(lines, 0, 0, true)[0];
 }
@@ -62,7 +73,7 @@ function parseMap(lines, i, indent, top = false) {
       const [v, next] = readBlock(lines, i, ind, rest[0]);
       out[key] = v; i = next; continue;
     }
-    if (rest === "") {
+    if (rest === "" || rest.startsWith("#")) {
       const j = nextContent(lines, i);
       if (j < lines.length) {
         const ci = indentOf(lines[j]);
@@ -90,7 +101,7 @@ function parseList(lines, i, indent) {
     const content = t === "-" ? "" : t.slice(1).trimStart();
     const at = line.indexOf(content, ind + 1); // where the item's content starts on the line
     i++;
-    if (content === "") {
+    if (content === "" || content.startsWith("#")) {
       const j = nextContent(lines, i);
       if (j < lines.length && indentOf(lines[j]) > ind) {
         const ci = indentOf(lines[j]);
@@ -99,6 +110,16 @@ function parseList(lines, i, indent) {
       } else out.push("");
       continue;
     }
+    if (content.startsWith("{") || content.startsWith("[")) {
+      // A bare flow map/list item (`- { station: fine, severity: fail }`, `- [a, b]`) is not a
+      // "- key: value" line, even though the KEY regex below would happily match on the first
+      // colon inside the braces (reading "{ station" as the key, which produced garbage). Try
+      // the flow parse first; when it is malformed, `inlineOrScalar` falls back to the raw
+      // string via `scalar()`, same as an unrecognized top-level value always has. Either way
+      // this never falls through to the "- key: value" submap heuristic below, because a flow
+      // collection's opening bracket can never legitimately be a map key.
+      out.push(inlineOrScalar(content)); continue;
+    }
     if (KEY.test(content) && !/^\[.*\]$/.test(content)) {
       // "- key: value" opens a map whose keys sit where this content starts.
       const sub = [" ".repeat(at) + content, ...lines.slice(i)];
@@ -120,10 +141,88 @@ function readBlock(lines, i, keyIndent, style) {
 }
 
 function inlineOrScalar(rest) {
-  if (rest.startsWith("[") && rest.endsWith("]")) return splitInline(rest.slice(1, -1)).map(scalar).filter((s) => s !== "");
+  if (rest.startsWith("[") || rest.startsWith("{")) {
+    const flow = tryParseFlow(rest);
+    if (flow !== undefined) return flow;
+  }
   return scalar(rest);
 }
 
+// A flow collection (`[...]` or `{...}`) parsed character-by-character so quotes can protect a
+// `,` `]` `}` or `#` from being read as structure, and so trailing whitespace plus a same-line
+// comment after the closing bracket does not fall the whole value back to a raw string. Returns
+// `undefined` (never throws) when `rest` is not a clean flow value: unbalanced brackets, an
+// unterminated quote, or trailing content that is neither blank nor a comment. The caller falls
+// back to `scalar(rest)` in every one of those cases, same as an unrecognized value always has.
+function tryParseFlow(rest) {
+  let parsed;
+  try {
+    parsed = readFlowCollection(rest, 0);
+  } catch {
+    return undefined;
+  }
+  const trailing = rest.slice(parsed.end);
+  if (trailing.trim() === "" || /^\s+#/.test(trailing)) return parsed.value;
+  return undefined;
+}
+
+function readFlowCollection(s, i) {
+  const open = s[i];
+  const close = open === "{" ? "}" : "]";
+  const isMap = open === "{";
+  i = skipFlowWs(s, i + 1);
+  if (s[i] === close) return { value: isMap ? {} : [], end: i + 1 };
+  const items = [];
+  for (;;) {
+    i = skipFlowWs(s, i);
+    if (i >= s.length) throw new Error("unterminated flow collection");
+    let key;
+    if (isMap) {
+      const k = readFlowToken(s, i, [":"]);
+      key = k.text.trim().replace(/^["']|["']$/g, "");
+      i = skipFlowWs(s, k.end + 1);
+    }
+    let value;
+    if (s[i] === "{" || s[i] === "[") {
+      const nested = readFlowCollection(s, i);
+      value = nested.value; i = nested.end;
+    } else {
+      const v = readFlowToken(s, i, [",", close]);
+      value = scalar(v.text);
+      i = v.end;
+    }
+    items.push(isMap ? [key, value] : value);
+    i = skipFlowWs(s, i);
+    if (s[i] === ",") { i = skipFlowWs(s, i + 1); if (s[i] === close) { i++; break; } continue; }
+    if (s[i] === close) { i++; break; }
+    throw new Error(`expected ',' or '${close}'`);
+  }
+  const value = isMap ? Object.fromEntries(items) : items.filter((v) => v !== "");
+  return { value, end: i };
+}
+
+function skipFlowWs(s, i) {
+  while (i < s.length && /\s/.test(s[i])) i++;
+  return i;
+}
+
+// Reads raw text from `i` up to (but not including) the first unquoted occurrence of a char in
+// `stopChars`, honoring both quote styles so a stop char inside quotes stays text. Throws (never
+// returns a partial token) when the string runs out before a stop char is found outside quotes,
+// which is what an unbalanced bracket or an unterminated quote looks like from here.
+function readFlowToken(s, i, stopChars) {
+  let text = "";
+  let q = null;
+  while (i < s.length) {
+    const ch = s[i];
+    if (q) { text += ch; if (ch === q) q = null; i++; continue; }
+    if (ch === '"' || ch === "'") { q = ch; text += ch; i++; continue; }
+    if (stopChars.includes(ch)) return { text, end: i };
+    text += ch; i++;
+  }
+  throw new Error("unterminated flow token");
+}
+
 function foldLines(lines) {
   let s = "";
   for (const l of lines) {
@@ -133,19 +232,6 @@ function foldLines(lines) {
   return s;
 }
 
-function splitInline(s) {
-  const parts = [];
-  let cur = "", q = null;
-  for (const ch of s) {
-    if (q) { cur += ch; if (ch === q) q = null; }
-    else if (ch === '"' || ch === "'") { q = ch; cur += ch; }
-    else if (ch === ",") { parts.push(cur); cur = ""; }
-    else cur += ch;
-  }
-  parts.push(cur);
-  return parts.map((p) => p.trim());
-}
-
 function scalar(raw) {
   const s = String(raw).trim();
   if (s.startsWith('"')) {