Skip to content

Fix/documentation language consistency - #9

Merged
eschaar merged 19 commits into
mainfrom
fix/documentation-language-consistency
Apr 20, 2026
Merged

Fix/documentation language consistency#9
eschaar merged 19 commits into
mainfrom
fix/documentation-language-consistency

Conversation

@eschaar

@eschaar eschaar commented Apr 20, 2026

Copy link
Copy Markdown
Owner

Summary

This PR is a broad branch consolidation that includes CLI/runtime refactors, frontmatter serializer migration, testing alignment, documentation updates, generated artifact refreshes, branding updates, and commit-policy workflow improvements.

Key outcomes:

  • Added CLI artifact provenance verification against the install manifest.
  • Refactored CLI parser and command flow for clearer structure and maintainability.
  • Reworked frontmatter internals by introducing a serializer module and removing the old builder path.
  • Updated tests across CLI, artifacts, frontmatter, and template generation to match the refactors.
  • Regenerated installed artifacts and removed stale freeze/unfreeze skill remnants.
  • Standardized docs direction (Mermaid-first guidance), refreshed README branding/header, and aligned changelog style.
  • Centralized commit/branch policy in cchk.toml and enabled local commit-msg + pre-push checks.
  • Removed hard scope allowlist enforcement in CI (scope naming now guidance-level, not a hard gate).

Scope of change:

  • 160 files changed
  • 2617 insertions, 1195 deletions

Related Issues

No linked issue.

Validation

  • Tests pass locally
  • CI checks pass
  • Docs updated (if needed)

Local verification performed:

  • Pre-commit checks passed on modified workflow/config/docs files.
  • Commit-check hook behavior validated for valid and invalid commit messages.
  • Branch-name validation confirmed in pre-push context.

Release Impact

  • feat: (minor)
  • fix: (patch)
  • BREAKING CHANGE (major)
  • No release impact

eschaar added 18 commits April 20, 2026 21:16
@eschaar
docs: improve language and documentation clarity
79b3a9f
@eschaar
chore(ci): improve semver release and commit policy workflows
d5c2888
@eschaar
docs(instructions): align policy boundaries and bump python template …
b92a6e1 
…version
@eschaar
feat(cli): verify artifact provenance against manifest
83c2112
@eschaar
refactor(cli): simplify install and verify control flow
dbc5ec8
@eschaar
chore(artifacts): regenerate .github outputs
d128f93
@eschaar
chore(skills): remove stale freeze and unfreeze artifacts
a76ce15
@eschaar
refactor(frontmatter): reduce nested validation and parse flow
9865c0f
@eschaar
refactor(frontmatter): rename builder to serializer for accuracy
496123f 
- FrontmatterBuilder → FrontmatterSerializer (reflects actual responsibility)
- build_output() class method → serialize() (clearer intent)
- builder.py → serializer.py (align module name with class name)
- test_builder.py → test_serializer.py (align test file name)
- Keep backward-compatible build_output() function wrapper for external usage

Improves naming clarity: FrontmatterParser parses YAML, FrontmatterSchema
validates, FrontmatterSerializer renders to YAML output. All 12 tests green.
@eschaar
refactor(frontmatter): remove build_output wrapper function
3239612 
Remove the backward-compatible build_output() wrapper function since:
- Internal usage via FrontmatterSerializer.serialize() is clearer
- Only used by tests and generator.py (both now migrated)
- Reduces surface API to single entry point

Changes:
- Remove build_output() function from serializer.py
- Update exports in __init__.py and artifacts/__init__.py
- Migrate all calls to FrontmatterSerializer.serialize()
- Update test to check FrontmatterSerializer export
- Simplify module docstring

All 71 tests green. Static methods remain for true utility functions
with no class state involvement.
@eschaar
refactor(tests): rename test class and methods to match FrontmatterSe…
397892d 
…rializer

- TestBuildOutput → TestFrontmatterSerializer
- test_build_output_* → test_serialize_*
- Update docstrings to be more descriptive
- Module doc: 'Tests for frontmatter builder behavior' → 'Tests for FrontmatterSerializer behavior'

All test behavior unchanged; pure renaming for consistency with FrontmatterSerializer API.
All 11 tests green.
@eschaar
refactor(frontmatter): convert serializer to instance methods
59df8a2 
- All methods: @staticmethod/@classmethod → instance methods
- All FrontmatterSerializer._ references → self._
- Updated 11 call sites in test_serializer.py
- Updated 2 call sites in generator.py
- Behavior unchanged; semantically clearer instance pattern
- All 11 serializer tests + 30 artifact generator tests passing
@eschaar
refactor(cli): convert parser functions to CLIParser class
bc30b99 
- Created CLIParser class with instance methods: vscode_user_dir(), resolve_targets(), build()
- Renamed _vscode_user_dir() → vscode_user_dir() (removed leading underscore)
- Updated main.py: instantiate CLIParser() and call instance methods
- Updated parser tests to use CLIParser() instances and patch class methods
- Updated main tests to patch CLIParser.build and CLIParser.resolve_targets
- Updated skills test to verify both AUTO-GENERATED and VSTACK-META footers
- All 194 tests passing
@eschaar
refactor(docs): align docstrings and repo guidance
4c61f3f 
- add repo-wide Python docstring guidance to copilot instructions
- align docs with code as source of truth for frontmatter and manifest behavior
- complete CommandLineParser rename across code and tests
- improve public Python docstrings toward PEP 257, PEP 287, and selective Google-style sections
- fix install/verify metadata drift for skipped artifacts with stale footer versions
- add focused tests to preserve 100 percent coverage
- include regenerated .github/vstack.json manifest
@eschaar
docs: align markdown documentation style
4c0bdea 
- improve README structure and correct non-PyPI distribution guidance
- move gstack attribution lower in the README and link to the upstream repo
- add repo-wide Markdown documentation style guidance for Mermaid vs ASCII usage
- modernize architecture, workflow, and design docs with Mermaid flow diagrams
- keep repository and directory structure views as ASCII text where more readable
@eschaar
refactor(skills): adopt Mermaid-first diagram convention
7cbd60e 
- add a shared diagram convention to the skill context partial
- replace explicit ASCII-first guidance in architecture, vision, design, and explore templates
- keep ASCII as a fallback and for scan-friendly tree structures
- bump skill artifact versions so downstream installs receive the convention update
- regenerate .github skill artifacts and manifest from the updated templates
@eschaar
docs(readme): add logo and centered badge header
9df41e0 
- add assets/branding/ with light and dark wordmark PNGs
- use picture element with prefers-color-scheme for automatic light/dark switching
- center logo and badges together in a single div block
@eschaar
chore(ci): centralize commit-check policy
e6d0658 
- move commit and branch policy to cchk.toml
- add local pre-commit hooks for commit-msg and pre-push checks
- remove hard CI scope allowlist enforcement
- update changelog 1.2.0 to reflect policy changes
Copilot AI review requested due to automatic review settings April 20, 2026 23:30
Copilot AI reviewed Apr 20, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR consolidates a broad set of refactors and documentation updates across vstack’s CLI/runtime, artifact generation (frontmatter + provenance metadata), commit-policy automation, and repo documentation/templates.

Changes:

  • Refactors CLI parsing/dispatch and enhances install/verify with manifest-aware provenance checks via a new VSTACK-META footer.
  • Replaces the old frontmatter builder with FrontmatterSerializer, updates schema validation helpers, and aligns tests accordingly.
  • Updates templates and docs toward Mermaid-first diagrams, adds commit/branch policy config (cchk.toml) + new commit workflow, and refreshes generated .github/* artifacts.

Reviewed changes

Copilot reviewed 156 out of 160 changed files in this pull request and generated 7 comments.

Show a summary per file
File Description
tests/vstack/test_models.py Updates test module docstring wording for consistency.
tests/vstack/test_main.py Updates docstrings and adapts tests to CommandLineParser-based parser build/target resolution.
tests/vstack/test_constants.py Updates test module docstring wording for consistency.
tests/vstack/test___main__.py Updates test module docstring wording for consistency.
tests/vstack/test___init__.py Updates test module docstring wording for consistency.
tests/vstack/skills/test_templates.py Adjusts generated-skill footer assertions for new VSTACK-META metadata.
tests/vstack/skills/test_models.py Updates test module docstring wording for consistency.
tests/vstack/skills/test_generator.py Updates test module docstring wording for consistency.
tests/vstack/skills/test_constants.py Updates test module docstring wording for consistency.
tests/vstack/skills/test_config.py Updates test module docstring wording for consistency.
tests/vstack/skills/test___init__.py Updates test module docstring wording for consistency.
tests/vstack/prompts/test_generator.py Updates test module docstring wording for consistency.
tests/vstack/instructions/test_generator.py Updates test module docstring wording for consistency.
tests/vstack/frontmatter/test_serializer.py Migrates tests from build_output to FrontmatterSerializer and adds serializer behavior coverage.
tests/vstack/frontmatter/test_schema.py Adds schema validation coverage for object-list mappings without item schema.
tests/vstack/frontmatter/test_parser.py Updates test module docstring wording for consistency.
tests/vstack/frontmatter/test___init__.py Updates re-export tests to expect FrontmatterSerializer instead of build_output.
tests/vstack/cli/test_parser.py Migrates CLI parser tests to CommandLineParser instance methods.
tests/vstack/cli/test_manifest.py Updates test module docstring wording for consistency.
tests/vstack/cli/test_integration_runtime.py Updates test module docstring wording for consistency.
tests/vstack/cli/test_constants.py Updates test module docstring wording for consistency.
tests/vstack/cli/test_commands.py Adds tests for manifest preservation/provenance verification and updates docstrings/test doubles.
tests/vstack/cli/test___init__.py Updates test module docstring wording for consistency.
tests/vstack/artifacts/test_protocol.py Updates docstrings for clarity and consistency.
tests/vstack/artifacts/test_models.py Updates test module docstring wording for consistency.
tests/vstack/artifacts/test_generator.py Adds coverage for VSTACK-META emission/parsing behavior in generated artifacts.
tests/vstack/artifacts/test_constants.py Updates test module docstring wording for consistency.
tests/vstack/artifacts/test_config.py Updates test module docstring wording for consistency.
tests/vstack/artifacts/test___init__.py Updates test module docstring wording for consistency.
tests/vstack/agents/test_template_config_style.py Updates test module docstring wording for consistency.
tests/vstack/agents/test_generator.py Updates test module docstring wording for consistency.
tests/vstack/agents/test_generation.py Updates test module docstring wording for consistency.
tests/vstack/agents/test_constants.py Updates test module docstring wording for consistency.
tests/vstack/agents/test_config.py Updates test module docstring wording for consistency.
tests/vstack/agents/test___init__.py Updates test module docstring wording for consistency.
tests/conftest.py Updates conftest module docstring wording for consistency.
src/vstack/skills/models.py Clarifies module purpose as backward-compatible exports.
src/vstack/skills/generator.py Improves docstrings for the skill generator wrapper.
src/vstack/skills/constants.py Clarifies skill constants module purpose.
src/vstack/prompts/generator.py Improves docstrings for the prompt generator wrapper.
src/vstack/prompts/constants.py Clarifies prompt constants module purpose.
src/vstack/prompts/config.py Clarifies prompt artifact config module purpose.
src/vstack/models.py Improves docstrings for shared validation result models.
src/vstack/main.py Refactors CLI entrypoint to use CommandLineParser and improves documentation.
src/vstack/instructions/generator.py Improves docstrings for the instruction generator wrapper.
src/vstack/instructions/constants.py Clarifies instruction constants module purpose.
src/vstack/instructions/config.py Clarifies instruction artifact config module purpose.
src/vstack/frontmatter/serializer.py Introduces FrontmatterSerializer to replace the old builder path.
src/vstack/frontmatter/schema.py Refactors schema validation into helper methods; adds clearer type-specific checks.
src/vstack/frontmatter/parser.py Refactors parser block-flush logic into helper methods for maintainability.
src/vstack/frontmatter/builder.py Removes legacy build_output builder implementation.
src/vstack/frontmatter/init.py Updates exports to provide FrontmatterSerializer (and removes build_output).
src/vstack/constants.py Clarifies module purpose docstring.
src/vstack/cli/parser.py Refactors CLI parsing/target resolution into CommandLineParser class.
src/vstack/cli/manifest.py Expands/clarifies manifest models and serialization docs.
src/vstack/cli/constants.py Clarifies module purpose docstring.
src/vstack/cli/commands.py Adds manifest-aware expected output resolution and manifest-linked footer metadata verification.
src/vstack/artifacts/generator.py Adds VSTACK-META footer emission + parsing; switches to FrontmatterSerializer.
src/vstack/artifacts/config.py Clarifies manifest_key defaulting behavior in docstring.
src/vstack/artifacts/init.py Updates exports to reflect serializer migration.
src/vstack/agents/generator.py Improves docstrings for agent generator wrapper.
src/vstack/agents/constants.py Clarifies agent constants module purpose.
src/vstack/_templates/skills/vision/template.md Updates diagram guidance to prefer Mermaid with ASCII fallback.
src/vstack/_templates/skills/vision/config.yaml Bumps skill version.
src/vstack/_templates/skills/verify/config.yaml Bumps skill version.
src/vstack/_templates/skills/security/config.yaml Bumps skill version.
src/vstack/_templates/skills/requirements/config.yaml Bumps skill version.
src/vstack/_templates/skills/release-notes/config.yaml Bumps skill version.
src/vstack/_templates/skills/refactor/config.yaml Bumps skill version.
src/vstack/_templates/skills/pr/config.yaml Bumps skill version.
src/vstack/_templates/skills/performance/config.yaml Bumps skill version.
src/vstack/_templates/skills/openapi/config.yaml Bumps skill version.
src/vstack/_templates/skills/onboard/config.yaml Bumps skill version.
src/vstack/_templates/skills/migrate/config.yaml Bumps skill version.
src/vstack/_templates/skills/inspect/config.yaml Bumps skill version.
src/vstack/_templates/skills/incident/config.yaml Bumps skill version.
src/vstack/_templates/skills/guardrails/config.yaml Bumps skill version.
src/vstack/_templates/skills/explore/template.md Replaces ASCII diagram example prompt with Mermaid-first guidance.
src/vstack/_templates/skills/explore/config.yaml Bumps skill version.
src/vstack/_templates/skills/docs/config.yaml Bumps skill version.
src/vstack/_templates/skills/design/template.md Replaces ASCII ER example with Mermaid ER diagram example.
src/vstack/_templates/skills/design/config.yaml Bumps skill version.
src/vstack/_templates/skills/dependency/config.yaml Bumps skill version.
src/vstack/_templates/skills/debug/config.yaml Bumps skill version.
src/vstack/_templates/skills/container/config.yaml Bumps skill version.
src/vstack/_templates/skills/consult/config.yaml Bumps skill version.
src/vstack/_templates/skills/concise/config.yaml Bumps skill version.
src/vstack/_templates/skills/code-review/config.yaml Bumps skill version.
src/vstack/_templates/skills/cicd/config.yaml Bumps skill version.
src/vstack/_templates/skills/architecture/template.md Updates diagram guidance to Mermaid-first with ASCII fallback and replaces ASCII diagram block with Mermaid.
src/vstack/_templates/skills/architecture/config.yaml Bumps skill version.
src/vstack/_templates/skills/analyse/config.yaml Bumps skill version.
src/vstack/_templates/skills/adr/config.yaml Bumps skill version.
src/vstack/_templates/skills/_partials/skill-context.md Adds a shared Mermaid-first “Diagram Convention” section for skills.
src/vstack/_templates/instructions/python/template.md Rewords “repository” → “project” for broader applicability.
src/vstack/_templates/instructions/python/config.yaml Updates description wording and bumps instruction version.
src/vstack/_templates/instructions/git/template.md Adds a new Git/release hygiene instruction template.
src/vstack/_templates/instructions/git/config.yaml Adds config for the new git instruction.
src/vstack/main.py Updates module docstring wording for consistency.
docs/product/requirements.md Adds ownership/last-updated metadata and clarifies ownership language.
docs/design/workflow.md Documents repo automation and modernizes diagrams to Mermaid.
docs/design/skills.md Adds policy/procedure boundary rule and modernizes language.
docs/design/instructions.md Adds new design doc explaining instructions and policy/procedure boundary.
docs/design/design.md Updates generator design diagrams and documents new serializer + VSTACK-META footer.
docs/architecture/architecture.md Updates structure docs and modernizes execution model diagrams to Mermaid.
docs/architecture/adr/013-instructions-vs-skills-boundary.md Adds ADR defining policy vs procedure boundary.
cchk.toml Introduces centralized commit and branch policy configuration.
README.md Refreshes branding, quickstart, conceptual model, and Mermaid-first docs alignment.
CONTRIBUTING.md Updates commit/branch policy documentation to reflect Conventional Commits and CI enforcement.
CHANGELOG.md Adds a new 1.2.0 entry describing the consolidated changes.
.pre-commit-config.yaml Adds local commit-check hooks for commit-msg and pre-push validation.
.github/workflows/verify.yml Makes Poetry venv location deterministic via POETRY_VIRTUALENVS_IN_PROJECT.
.github/workflows/release.yml Migrates SemVer computation action and tightens tag policy behavior.
.github/workflows/qa.yml Adds comments and makes Poetry venv location deterministic.
.github/workflows/commit.yml Adds a new workflow to validate commit/branch policy on non-main pushes.
.github/vstack.json Refreshes generated install manifest with updated artifact versions/types.
.github/skills/vision/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/verify/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/unfreeze/SKILL.md Removes stale generated skill artifact.
.github/skills/security/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/requirements/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/release-notes/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/refactor/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/pr/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/performance/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/openapi/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/onboard/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/migrate/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/freeze/SKILL.md Removes stale generated skill artifact.
.github/skills/explore/SKILL.md Regenerated skill artifact: adds diagram convention + Mermaid-first guidance + VSTACK-META footer.
.github/skills/docs/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/design/SKILL.md Regenerated skill artifact: adds diagram convention + Mermaid ER example + VSTACK-META footer.
.github/skills/dependency/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/debug/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/container/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/consult/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/concise/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/code-review/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/cicd/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/architecture/SKILL.md Regenerated skill artifact: adds diagram convention + Mermaid diagrams + VSTACK-META footer.
.github/skills/analyse/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/skills/adr/SKILL.md Regenerated skill artifact: adds diagram convention + VSTACK-META footer.
.github/prompts/code-review.prompt.md Regenerated prompt artifact: appends VSTACK-META footer.
.github/instructions/python.instructions.md Regenerated instruction artifact: updated description + VSTACK-META footer.
.github/instructions/git.instructions.md Adds regenerated git instruction artifact + VSTACK-META footer.
.github/dependabot.yml Adds Dependabot config for pip and GitHub Actions ecosystems.
.github/copilot-instructions.md Adds repo-wide Markdown documentation style and Python docstring style guidance.
.github/agents/tester.agent.md Regenerated agent artifact: formatting tweaks + VSTACK-META footer.
.github/agents/release.agent.md Regenerated agent artifact: formatting tweaks + VSTACK-META footer.
.github/agents/product.agent.md Regenerated agent artifact: formatting tweaks + VSTACK-META footer.
.github/agents/engineer.agent.md Regenerated agent artifact: formatting tweaks + VSTACK-META footer.
.github/agents/designer.agent.md Regenerated agent artifact: formatting tweaks + VSTACK-META footer.
.github/agents/architect.agent.md Regenerated agent artifact: formatting tweaks + VSTACK-META footer.

Comment thread docs/design/workflow.md Outdated
Comment thread docs/design/instructions.md Outdated
Comment thread tests/vstack/skills/test_templates.py Outdated
Comment thread docs/design/workflow.md Outdated
Comment thread docs/design/skills.md Outdated
Comment thread CONTRIBUTING.md Outdated
Comment thread CHANGELOG.md Outdated
@eschaar
chore(docs): align markdown links and policy text
ecff1d0 
- fix relative markdown links under docs/design to resolve correctly on GitHub
- update CONTRIBUTING commit-scope wording to match cchk.toml enforcement model
- strengthen generated skill footer test to assert footer structure at end-of-file
@eschaar
eschaar merged commit ab1cefb into main Apr 20, 2026
12 checks passed
@eschaar
eschaar deleted the fix/documentation-language-consistency branch April 20, 2026 23:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@eschaar