Verification and traceability

Platform spec article

Verification and traceability

Back to Project templates ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (10)

1. 0001-beskid-template-v1-engine Beskid-native template engine schema Accepted

   Use beskid.template.v1 only

   Context

   Foreign template engines would split validation and documentation across ecosystems.

   Decision

   The platform must use beskid.template.v1 only. Foreign engine schemas are forbidden in spec, CLI, and pckg.

   Consequences

   Single parser and validator in tooling; template docs stay in-repo.

   Verification anchors

   CI grep excluding foreign schema identifiers under compiler/ and platform-spec tooling tree.

   Open full ADR page

2. 0002-placeholder-delimiters Human-readable {{ }} placeholders Accepted

   Use {{symbolId}} delimiters in template text

   Context

   Template authors need delimiter syntax distinct from Beskid source.

   Decision

   Text files must use {{symbolName}} placeholders; optional sourceName rewriting applies to paths and identifiers.

   Consequences

   Editors can highlight unmatched braces; substitution tests stay deterministic.

   Verification anchors

   Golden substitution tests under planned beskid_tests template fixtures.

   Open full ADR page

3. 0003-no-runnable-template-root Templates need not build at template root Accepted

   Validation runs on instantiation output only, not template project build.

   Context

   Requiring beskid build on template sources slows authoring and blocks non-host template layouts.

   Decision

   Template packages need not compile at the template project root. Tooling must validate via instantiation output builds.

   Consequences

   Faster template iteration; CI runs instantiate-then-build on consumer output.

   Verification anchors

   beskid.templates.* CI pipeline; planned beskid_tests template fixtures.

   Open full ADR page

4. 0004-corelib-always-on Implicit corelib Accepted

   Implicit corelib

   Context

   Hosts need standard library.

   Decision

   Inject corelib; forbid noCorelib flags.

   Consequences

   Simpler manifests.

   Verification anchors

   E18xx linter.

   Open full ADR page

5. 0005-template-kinds-v1 Three template kinds Accepted

   Three template kinds

   Context

   Workspace, project, item flows.

   Decision

   Support all three via tags.type.

   Consequences

   One engine.

   Verification anchors

   Three beskid_tests fixtures.

   Open full ADR page

6. 0006-path-and-git-sources Path and git sources Accepted

   Path and git sources

   Context

   Local workflows.

   Decision

   Resolve registry, path, and git.

   Consequences

   beskid new flags.

   Verification anchors

   Git/path integration tests.

   Open full ADR page

7. 0007-no-constraint-blocks No constraints Accepted

   No constraints

   Context

   DSL delay.

   Decision

   No constraint blocks in schema.

   Consequences

   Simpler v1.

   Verification anchors

   Reject constraints key.

   Open full ADR page

8. 0008-unrestricted-post-actions Post-actions Accepted

   Post-actions

   Context

   Extensibility.

   Decision

   Documented action ids, no v1 whitelist.

   Consequences

   Operator sandbox policy.

   Verification anchors

   Action registry docs.

   Open full ADR page

9. 0009-update-check-on-use Update on use Accepted

   Update on use

   Context

   Stale cache.

   Decision

   Compare cache on every use when online.

   Consequences

   Update prompts.

   Verification anchors

   Mock HTTP test.

   Open full ADR page

10. 0010-yanked-template-warning Yanked warning Accepted

    Yanked warning

    Context

    Yank policy.

    Decision

    Warn on yanked; optional continue flag.

    Consequences

    Registry alignment.

    Verification anchors

    Yank API test.

    Open full ADR page

Articles

• Contracts and edge cases Normative MUST/SHOULD rules for template instantiation, updates, yanked packages, and post-actions. article Standard Reviewed Thu May 21
• Decisions record (legacy index) Migration index pointing to per-decision ADR files under adr/. article Standard Reviewed Fri May 22
• Design model `beskid.template.v1` schema, symbols, sources, placeholders, GUIDs, and corelib policy. article Standard Reviewed Thu May 21
• Examples Sample `beskid.template.v1` manifests and first-party `beskid.templates.*` packages. article Standard Reviewed Thu May 21
• FAQ and troubleshooting Common questions about Beskid templates and `beskid new`. article Standard Reviewed Thu May 21
• Flow and algorithm End-to-end lifecycle for install, update check, and instantiate. article Standard Reviewed Thu May 21
• Verification and traceability Tests, CI, and registry checks for template conformance. article Standard Reviewed Thu May 21

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 13 SpecSection(s) · 0 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Feature
  Project templates

  Parent feature hub

Purpose and scope

How implementers prove template engine and first-party package compliance.

Conformance matrix

Requirement	Verification
beskid.template.v1 parse	JSON schema fixture tests in beskid_tests
{{ }} exhaustion	Golden output diff tests
GUID rewrite	Multi-format guid fixture files in template content
corelib after instantiate	beskid lock + compile smoke without noCorelib manifest key
Update check on use	Mock registry returning newer semver → expect stdout message
Yanked warning	Publish yanked version → beskid new warns
Item template	Instantiate into temp project → beskid analyze
Workspace template	Two members resolve in beskid tree

First-party packages

Package id	shortName	tags.type
beskid.templates.console	console	project
beskid.templates.lib	lib	project
beskid.templates.project	template	project

CI must pack and publish these under the beskid.templates.* namespace when registry credentials are available, matching corelib publish workflow patterns.

pckg server

• Template .bpk must reject packageKind: library when template.json present (or require template).
• Template package page must not mount API documentation viewer (see template packages).

Spec drift

Changes to beskid.template.v1 must update this article and design model in the same change set.