pbakaus_impeccable/skill/scripts/lib/artifact-schema.mjs

/**
 * Schema versions for the artifacts Impeccable writes, plus the readers and
 * writers for the PRODUCT.md provenance stamp.
 *
 * Why schema versions rather than the skill version: a PRODUCT.md written by
 * v4.0.0 is not stale under v4.0.1, so stamping the release version would make
 * every artifact "old" on every patch. A schema version changes only when the
 * shape changes, which is exactly when a migration is owed. It also gives the
 * writing flows a literal constant to copy instead of a value they would have
 * to look up.
 *
 * DESIGN.md deliberately carries no stamp. It follows the external
 * design.md spec that Stitch's linter validates, and an extra frontmatter key
 * risks failing that lint for no gain: every DESIGN.md staleness signal
 * (sidecar schema version, sidecar mtime, section coverage, git drift) is
 * measurable without one.
 */

/** PRODUCT.md as init.md writes it today: the ten-section v4 record. */
export const PRODUCT_SCHEMA_VERSION = 1;

/** `.impeccable/design.json`, as documented in reference/document.md Step 4b. */
export const DESIGN_SIDECAR_SCHEMA_VERSION = 2;

/**
 * Sections init.md added in v4. A PRODUCT.md carrying none of them, and no
 * stamp, predates the current record. Used only as a fallback: an explicit
 * stamp always wins.
 */
export const PRODUCT_V4_SECTIONS = Object.freeze([
  'Positioning',
  'Operating Context',
  'Evidence on Hand',
  'Product Principles',
]);

/**
 * Headings Impeccable used to read and no longer does, with the reason. The
 * agent needs the reason: told only that a field is deprecated it tends to
 * preserve it "just in case", which is how a v3 register value keeps steering
 * v4 output.
 */
export const PRODUCT_DEPRECATED_SECTIONS = Object.freeze({
  Register: 'v4 replaced the brand/product register axis with the four visitor modes '
    + '(Persuade, Operate, Read, Experience), which are chosen per surface and persisted in that '
    + "surface's brief. Nothing reads `## Register` any more.",
});

const PRODUCT_STAMP_RE = /^[ \t]*<!--[ \t]*impeccable:product-schema[ \t]+(\d+)[ \t]*-->[ \t]*$/im;

/** The literal stamp line, for the init template and for migrations. */
export function productStampLine(version = PRODUCT_SCHEMA_VERSION) {
  return `<!-- impeccable:product-schema ${version} -->`;
}

/**
 * Schema version stamped in a PRODUCT.md body, or null when unstamped. Null
 * means "written before stamping existed", not "invalid".
 */
export function readProductSchemaVersion(markdown) {
  const match = String(markdown || '').match(PRODUCT_STAMP_RE);
  if (!match) return null;
  const version = Number.parseInt(match[1], 10);
  return Number.isInteger(version) ? version : null;
}

/**
 * Add or update the stamp, returning the new body. Idempotent. A stamped file
 * keeps the stamp where it already sits so a migration never reorders the
 * user's prose; an unstamped file gets it directly under the leading `#`
 * heading, or at the top when there is none.
 */
export function stampProductSchema(markdown, version = PRODUCT_SCHEMA_VERSION) {
  const body = String(markdown || '');
  const line = productStampLine(version);
  if (PRODUCT_STAMP_RE.test(body)) return body.replace(PRODUCT_STAMP_RE, line);

  const lines = body.split('\n');
  const headingIndex = lines.findIndex((entry) => /^#\s+\S/.test(entry));
  if (headingIndex === -1) return `${line}\n\n${body.replace(/^\n+/, '')}`;
  lines.splice(headingIndex + 1, 0, '', line);
  return lines.join('\n');
}

/**
 * Schema version of a parsed design.json. Returns null for a missing or
 * non-numeric field, which is how schemaVersion-1-era sidecars present
 * (the field predates the v2 rewrite in some files).
 */
export function readSidecarSchemaVersion(sidecar) {
  const version = sidecar && typeof sidecar === 'object' ? sidecar.schemaVersion : null;
  return Number.isInteger(version) ? version : null;
}