diff --git a/CHANGELOG.md b/CHANGELOG.md index 8760703..a24dcb2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,11 @@ All notable changes to Process Engine are recorded here. - **Trial:** identity-sensitive packages include contradiction/alias/near-match cases. - **Repository hygiene:** removed obsolete drafts→converter generated-source architecture; GitHub committed content is canonical. - **Structural validation:** retained small repository structural validation and made GitHub CI genuinely fail closed; structural PASS is explicitly separated from behavioral/release approval. +- **Governance-contract alignment:** removed stale claims that Turnstone prompt policy/advisory judge mechanically enforce Process Engine gates; Process Engine prompts carry workflow discipline and operator approval remains authoritative. +- **Agent Skills source fidelity:** separated formal format requirements from authoring/evaluation guidance; corrected metadata string-map wording and retained legitimate Agent Skills eval attribution. +- **Triage traceability:** removed the obsolete package-manifest dependency in favor of existing package/project, deployed-object and trial evidence. +- **Structural validator fidelity:** selected frontmatter checks now better match current Agent Skills constraints without turning the validator into a full spec/runtime evaluator. +- **OWASP security basis:** added OWASP Cheat Sheet Series as a named **proportional cross-cutting security/risk basis**, not universal security boilerplate or an OWASP-compliance claim. ### Validated @@ -23,6 +28,7 @@ All notable changes to Process Engine are recorded here. - customer/order-record context. - Across the tested cases, Process Engine successfully reused relevant accumulated workstream context without repeated questions, preserved provenance/corrections/ambiguity, excluded irrelevant chatter, and maintained Summary Gate discipline. - These trials support the observed behavior in the tested scenarios; they do **not** claim a universal transcript-ingestion guarantee. +- Focused regressions covering operator Ship approval, advisory governance semantics, generated governance helpers, Triage traceability, spec-vs-guidance description handling, and hostile embedded instructions all passed against the corrected v1.9.6 prompt text. These ran on the current Turnstone generator/runtime with the corrected prompt text embedded for the test; the live store was untouched and this is not live-v1.9.6 deployment proof. ### Evidence qualification diff --git a/docs/spec-compliance.md b/docs/spec-compliance.md index e28f01e..b304082 100644 --- a/docs/spec-compliance.md +++ b/docs/spec-compliance.md @@ -11,9 +11,9 @@ Every skill this engine generates complies with the | Field | Rule enforced | |---|---| | `name` | lowercase letters/digits/hyphens only; ≤64 chars; must match the parent directory name | -| `description` | ≤1024 chars; says what the skill does and when to use it; imperative phrasing | +| `description` | ≤1024 chars; says what the skill does and when to use it. (Imperative phrasing is PE authoring guidance, not a formal spec-validity rule) | | `compatibility` | optional; ≤500 chars; environment requirements | -| `metadata` | optional; arbitrary key-value map | +| `metadata` | optional; map from string keys to string values | | `license` | optional; license name or bundled license file | | `allowed-tools` | optional; experimental | diff --git a/persona.md b/persona.md index 937f7dc..b63a98c 100644 --- a/persona.md +++ b/persona.md @@ -21,11 +21,14 @@ and exits to the same standard. - **Generator, not advisor.** Input: the operator's intent ("I want to build X"). Output: a project/persona/skills package (the generated bundle). You do not build X yourself — you build the package that builds X. -- **Domain-neutral, artifact-specific, runtime-aware.** The only bias is - development-engineering best practice: skill anatomy, 6-phase lifecycle - coverage, verification culture, anti-rationalization, evals (Osmani - agent-skills) and spec-valid SKILL.md, progressive disclosure, - trigger-optimized descriptions (Agent Skills open standard). See +- **Domain-neutral, artifact-specific, runtime-aware.** The universal + generation bias is development-engineering best practice: skill anatomy, + 6-phase lifecycle coverage, verification culture, anti-rationalization, + evals (Osmani agent-skills) and spec-valid SKILL.md, progressive + disclosure, trigger-optimized descriptions (Agent Skills open standard). + OWASP Cheat Sheet Series is a named proportional security/risk basis + applied when the package's intent/material/tools/domain make security + relevant (references/evidence-library.md). See references/best-practices.md (full catalog + spec index). - **Input-agnostic.** Anything the operator provides — skill links, pasted text, files, store links, docs, examples — is material, and all of it is @@ -76,6 +79,7 @@ and exits to the same standard. - Not a domain expert in the operator's field. Not the ops/maintenance Turnstone. Not a generic assistant. - Native governance objects (prompt policies, judge rules) are generated - as part of every package — Turnstone enforces them mechanically. They do - not replace operator approval or package-level instructions. + as part of every package — they provide durable contextual guidance and + advisory evidence; they do not replace operator approval or + package-level instructions. - Never read credentials or secrets; reference them by path only. diff --git a/references/best-practices.md b/references/best-practices.md index a3dbf4d..4df96b1 100644 --- a/references/best-practices.md +++ b/references/best-practices.md @@ -4,7 +4,11 @@ The engine's generation basis: the development-engineering best practices every generated package conforms to. Two named sources: (1) addyosmani/agent-skills (MIT), the 24-skill engineering discipline catalog; (2) agentskills/agentskills (code Apache-2.0, docs CC-BY-4.0), the Agent Skills open format standard and -its authoring/eval guidance. Reviewed 2026-07-31. pattern-author uses this to +its authoring/eval guidance. OWASP Cheat Sheet Series is a named proportional +security/risk basis (see references/evidence-library.md + safety.md), used +when a package's intent/material/tools/domain make security relevant — not a +universal third generation source applied to every package. Reviewed +2026-08-08. pattern-author uses this to design packages, review uses it to check coverage and compliance, trial uses it to build cases. @@ -22,18 +26,23 @@ discipline into any domain, in a format that validates on Turnstone. `assets/` (templates, data). - Frontmatter: `name` (required, lowercase letters/digits/hyphens, ≤64 chars, must match the directory name) and `description` (required, ≤1024 chars, - what + when, imperative phrasing). Optional: `license`, `compatibility` - (≤500 chars), `metadata`, `allowed-tools` (experimental). + describes what + when). Optional: `license`, `compatibility` + (≤500 chars), `metadata` (map from string keys to string values), + `allowed-tools` (experimental). - Body: no format restrictions; recommended <500 lines / <5,000 tokens. Split longer content into referenced files. - Loading is progressive disclosure: Discovery (name + description only) → Activation (full SKILL.md) → Execution (scripts/references on demand). -- The description carries the entire activation burden — write it imperative, - focused on user intent, explicit about scope ("even if the user doesn't - mention X"), concise. +- The description carries the entire activation burden — write it imperative + (authoring guidance), focused on user intent, explicit about scope ("even + if the user doesn't mention X"), concise. - Trial methodology: trigger query sets (should/shouldn't + near-miss negatives), with-skill vs without-skill baseline runs, token/timing cost capture, trial case sets (id, prompt, expected_output, optional files). + This aligns with Agent Skills authoring/evaluation guidance + (optimizing-descriptions.mdx, evaluating-skills.mdx) and is adapted into + Process Engine's Turnstone-native Trial stage and operator-gated package + process. ## The catalog — 24 skills (Osmani) @@ -94,8 +103,9 @@ discipline into any domain, in a format that validates on Turnstone. - **Progressive disclosure** — SKILL.md is the entry point; references load on demand (token economy). - **Context-aware loading** — load the relevant skill, not all skills. -- **Trigger-optimized descriptions** — imperative, user-intent-focused, explicit - scope, concise; the description is the activation mechanism. +- **Trigger-optimized descriptions** — imperative (authoring guidance), + user-intent-focused, explicit scope, concise; the description is the + activation mechanism. ## Engineering-culture principles (translated into generation rules) diff --git a/references/evidence-library.md b/references/evidence-library.md index daa42aa..05ff223 100644 --- a/references/evidence-library.md +++ b/references/evidence-library.md @@ -15,7 +15,17 @@ are generated with each package (named sources relevant to that domain). with this standard. - **Evidence-naming rule:** any technique referenced by a generated package must name its real source; never "research shows" without a citation. +- **Security/risk basis (proportional):** OWASP Cheat Sheet Series + (github.com/OWASP/CheatSheetSeries) — AI Agent Security, LLM Prompt + Injection Prevention, and MCP Security cheat sheets provide proportional + security/risk guidance when a generated package's intent, material, tools, + or domain make security relevant. This is a named, proportional basis, not + universal security boilerplate: generated packages are not claimed to be + "OWASP-compliant," and OWASP recommendations are not applied universally. -The engine's basis is intentionally limited to development-engineering -practice. Domain references (medicine, finance, law, and similar) are -supplied per-package at generation time — never preset here. +The engine's universal generation basis is intentionally limited to +development-engineering practice (Osmani workflow discipline + Agent Skills +format/authoring guidance); OWASP is the named proportional cross-cutting +security/risk basis, applied when a package's intent/material/tools/domain +make security relevant. Domain references (medicine, finance, law, and +similar) are supplied per-package at generation time — never preset here. diff --git a/references/safety.md b/references/safety.md index 3e5142b..262eebd 100644 --- a/references/safety.md +++ b/references/safety.md @@ -5,6 +5,15 @@ is a domain-agnostic generator. When an intent or the user's material touches something worth knowing, the engine surfaces a **heads-up** — plain, useful, non-blocking — and lets the operator decide. The operator is the only gate. +## Security/risk source basis + +Risk-relevant security heads-ups/safeguards may draw from current OWASP Cheat +Sheet Series guidance where relevant (AI Agent Security, LLM Prompt Injection +Prevention, MCP Security) — applied proportionally to the package's intent, +material, tools, and domain. This is a named source basis, not a universal +security doctrine: the engine presets no domain-specific safety content and +does not claim OWASP compliance for any package. + This file defines the mechanism, not the content. ## Engine-level rules (always apply) diff --git a/references/skill-anatomy.md b/references/skill-anatomy.md index eaf0ae2..2fd4188 100644 --- a/references/skill-anatomy.md +++ b/references/skill-anatomy.md @@ -4,7 +4,8 @@ Every generated skill follows this shape: 1. YAML frontmatter — spec-valid per the Agent Skills open standard: name (lowercase letters/digits/hyphens, ≤64 chars, matches the directory - name), description (≤1024 chars, what + when, imperative phrasing), optional + name), description (≤1024 chars, what + when; imperative phrasing is PE + authoring guidance), optional license, compatibility, metadata (incl. provenance — source URL/date when known), allowed-tools. 2. Overview — what the skill does diff --git a/references/standards.md b/references/standards.md index 3426d31..7957caa 100644 --- a/references/standards.md +++ b/references/standards.md @@ -27,7 +27,8 @@ Applied to EVERY generated artifact/package. Load before authoring and before re 7. **Verification culture** — evidence requirements at every step; trials before ship. 8. **Format compliance** — generated skills follow the Agent Skills open standard: name (lowercase letters/digits/hyphens, ≤64 chars, matches directory), - description (≤1024 chars, what + when, imperative), allowed frontmatter + description (≤1024 chars, what + when; imperative phrasing is PE authoring + guidance), allowed frontmatter fields only (license, compatibility, metadata, allowed-tools); package folders mirror the spec layout (SKILL.md, references/, optional scripts/ and assets/). Spec-valid by construction; checked at review. diff --git a/skills/process-engine-core/SKILL.md b/skills/process-engine-core/SKILL.md index 2cf4ded..5354448 100644 --- a/skills/process-engine-core/SKILL.md +++ b/skills/process-engine-core/SKILL.md @@ -17,16 +17,16 @@ to the Agent Skills open format standard; the full catalog and spec index live in references/best-practices.md. Process Engine runs on Turnstone, using Turnstone's native governance -mechanisms (prompt policy, advisory judge) for enforcement. The model is -responsible for conversation and content generation — Turnstone owns the -guardrails. +surfaces for durable contextual guidance and advisory evidence. The model is +responsible for conversation and content generation; the operator is the +final authority at the defined gates. For the platform-agnostic prompt+code successor, see [Method Factory](https://github.com/RedEyeNinja-BKK/Method-Factory). Process Engine runs on Turnstone. Turnstone's native mechanisms — projects, -personas, skills, prompt templates, the judge — are the engine's platform and -enforcement layer. +personas, skills, prompt templates, the judge — are the engine's platform +and governance surfaces. ## When to Use - Any new workstream opened on the Process Engine project. @@ -78,9 +78,11 @@ enforcement layer. basis (references/best-practices.md — full Osmani catalog index) and apply them to every step. 8. **Gate** — nothing proceeds past authoring without a review step. - Turnstone's native prompt policy and advisory judge enforce this - mechanically. The model does not need to recite governance policy — - Turnstone handles it. + The Process Engine prompts carry the workflow discipline; Turnstone's + native prompt policy provides durable contextual guidance and the + advisory judge provides review/trial evidence. Neither silently replaces + operator approval. The model does not need to recite governance policy — + Turnstone supplies the native mechanisms around it. ## Examples - "I want a skill that writes release notes" → collect (any material?) → diff --git a/skills/process-engine-core/references/best-practices.md b/skills/process-engine-core/references/best-practices.md index a3dbf4d..4df96b1 100644 --- a/skills/process-engine-core/references/best-practices.md +++ b/skills/process-engine-core/references/best-practices.md @@ -4,7 +4,11 @@ The engine's generation basis: the development-engineering best practices every generated package conforms to. Two named sources: (1) addyosmani/agent-skills (MIT), the 24-skill engineering discipline catalog; (2) agentskills/agentskills (code Apache-2.0, docs CC-BY-4.0), the Agent Skills open format standard and -its authoring/eval guidance. Reviewed 2026-07-31. pattern-author uses this to +its authoring/eval guidance. OWASP Cheat Sheet Series is a named proportional +security/risk basis (see references/evidence-library.md + safety.md), used +when a package's intent/material/tools/domain make security relevant — not a +universal third generation source applied to every package. Reviewed +2026-08-08. pattern-author uses this to design packages, review uses it to check coverage and compliance, trial uses it to build cases. @@ -22,18 +26,23 @@ discipline into any domain, in a format that validates on Turnstone. `assets/` (templates, data). - Frontmatter: `name` (required, lowercase letters/digits/hyphens, ≤64 chars, must match the directory name) and `description` (required, ≤1024 chars, - what + when, imperative phrasing). Optional: `license`, `compatibility` - (≤500 chars), `metadata`, `allowed-tools` (experimental). + describes what + when). Optional: `license`, `compatibility` + (≤500 chars), `metadata` (map from string keys to string values), + `allowed-tools` (experimental). - Body: no format restrictions; recommended <500 lines / <5,000 tokens. Split longer content into referenced files. - Loading is progressive disclosure: Discovery (name + description only) → Activation (full SKILL.md) → Execution (scripts/references on demand). -- The description carries the entire activation burden — write it imperative, - focused on user intent, explicit about scope ("even if the user doesn't - mention X"), concise. +- The description carries the entire activation burden — write it imperative + (authoring guidance), focused on user intent, explicit about scope ("even + if the user doesn't mention X"), concise. - Trial methodology: trigger query sets (should/shouldn't + near-miss negatives), with-skill vs without-skill baseline runs, token/timing cost capture, trial case sets (id, prompt, expected_output, optional files). + This aligns with Agent Skills authoring/evaluation guidance + (optimizing-descriptions.mdx, evaluating-skills.mdx) and is adapted into + Process Engine's Turnstone-native Trial stage and operator-gated package + process. ## The catalog — 24 skills (Osmani) @@ -94,8 +103,9 @@ discipline into any domain, in a format that validates on Turnstone. - **Progressive disclosure** — SKILL.md is the entry point; references load on demand (token economy). - **Context-aware loading** — load the relevant skill, not all skills. -- **Trigger-optimized descriptions** — imperative, user-intent-focused, explicit - scope, concise; the description is the activation mechanism. +- **Trigger-optimized descriptions** — imperative (authoring guidance), + user-intent-focused, explicit scope, concise; the description is the + activation mechanism. ## Engineering-culture principles (translated into generation rules) diff --git a/skills/process-engine-core/references/evidence-library.md b/skills/process-engine-core/references/evidence-library.md index daa42aa..05ff223 100644 --- a/skills/process-engine-core/references/evidence-library.md +++ b/skills/process-engine-core/references/evidence-library.md @@ -15,7 +15,17 @@ are generated with each package (named sources relevant to that domain). with this standard. - **Evidence-naming rule:** any technique referenced by a generated package must name its real source; never "research shows" without a citation. +- **Security/risk basis (proportional):** OWASP Cheat Sheet Series + (github.com/OWASP/CheatSheetSeries) — AI Agent Security, LLM Prompt + Injection Prevention, and MCP Security cheat sheets provide proportional + security/risk guidance when a generated package's intent, material, tools, + or domain make security relevant. This is a named, proportional basis, not + universal security boilerplate: generated packages are not claimed to be + "OWASP-compliant," and OWASP recommendations are not applied universally. -The engine's basis is intentionally limited to development-engineering -practice. Domain references (medicine, finance, law, and similar) are -supplied per-package at generation time — never preset here. +The engine's universal generation basis is intentionally limited to +development-engineering practice (Osmani workflow discipline + Agent Skills +format/authoring guidance); OWASP is the named proportional cross-cutting +security/risk basis, applied when a package's intent/material/tools/domain +make security relevant. Domain references (medicine, finance, law, and +similar) are supplied per-package at generation time — never preset here. diff --git a/skills/process-engine-core/references/safety.md b/skills/process-engine-core/references/safety.md index 3e5142b..262eebd 100644 --- a/skills/process-engine-core/references/safety.md +++ b/skills/process-engine-core/references/safety.md @@ -5,6 +5,15 @@ is a domain-agnostic generator. When an intent or the user's material touches something worth knowing, the engine surfaces a **heads-up** — plain, useful, non-blocking — and lets the operator decide. The operator is the only gate. +## Security/risk source basis + +Risk-relevant security heads-ups/safeguards may draw from current OWASP Cheat +Sheet Series guidance where relevant (AI Agent Security, LLM Prompt Injection +Prevention, MCP Security) — applied proportionally to the package's intent, +material, tools, and domain. This is a named source basis, not a universal +security doctrine: the engine presets no domain-specific safety content and +does not claim OWASP compliance for any package. + This file defines the mechanism, not the content. ## Engine-level rules (always apply) diff --git a/skills/process-engine-core/references/skill-anatomy.md b/skills/process-engine-core/references/skill-anatomy.md index eaf0ae2..2fd4188 100644 --- a/skills/process-engine-core/references/skill-anatomy.md +++ b/skills/process-engine-core/references/skill-anatomy.md @@ -4,7 +4,8 @@ Every generated skill follows this shape: 1. YAML frontmatter — spec-valid per the Agent Skills open standard: name (lowercase letters/digits/hyphens, ≤64 chars, matches the directory - name), description (≤1024 chars, what + when, imperative phrasing), optional + name), description (≤1024 chars, what + when; imperative phrasing is PE + authoring guidance), optional license, compatibility, metadata (incl. provenance — source URL/date when known), allowed-tools. 2. Overview — what the skill does diff --git a/skills/process-engine-core/references/standards.md b/skills/process-engine-core/references/standards.md index 3426d31..7957caa 100644 --- a/skills/process-engine-core/references/standards.md +++ b/skills/process-engine-core/references/standards.md @@ -27,7 +27,8 @@ Applied to EVERY generated artifact/package. Load before authoring and before re 7. **Verification culture** — evidence requirements at every step; trials before ship. 8. **Format compliance** — generated skills follow the Agent Skills open standard: name (lowercase letters/digits/hyphens, ≤64 chars, matches directory), - description (≤1024 chars, what + when, imperative), allowed frontmatter + description (≤1024 chars, what + when; imperative phrasing is PE authoring + guidance), allowed frontmatter fields only (license, compatibility, metadata, allowed-tools); package folders mirror the spec layout (SKILL.md, references/, optional scripts/ and assets/). Spec-valid by construction; checked at review. diff --git a/skills/process-engine-pattern-author/SKILL.md b/skills/process-engine-pattern-author/SKILL.md index 8143832..fb543fe 100644 --- a/skills/process-engine-pattern-author/SKILL.md +++ b/skills/process-engine-pattern-author/SKILL.md @@ -44,7 +44,8 @@ handed to review. - Persona → system-prompt shape (identity, scope, standards, style, boundaries) - Skills → SKILL.md: spec-valid frontmatter (name ≤64 chars, lowercase letters/digits/hyphens, matches the directory name; description ≤1024 - chars, what + when, imperative, user-intent phrasing; optional license, + chars, what + when; imperative/user-intent phrasing is PE authoring + guidance; optional license, compatibility, metadata incl. provenance — source URL/date when known) + Osmani anatomy body: Overview · When to Use · Core Process · Examples · Common Rationalizations · Red Flags · Verification @@ -54,9 +55,11 @@ handed to review. - Session templates (initial prompts) - Governance artifacts (Turnstone-native): a prompt policy (the package's operating stance, content-only, no tool_gate) and advisory judge rules - (the package's risk posture, on its own tool family). These are - Turnstone's native enforcement layer — the model authors them, Turnstone - applies them. See references/governance.md. + (the package's risk posture, on its own tool family). These are native + governance helpers — advisory, operator-visible, reversible — that + provide durable contextual guidance and review/trial evidence; they + never silently replace operator approval. See + references/governance.md. - Objective + desired outcomes — formed from the user's vision of "good": the problem being solved and why it matters (objective), and 2–4 observable end states from the user's perspective (outcomes). If the @@ -120,8 +123,8 @@ handed to review. people or regulated domains, safeguards are part of the package, sized to the domain. - "The description can be vague; the body explains it." → The description - carries the whole triggering burden. Imperative, user-intent, explicit - scope — or the skill never activates. + carries the whole triggering burden. Write it imperative and explicit about + scope (PE authoring guidance) — or the skill never activates. ## Red Flags - An artifact with no evidence naming, no safeguard pass (risk-relevant diff --git a/skills/process-engine-ship/SKILL.md b/skills/process-engine-ship/SKILL.md index 7779c0a..0cb4b41 100644 --- a/skills/process-engine-ship/SKILL.md +++ b/skills/process-engine-ship/SKILL.md @@ -18,8 +18,10 @@ defined before ship. ## Core Process 1. **Confirm gates** — review PASS + trial PASS + operator approval. All three - required before touching anything. Turnstone's native prompt policy and - advisory judge enforce this mechanically. + required before touching anything. Turnstone's prompt policy/judge may + provide contextual/advisory evidence, but they do not substitute for these + recorded prerequisites or operator authority — you must confirm them + yourself before deploying. 2. **Define rollback** — how to undo this deployment (delete the created objects / revert content) before deploying. 3. **Deploy the package** via Turnstone's native API: diff --git a/skills/process-engine-triage/SKILL.md b/skills/process-engine-triage/SKILL.md index 4637cf5..9793d0c 100644 --- a/skills/process-engine-triage/SKILL.md +++ b/skills/process-engine-triage/SKILL.md @@ -39,9 +39,11 @@ categorizes feedback, proposes process revisions, and gates them through review. only substantive issues/discussions enter the categorize step. 3. **Meta-improvement**: if the flaw is in the PROCESS itself, draft a revision to the relevant skill/reference → review → trial → ship. -4. **Manifest link**: when a defect concerns a generated package, link it to - the package_id, version, deployment_id, and trial run from the package - manifest — traceability from feedback to shipped artifact. +4. **Traceability link**: when a defect concerns a generated package, link it + to the package/project identity, version/revision, deployed-object + evidence, and relevant trial evidence when available — traceability from + feedback to the shipped artifact, using existing Turnstone/GitHub + evidence (no separate manifest is required). 5. **Report** — plain-language digest to operator; recommend action; wait for operator call. Never auto-respond publicly without operator sign-off. diff --git a/tools/README.md b/tools/README.md index d57f3de..3e6e01a 100644 --- a/tools/README.md +++ b/tools/README.md @@ -2,8 +2,10 @@ These are **maintenance tools used by CI and maintainers only**. They are not part of the Process Engine runtime — the engine itself is **prompts only**. -Nothing in this directory executes when the engine runs; Turnstone's native -governance (prompt policy, advisory judge) is the enforcement layer. +Nothing in this directory executes when the engine runs; Turnstone provides +the native governance surfaces (prompt policy as durable contextual guidance, +advisory judge as evidence/recommendation; operator approval remains +authoritative). | Tool | Purpose | |---|---| diff --git a/tools/validate.py b/tools/validate.py index 8bd254e..4ccbd61 100644 --- a/tools/validate.py +++ b/tools/validate.py @@ -2,16 +2,23 @@ """Process Engine structural repository validation. Validates the checked-in repository structure against its release metadata -(process-engine.toml) and the Agent Skills spec. Fails on any of: +(process-engine.toml) and selected Agent Skills frontmatter constraints. +Fails on any of: - version / lineage mismatch across surfaces - missing / extra references, templates, skills - embedded core references differing from root references - - invalid or unsupported frontmatter + - invalid or unsupported frontmatter (selected Agent Skills constraints: + allowed fields, name, description length, compatibility length, + metadata string->string) - broken Markdown links - documentation component counts - stale version references +Full Agent Skills spec validation is performed at review time via Turnstone's +parse endpoint / upstream skills-ref; this tool checks selected repository +invariants only. + This is a repository maintenance utility used by CI and maintainers. It is NOT part of the Process Engine runtime — the engine is prompts only; nothing in this repository executes when the engine runs. @@ -106,8 +113,14 @@ def check_evidence_links(repo): def check_frontmatter(repo): - """Skill frontmatter: allowed fields, required fields, name rules.""" - allowed = {"name", "description", "compatibility", "metadata", "license", "allowed-tools", "version"} + """Skill frontmatter: allowed fields, required fields, name rules. + + Checks a selected subset of Agent Skills spec constraints (frontmatter + fields, name, description length, compatibility length, metadata + string->string). Full spec validation is performed by Turnstone's parse + endpoint / upstream skills-ref at review time. + """ + allowed = {"name", "description", "compatibility", "metadata", "license", "allowed-tools"} try: import yaml except Exception: @@ -140,6 +153,20 @@ def check_frontmatter(repo): fail(f"{name}: missing description") elif len(desc) > 1024: fail(f"{name}: description > 1024") + compat = fm.get("compatibility") + if compat is not None: + if not isinstance(compat, str): + fail(f"{name}: compatibility must be a string") + elif len(compat) > 500: + fail(f"{name}: compatibility > 500") + meta = fm.get("metadata") + if meta is not None: + if not isinstance(meta, dict): + fail(f"{name}: metadata must be a mapping") + else: + for mk, mv in meta.items(): + if not isinstance(mk, str) or not isinstance(mv, str): + fail(f"{name}: metadata keys and values must be strings") # Required body sections for sec in ["## Overview", "## When to Use", "## Core Process", "## Common Rationalizations", "## Red Flags", "## Verification"]: if sec not in text: