@raishin/vanguard-frontier-agentic 2.5.0 → 2.7.0

package/.agents/tasks/task-dynamic-kiro-powers/2025-01-24-120000-review.md

@@ -0,0 +1,92 @@
+# Dynamic Kiro Powers generator
+
+The generator was previously hardcoded to 15 providers. This change makes it scan `catalog/agents.json` at generate-time, discovering all 32 providers with a `kiro` harness, and auto-deriving steering content (displayName, description, keywords, invariants) for the 17 providers that lack hand-authored entries. A merged map of hand-authored + derived entries drives the iteration loop, and a new `renderReadme()` produces an alphabetically-sorted README reflecting the full set.
+
+Watch for: mid-word truncation in 10 of 17 derived descriptions produces broken text visible in frontmatter (confirmed); grammar error "All 1 agents" for single-agent providers (confirmed); template renders maestro-routing guidance even for maestro-less providers, creating contradictory body text (confirmed, but pre-existing pattern extended to new providers).
+
+## High-level view
+
+The description-generation logic for single-agent providers has a truncation path that cuts at 120 characters without respecting word boundaries, producing mid-word breaks like `secre...` and `t...` that appear literally in the POWER.md frontmatter `description` field. Ten of the seventeen derived providers hit this path. The descriptions pass the 3-sentence validator (the `...` doesn't count as a sentence terminator) but the output is visually broken and semantically incomplete.
+
+The template-rendering path (`renderPower`) emits maestro guidance ("Use the maestro as the entry point...") unconditionally, even when the bullet above says "no maestro for this provider." This PR did not introduce the pattern but propagates it to 11 additional maestro-less providers, making the contradiction more visible and more likely to confuse Kiro's AI routing.
+
+The `adapterNote` string has no singular branch — when a provider has exactly 1 agent, the output reads "All 1 agents in this provider ship a Kiro adapter" across 10 new providers.
+
+<details>
+<summary>Issues (3)</summary>
+
+1. **Mid-word description truncation** — `core.substring(0, 117) + "..."` cuts at byte offset regardless of word boundary. Truncate to the last space before 120 chars, or trim the catalog summary at a comma/list-item boundary so the description remains a coherent sentence fragment. Affects 10 of 17 new providers.
+2. **"All 1 agents" grammar** — The `adapterNote` template uses `All ${total} agents` without a singular branch. When `total === 1`, this should read "The single agent in this provider ships..." or equivalent. Affects 10 providers.
+3. **Maestro boilerplate on maestro-less providers** — The "Use the maestro as the entry point" paragraph is rendered even when the provider has no maestro. Conditionally omit or rewrite this paragraph when `maestro` is null.
+
+</details>
+
+<details>
+<summary>Details</summary>
+
+## Description truncation at 120 chars
+
+The derivation path for single-agent providers strips the catalog summary's "Agent for X." prefix, removes a leading "Review"/"Static review of" prefix, then truncates at 120 characters:
+
+```javascript
+if (core.length > 120) {
+  core = core.substring(0, 117) + "...";
+}
+```
+
+This hard cut lands mid-word. For backstage the result is `"secre..."` (cutting "secret scope"), for cert-manager `"t..."` (cutting "trust"), for cilium `"policy ..."`. The frontmatter `description` field is the primary metadata Kiro's Powers panel shows to users. A word-boundary-aware truncation (find last space before offset 117, trim there, append `"..."`) would keep descriptions readable.
+
+Only single-agent providers with long catalog summaries are affected — the multi-agent paths use `deriveTopics` which slices to 4 items and stays short.
+
+## Singular/plural grammar in adapter note
+
+`renderPower` assembles: `"All ${total} agents in this provider ship a Kiro adapter..."`. When `total === 1`, this produces "All 1 agents in this provider ship." The template distinguishes `kiroAvailable === total` vs `kiroAvailable === 0` vs partial, but never checks for the singular case. Adding a `total === 1` guard (e.g., "The single agent in this provider ships a Kiro adapter...") fixes ten affected providers.
+
+## Contradictory maestro guidance for non-maestro providers
+
+The body template always emits:
+
+```
+Use the maestro as the entry point: classify the task, then dispatch to
+one specialist or a parallel team of specialists.
+```
+
+This appears directly beneath "*(no maestro for this provider; reference agents directly under `agents/<provider>/`)*". After this PR, 11 providers render this contradictory pair (up from 2 in the base). Since Kiro's AI uses this steering text for routing decisions, the contradiction could cause it to search for a non-existent maestro agent. Conditionalizing the paragraph on `maestro !== null` eliminates the issue.
+
+## Coverage gap: no truncation quality check
+
+The Python validator checks structural constraints (3-sentence max, kebab-case, banned keywords) but has no assertion on description coherence. Mid-word truncation passes all existing checks. A simple regex check for `\w{2}\.\.\. ` (word fragment followed by ellipsis mid-sentence) would catch this class of defect.
+
+</details>
+
+<details>
+<summary>File map</summary>
+
+| File | Change |
+|------|--------|
+| `scripts/generate-kiro-powers.mjs` | +342 lines: `discoverKiroProviders`, `deriveProviderConfig`, `DISPLAY_NAME_OVERRIDES`, `DERIVED_KEYWORDS`, `buildMergedProviders`, `renderReadme`; loop changed from `PROVIDERS` to `allProviders` |
+| `powers/README.md` | Now generated (count 14 -> 32, tree alphabetized, "How to update" references dynamic count) |
+| `powers/vanguard-argocd/POWER.md` | New derived power |
+| `powers/vanguard-backstage/POWER.md` | New derived power |
+| `powers/vanguard-cert-manager/POWER.md` | New derived power |
+| `powers/vanguard-cilium/POWER.md` | New derived power |
+| `powers/vanguard-dotnet/POWER.md` | New derived power (has maestro) |
+| `powers/vanguard-falco/POWER.md` | New derived power |
+| `powers/vanguard-fluxcd/POWER.md` | New derived power |
+| `powers/vanguard-generic/POWER.md` | New derived power |
+| `powers/vanguard-hr/POWER.md` | New derived power (has maestro) |
+| `powers/vanguard-istio/POWER.md` | New derived power |
+| `powers/vanguard-kyverno/POWER.md` | New derived power |
+| `powers/vanguard-legal/POWER.md` | New derived power (has maestro) |
+| `powers/vanguard-marketing/POWER.md` | New derived power (has maestro) |
+| `powers/vanguard-multi-cloud/POWER.md` | New derived power (has maestro) |
+| `powers/vanguard-opentelemetry/POWER.md` | New derived power |
+| `powers/vanguard-prometheus/POWER.md` | New derived power |
+| `powers/vanguard-sigstore/POWER.md` | New derived power |
+| `.agents/tasks/task-dynamic-kiro-powers/context.json` | Task context metadata |
+| `.agents/tasks/task-dynamic-kiro-powers/features/FEAT-001.json` | Feature spec |
+| `.agents/tasks/task-dynamic-kiro-powers/task.json` | Task tracker |
+
+Full diff: `git diff 8e0a7fc..HEAD`
+
+</details>

package/.agents/tasks/task-dynamic-kiro-powers/context.json

@@ -0,0 +1,22 @@
+{
+  "project_type": "Multi-platform agent marketplace (Node.js scripts, Python validators)",
+  "language": "JavaScript (ESM) for generator, Python for validator",
+  "build_system": "npm scripts - no compile step, just generator + validators",
+  "test_framework": "Python validator scripts (tests/validate-kiro-powers.py) plus generator --check mode",
+  "build_command": "NODE_OPTIONS=\"\" node scripts/generate-kiro-powers.mjs",
+  "test_command": "NODE_OPTIONS=\"\" python3 tests/validate-kiro-powers.py",
+  "verification_instructions": "1. Run NODE_OPTIONS=\"\" node scripts/generate-kiro-powers.mjs to generate powers. 2. Run NODE_OPTIONS=\"\" python3 tests/validate-kiro-powers.py to validate. 3. Run NODE_OPTIONS=\"\" node scripts/generate-kiro-powers.mjs --check to confirm idempotency.",
+  "snapshot_or_generated_files": "powers/*/POWER.md and powers/README.md are generated files. Command: node scripts/generate-kiro-powers.mjs",
+  "setup_instructions": "No setup needed - Node.js and Python3 are pre-installed",
+  "environment_constraints": "Must prefix node commands with NODE_OPTIONS=\"\" due to sandbox preload issue",
+  "contribution_requirements": "Generated powers must conform to strict-5 frontmatter (name, displayName, description, keywords, author). Description max 3 sentences. Keywords must be specific, not broad (avoid: cloud, code, devops, infrastructure, infra, agent, agents, ai, ml, ops, automation, tool, tools, general). Names must be kebab-case.",
+  "key_patterns": "Generator uses a PROVIDERS object with hand-authored steering (displayName, description, keywords, invariants). renderPower() creates frontmatter + body. summarize() reads catalog for agent counts, maestro, live-guards. renderReadme() generates powers/README.md from PROVIDERS keys. Validator independently checks all powers/ subdirs.",
+  "relevant_files": [
+    "scripts/generate-kiro-powers.mjs",
+    "tests/validate-kiro-powers.py",
+    "catalog/agents.json",
+    "powers/README.md",
+    "powers/vanguard-aws/POWER.md"
+  ],
+  "directory_structure": "scripts/ has generators, tests/ has validators, catalog/agents.json is the source of truth for all agents, powers/ has generated POWER.md files per provider"
+}

package/.agents/tasks/task-dynamic-kiro-powers/features/FEAT-001.json

@@ -0,0 +1,34 @@
+{
+  "id": "FEAT-001",
+  "type": "fix",
+  "description": "Make the Kiro Powers generator fully dynamic so it auto-generates Powers for ALL 32 providers in catalog/agents.json that have 'kiro' in their harnesses array, not just the 15 hardcoded in the PROVIDERS object.",
+  "status": "completed",
+  "steps": [
+    "Step 1: In scripts/generate-kiro-powers.mjs, add a function that reads catalog/agents.json and discovers all unique providers where at least one agent has 'kiro' in its harnesses array. This should happen dynamically at generate-time.",
+    "Step 2: Add a function (e.g. `deriveProviderConfig`) that auto-generates steering content for providers NOT already in the hardcoded PROVIDERS object. The logic should be: (a) displayName: title-case the provider name with 'Vanguard Frontier -- ' prefix (use actual double-hyphen-space, e.g. 'Vanguard Frontier -- ArgoCD' becomes 'Vanguard Frontier \\u2014 ArgoCD' using em-dash matching existing convention). For multi-word names like 'multi-cloud' or 'cert-manager', convert to title case: 'Multi-Cloud', 'Cert-Manager'. For abbreviations like 'dotnet' use '.NET', 'hr' use 'HR', 'fluxcd' use 'FluxCD', 'argocd' use 'ArgoCD', 'opentelemetry' use 'OpenTelemetry'. (b) description: Generate from catalog data - max 3 sentences. Pattern: describe what the agents do based on agent IDs/summaries, mention maestro routing if present, note whether it has live-guard agents. Keep under 3 sentences. (c) keywords: Derive from provider name and agent IDs. Must be specific, NOT broad. Avoid the banned list: cloud, code, devops, infrastructure, infra, agent, agents, ai, ml, ops, automation, tool, tools, general. (d) invariants: Generate sensible defaults - if no live-guards, focus on review-only / static-analysis invariants. If has maestro, mention routing through maestro. If has live-guards, include the standard live-guard discipline bullet.",
+    "Step 3: Build a merged PROVIDERS-like map that combines the hand-authored PROVIDERS entries (unchanged) with the auto-derived entries for missing providers. The final iteration loop should use this merged map instead of just PROVIDERS.",
+    "Step 4: Update the loop at the bottom of the generator that iterates `Object.entries(PROVIDERS)` to instead iterate the merged map (all 32 providers). The renderPower and renderReadme functions should work with this merged map.",
+    "Step 5: Make sure the renderReadme function uses the merged map (all 32 providers) so the README.md accurately reflects the full count.",
+    "Step 6: The auto-derived descriptions MUST comply with the strict-5 spec: max 3 sentences for description, kebab-case name, specific non-broad keywords. Test each derived entry mentally.",
+    "Step 7: Run `NODE_OPTIONS=\"\" node scripts/generate-kiro-powers.mjs` and verify it generates 32 Power directories under powers/.",
+    "Step 8: Run `NODE_OPTIONS=\"\" python3 tests/validate-kiro-powers.py` and confirm all 32 Powers pass validation.",
+    "Step 9: Run `NODE_OPTIONS=\"\" node scripts/generate-kiro-powers.mjs --check` and confirm it reports all 32 Powers in sync (idempotency check)."
+  ],
+  "acceptance_criteria": [
+    "Running `NODE_OPTIONS=\"\" node scripts/generate-kiro-powers.mjs` produces 32 POWER.md files under powers/ (one per kiro-enabled provider)",
+    "Running `NODE_OPTIONS=\"\" python3 tests/validate-kiro-powers.py` passes with OK status for all 32 Powers",
+    "Running `NODE_OPTIONS=\"\" node scripts/generate-kiro-powers.mjs --check` exits 0 (all Powers in sync)",
+    "The 15 existing hand-authored providers (aws, azure, gcp, oci, alibaba, huawei, ovhcloud, scaleway, hetzner, contabo, ionos, kubernetes, terraform, nvidia, salesforce) retain their exact same steering content unchanged",
+    "The 17 new providers (argocd, backstage, cert-manager, cilium, dotnet, falco, fluxcd, generic, hr, istio, kyverno, legal, marketing, multi-cloud, opentelemetry, prometheus, sigstore) each get auto-generated Powers with valid strict-5 frontmatter",
+    "No generated keyword is in the broad-keywords banned list",
+    "No generated description exceeds 3 sentences",
+    "All generated names are lowercase kebab-case matching pattern 'vanguard-<provider>'"
+  ],
+  "verification": [
+    "NODE_OPTIONS=\"\" node scripts/generate-kiro-powers.mjs",
+    "NODE_OPTIONS=\"\" python3 tests/validate-kiro-powers.py",
+    "NODE_OPTIONS=\"\" node scripts/generate-kiro-powers.mjs --check"
+  ],
+  "blocked_reason": null,
+  "findings": "All 32 providers generate successfully. The generator outputs '33 Kiro Powers (+ README.md)' because it counts 32 POWER.md files + 1 README.md in the written array. The validator correctly reports 32 Powers. Single-agent providers use their catalog summary (second sentence if first is 'Agent for <id>.') with truncation to 120 chars. All descriptions pass the 3-sentence validator."
+}

package/.agents/tasks/task-dynamic-kiro-powers/task.json

@@ -0,0 +1,14 @@
+{
+  "task_id": "task-dynamic-kiro-powers",
+  "task_description": "Make the Kiro Powers generator fully dynamic so it auto-generates Powers for ALL providers in catalog/agents.json that have 'kiro' in their harnesses array, not just the 15 hardcoded in the PROVIDERS object. This fixes the bug where 17 providers with Kiro adapters have no Power generated.",
+  "status": "completed",
+  "feature_order": ["FEAT-001"],
+  "blocked_reason": null,
+  "verification": {
+    "build": "pass",
+    "tests": "pass",
+    "test_quality": "pass",
+    "docker_build": "skipped",
+    "summary": "Generator produces 32 Powers (up from 15). Validator confirms all 32 pass strict-5 frontmatter, kebab-case, max-3-sentence, non-broad-keyword checks. Idempotency check (--check) passes. Review fixes applied: word-boundary truncation, singular grammar for single-agent providers, conditional maestro boilerplate."
+  }
+}

package/.agents/tasks/task-jekyll-docs-site/2025-07-17-review.md

@@ -0,0 +1,118 @@
+# Jekyll documentation site for GitHub Pages
+
+A complete documentation system added to the repository: Jekyll infrastructure (`_config.yml`, `Gemfile`, root `index.md`), a GitHub Actions workflow for Pages deployment, 14 documentation pages in `docs/`, and 2 ADRs in `docs/adr/`. The approach uses the official GitHub Pages deployment pattern (OIDC token exchange, `actions/deploy-pages`) with a minima-themed Jekyll build triggered by path-filtered pushes to master.
+
+Watch for: The `_config.yml` `header_pages` reference three files that don't exist (confirmed), the workflow path filter `"*.md"` is broader than intended and will trigger on any root-level Markdown change including `CHANGELOG.md` (confirmed), and pre-existing docs without Jekyll front matter will be processed by Jekyll and may render incorrectly or generate unexpected URLs (likely).
+
+## High-level view
+
+The `_config.yml` has a structural mismatch: `header_pages` lists five paths, but only two exist in the repository. The first three (`docs/architecture/index.md`, `docs/strategy/index.md`, `docs/integrations/index.md`) will produce broken navigation links. None of the 14 new documentation pages appear in this list, so the site header provides no path to the actual documentation.
+
+The build will process all Markdown files in `docs/` including ~20 pre-existing files that lack Jekyll front matter. These become uncontrolled public pages with incorrect formatting. The `_config.yml` excludes many directories but does nothing to filter which files within `docs/` are built.
+
+The workflow trigger includes `"*.md"` which matches any root-level Markdown file. Since `CHANGELOG.md` is auto-updated by semantic-release, the Pages workflow fires on every release. The workflow's security posture is otherwise sound (OIDC, pinned actions, least-privilege), but no `Gemfile.lock` is committed, making gem resolution non-deterministic across builds.
+
+<details>
+<summary>Issues (6)</summary>
+
+1. **Broken header navigation** — `_config.yml` `header_pages` references `docs/architecture/index.md`, `docs/strategy/index.md`, and `docs/integrations/index.md` which do not exist. Remove or replace with paths to actual files. (confirmed)
+2. **Overly broad path trigger** — Workflow path filter `"*.md"` will trigger on `CHANGELOG.md` changes from every release. Replace with explicit file list or narrower glob like `"index.md"`. (confirmed)
+3. **Pre-existing docs processed by Jekyll** — ~20 existing Markdown files in `docs/` lack front matter and will be processed by Jekyll into the built site with default layouts. Either exclude them in `_config.yml` or accept uncontrolled output pages. (likely)
+4. **New docs pages absent from header_pages** — The 14 new documentation pages are not referenced in `_config.yml` `header_pages`, so the minima theme header won't link to them. Navigation depends entirely on users finding `docs/index.md`. (confirmed)
+5. **Spurious workflow triggers from CHANGELOG.md** — `_config.yml` excludes `CHANGELOG.md` from Jekyll processing, but the workflow trigger still fires when it changes. The build runs unnecessarily on every release. (confirmed)
+6. **Missing Gemfile.lock** — No lockfile is committed. `bundler-cache: true` in the workflow caches based on `Gemfile.lock`, but without one, gem resolution is non-deterministic. A malicious or broken gem update could affect the build silently. Commit a `Gemfile.lock`. (confirmed)
+
+</details>
+
+<details>
+<summary>Details</summary>
+
+## `_config.yml` navigation mismatch
+
+The `header_pages` configuration lists five files for the minima theme navigation bar:
+
+```yaml
+header_pages:
+  - docs/architecture/index.md
+  - docs/strategy/index.md
+  - docs/integrations/index.md
+  - docs/taxonomy.md
+  - docs/compatibility.md
+```
+
+`docs/architecture/index.md` does not exist — there is a `docs/architecture.md` (new, with front matter) and a directory `docs/architecture/` containing only `legal-hr-agent-communication.md` and `legal-hr-agent-routing.md`. `docs/strategy/index.md` does not exist — the directory has `finops-maestro-board-memo.md` and similar. `docs/integrations/index.md` does not exist — the directory has `installation-guide.md`, `multi-harness-adapter-pattern.md`, `skills-cli.md`.
+
+The two files that do exist (`docs/taxonomy.md`, `docs/compatibility.md`) are pre-existing files without Jekyll front matter, so they render in the header but produce pages without proper title metadata.
+
+A visitor arriving at the deployed site sees a broken or stale navigation bar with no path to the actual documentation. The `docs/index.md` page's internal links work, but only if users find it via the root `index.md` link.
+
+## Workflow path filter scope
+
+```yaml
+paths:
+  - "docs/**"
+  - "_config.yml"
+  - "Gemfile"
+  - "index.md"
+  - "*.md"
+```
+
+The `"*.md"` glob matches all root-level Markdown files. The repository root contains `CHANGELOG.md`, `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and `CODE_OF_CONDUCT.md`. The semantic-release workflow updates `CHANGELOG.md` on every version bump, meaning every release triggers a Pages deployment even when no documentation changed. Any change to `README.md` (common in PRs that update badge counts) also triggers the workflow.
+
+The `"index.md"` entry already covers the root index file specifically — the `"*.md"` entry is redundant for that purpose and introduces the over-triggering.
+
+## Pre-existing docs without front matter
+
+The `docs/` directory contains approximately 20 pre-existing Markdown files (`branch-protection.md`, `cross-harness-skills.md`, `evidence-output-spec.md`, `execution-tiers.md`, `least-privilege-rbac.md`, `npm-oidc-trusted-publishing.md`, `quality-bar.md`, `release-versioning.md`, `security-notes.md`, etc.) plus subdirectories (`architecture/`, `strategy/`, `integrations/`, `live-agents/`, `pricing-api-research/`, `admission-policies/`). None have Jekyll front matter.
+
+Jekyll processes these files regardless. Without front matter, they become part of the deployed site at their natural URL paths with no title metadata and no layout wrapper (or the default layout, depending on minima's behavior for front-matter-less files). This creates an uncontrolled surface: internal project documents appear on the public GitHub Pages site.
+
+The fix is either adding these file paths or glob patterns to `_config.yml`'s `exclude` list, or restructuring so that only files with front matter are published (which is not Jekyll's default behavior — Jekyll processes all `.md` files in non-excluded directories).
+
+## Missing Gemfile.lock
+
+The `Gemfile` declares:
+
+```ruby
+gem "jekyll", "~> 4.3"
+gem "minima", "~> 2.5"
+gem "jekyll-seo-tag"
+```
+
+Without a committed `Gemfile.lock`, every CI run resolves gems fresh. The `ruby/setup-ruby` action's `bundler-cache: true` looks for `Gemfile.lock` to generate the cache key — without it, caching may not work as intended, and gem versions float between builds. Running `bundle install` locally and committing the lockfile pins versions deterministically.
+
+</details>
+
+<details>
+<summary>Files changed (24)</summary>
+
+| File | What changed |
+|------|-------------|
+| `.agents/tasks/task-jekyll-docs-site/context.json` | Task context metadata for the documentation task |
+| `.agents/tasks/task-jekyll-docs-site/features/FEAT-001.json` | Feature spec for Jekyll infrastructure |
+| `.agents/tasks/task-jekyll-docs-site/features/FEAT-002.json` | Feature spec for documentation content |
+| `.agents/tasks/task-jekyll-docs-site/task.json` | Task orchestration state |
+| `.github/workflows/jekyll-gh-pages.yml` | GitHub Actions workflow for Pages deployment |
+| `Gemfile` | Ruby gem declarations for Jekyll build |
+| `_config.yml` | Jekyll site configuration |
+| `index.md` | Root Jekyll homepage |
+| `docs/index.md` | Documentation hub landing page |
+| `docs/getting-started.md` | Installation and first-use guide |
+| `docs/architecture.md` | Three-layer architecture documentation |
+| `docs/configuration.md` | Configuration reference |
+| `docs/deployment.md` | npm publishing and release flow |
+| `docs/github-pages.md` | GitHub Pages setup guide |
+| `docs/security.md` | Supply chain security and threat model |
+| `docs/testing.md` | Validation gates reference |
+| `docs/operations-runbook.md` | Release operations and recovery |
+| `docs/troubleshooting.md` | Common issues and fixes |
+| `docs/contributing.md` | Contribution guide for docs |
+| `docs/governance.md` | Decision-making and maintainer roles |
+| `docs/roadmap.md` | Planned work and proposals |
+| `docs/faq.md` | Frequently asked questions |
+| `docs/adr/0001-initial-architecture.md` | ADR for three-layer Maestro architecture |
+| `docs/adr/0002-documentation-site-with-jekyll-github-pages.md` | ADR for Jekyll + GitHub Pages choice |
+
+Full diff: `git diff HEAD~4`
+
+</details>

package/.agents/tasks/task-jekyll-docs-site/context.json

@@ -0,0 +1,30 @@
+{
+  "project_type": "Node.js/Python hybrid - Enterprise AI agent ecosystem with 404 skills, 426 agents across 32 providers",
+  "language": "Markdown/JSON primary, JavaScript (Node.js ESM scripts), Python (validation scripts)",
+  "build_system": "npm scripts for validation/generation, no compile step - this is a content package",
+  "test_framework": "Python validation scripts (tests/validate-*.py), Node.js fuzz tests (fast-check), smoke tests",
+  "build_command": "npm run validate (17 validation gates)",
+  "test_command": "npm run validate && npm run test:fuzz",
+  "verification_instructions": "1. Run npm run validate to confirm all 17 gates pass. 2. For docs specifically: check that new .md files have valid frontmatter. 3. Verify _config.yml is valid YAML. 4. Verify Gemfile has correct gem declarations. 5. Verify workflow YAML is valid.",
+  "snapshot_or_generated_files": "catalog/asset-integrity.json - regenerate with: python3 tests/validate-asset-integrity.py --write",
+  "setup_instructions": "git clone, npm install (devDependencies for semantic-release/fast-check), python3 available for validation scripts",
+  "environment_constraints": "OPEN_INTERNET network mode - full access. Ruby 3.4.4 available via mise. Node.js 22 default. Python 3.11 default.",
+  "contribution_requirements": "Update catalog JSON when adding assets. Regenerate asset integrity after changes to root files. Do not add secrets. Keep README human-friendly.",
+  "key_patterns": "Default branch is master (not main). Existing docs/ directory has content - do NOT delete existing files. Least-privilege permissions in all workflows. Pin actions by SHA. Use ubuntu-latest runners. Comprehensive YAML comments in workflows.",
+  "relevant_files": [
+    "docs/",
+    ".github/workflows/ci.yml",
+    ".github/workflows/release.yml",
+    "package.json",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "AGENTS.md",
+    "README.md",
+    "docs/architecture/",
+    "docs/strategy/",
+    "catalog/agents.json",
+    "catalog/skills.json",
+    "schemas/"
+  ],
+  "directory_structure": "agents/ (426 agents in 34 provider dirs), skills/ (404 skills in 36 dirs), powers/ (Kiro Powers), catalog/ (machine-readable indexes), schemas/ (JSON Schema), mcp/ (MCP references), rules/ (harness rules), scripts/ (build/gen), tests/ (validation), templates/ (starter templates), docs/ (existing docs), .github/workflows/ (10 existing workflows)"
+}

package/.agents/tasks/task-jekyll-docs-site/features/FEAT-001.json

@@ -0,0 +1,28 @@
+{
+  "id": "FEAT-001",
+  "type": "chore",
+  "description": "Create Jekyll site infrastructure: _config.yml, Gemfile, root index.md, and GitHub Actions workflow for GitHub Pages deployment",
+  "status": "completed",
+  "steps": [
+    "Create _config.yml at repository root with: title 'Vanguard Frontier Agentic', baseurl '/vanguard-frontier-agentic', theme minima, markdown kramdown, plugins [jekyll-seo-tag], include [docs], exclude [node_modules, tests, agents, skills, powers, catalog, schemas, mcp, rules, scripts, templates, assets, plugins, .claude, .codex, .cursor-plugin, .claude-plugin, .agents, package.json, package-lock.json]. Add navigation with links to all documentation pages.",
+    "Create Gemfile at repository root with: source 'https://rubygems.org', gem 'jekyll' (~> 4.3), gem 'minima' (~> 2.5), group :jekyll_plugins with gem 'jekyll-seo-tag'",
+    "Create index.md at repository root as the Jekyll site homepage with layout: home, front matter, and brief intro pointing to docs/index.md for full documentation",
+    "Create .github/workflows/jekyll-gh-pages.yml with: trigger on push to master (path filters for docs/**, _config.yml, Gemfile, index.md) plus workflow_dispatch, least-privilege permissions (contents: read, pages: write, id-token: write), concurrency group for github-pages, single build-deploy job using actions/configure-pages, ruby setup, bundle install, jekyll build, actions/upload-pages-artifact, actions/deploy-pages. Pin all actions by SHA. Use github-pages environment with url output. Include comprehensive comments."
+  ],
+  "acceptance_criteria": [
+    "_config.yml exists at repo root and is valid YAML with correct baseurl '/vanguard-frontier-agentic'",
+    "Gemfile exists at repo root with jekyll and minima gems declared",
+    "index.md exists at repo root with Jekyll front matter (layout: home)",
+    ".github/workflows/jekyll-gh-pages.yml exists with correct trigger on master, path filters, least-privilege permissions, concurrency control, and official GitHub Pages actions",
+    "Workflow uses actions pinned by SHA with version comments",
+    "Workflow includes github-pages environment with url output"
+  ],
+  "verification": [
+    "Run: python3 -c \"import yaml; yaml.safe_load(open('_config.yml'))\" to confirm valid YAML",
+    "Run: cat Gemfile | grep jekyll to confirm gem declarations",
+    "Run: python3 -c \"import yaml; yaml.safe_load(open('.github/workflows/jekyll-gh-pages.yml'))\" to confirm valid workflow YAML",
+    "Inspect workflow for: on.push.branches containing master, permissions block, concurrency block, environment: github-pages"
+  ],
+  "blocked_reason": null,
+  "findings": "Pre-existing validation failures: validate:plugin-manifest fails due to stale plugin.json version (2.5.0 vs 2.6.0). This is unrelated to docs changes. Node.js requires MISE_NODE_VERIFY=false to install. Python 3.11+ needed for tomllib in validation scripts. The mise.toml was NOT committed as it was only needed for local env setup."
+}

package/.agents/tasks/task-jekyll-docs-site/features/FEAT-002.json

@@ -0,0 +1,44 @@
+{
+  "id": "FEAT-002",
+  "type": "docs",
+  "description": "Create the complete enterprise-grade documentation site content: 14 documentation pages plus 2 ADRs in docs/adr/",
+  "status": "completed",
+  "steps": [
+    "Create docs/index.md - Documentation site homepage with layout: default, title, navigation overview linking to all pages, catalog stats (404 skills, 426 agents, 32 providers), project summary, and quick links to key sections",
+    "Create docs/getting-started.md - Getting started guide covering: prerequisites (Node.js, Python3), installation (npm install @raishin/vanguard-frontier-agentic or git clone), first use with each supported harness (Claude Code, Codex, Copilot, Cursor, Gemini CLI, Kiro), vfa-export-agents CLI usage with --platform/--role/--provider flags, verification steps. Include 'What can go wrong' section.",
+    "Create docs/architecture.md - Architecture documentation with Mermaid diagrams showing: three-layer system (Maestro router -> Specialist agents -> Cross-functional protocol), skill/agent directory structure, catalog indexing flow, multi-harness adapter pattern, the refusal-by-default safety model. Reference actual files: catalog/index.json, schemas/*.schema.json, agents/<provider>/<id>/harnesses/. Include 'Enterprise reviewer notes' section.",
+    "Create docs/configuration.md - Configuration reference covering: package.json scripts (all npm run commands), catalog structure (agents.json, skills.json, install-roles.json), schema contracts (skill.schema.json, agent.schema.json), skill frontmatter fields, agent metadata.json fields, MCP reference structure, CLAUDE.md/AGENTS.md steering files. All backed by actual file references.",
+    "Create docs/deployment.md - Deployment guide covering: npm publishing via semantic-release (release.yml), OIDC trusted publishing flow, npm provenance + Sigstore, SLSA L3 via artifact attestations, SPDX SBOM generation, the npm-deployment-master environment, how the chore(release) commit flow works. Include Mermaid sequence diagram of release flow.",
+    "Create docs/github-pages.md - GitHub Pages setup guide explaining: the jekyll-gh-pages.yml workflow, how to enable Pages in repo settings (Settings > Pages > Source: GitHub Actions), DNS/custom domain options, how the build process works, troubleshooting Pages deployment failures. Include 'How to verify this works' section.",
+    "Create docs/security.md - Security documentation (adversarial, CISO-proof) covering: supply chain security (OIDC, provenance, SLSA L3, Sigstore), code scanning (CodeQL), dependency management (Dependabot), OpenSSF Scorecard + Best Practices badges, branch protection, CODEOWNERS, responsible disclosure (link to SECURITY.md), no lifecycle scripts policy, asset integrity validation, MCP trust matrix. Every claim backed by workflow file reference or configuration evidence. Include 'What an attacker would try' section.",
+    "Create docs/testing.md - Testing documentation covering: the 17 validation gates (list each with description), fuzz testing with fast-check, install path smoke tests, packed artifact smoke tests, provider scope regression, maestro routing validation (357 scenarios), docs quality (markdownlint + codespell). Show how to run each: npm run validate, npm run test:fuzz, individual scripts. Include 'How to add a new validation gate' section.",
+    "Create docs/operations-runbook.md - Operations runbook covering: release process (merge to master triggers semantic-release), failed release recovery (workflow_dispatch with republish option), asset integrity regeneration, catalog refresh after skill/agent changes, how to add a new provider, how to add a new harness adapter. Include decision trees and checklists.",
+    "Create docs/troubleshooting.md - Troubleshooting guide with common issues: validate failures (stale manifest, asset integrity mismatch, broken links), release failures (OIDC token issues, npm publish errors), CI failures (Python version, Node version), plugin installation issues. Format as problem/cause/fix tables.",
+    "Create docs/contributing.md - Contributing guide that links to the main CONTRIBUTING.md but adds docs-site-specific guidance: how to add documentation pages, Jekyll conventions, front matter requirements, local preview with bundle exec jekyll serve, how docs CI works.",
+    "Create docs/governance.md - Governance documentation covering: decision-making process (ADRs), maintainer responsibilities (CODEOWNERS), release authority (semantic-release automated), security response (SECURITY.md SLA), code review requirements (branch protection), quality gates (17 CI checks must pass). Reference actual governance files.",
+    "Create docs/roadmap.md - Roadmap page with: current version (2.6.0), recent milestones, planned work areas (more providers, more harnesses, deeper MCP integration, FinOps expansion). Mark speculative items with [NEEDS OWNER INPUT]. Include 'How to propose a new direction' section.",
+    "Create docs/faq.md - FAQ covering: What is this? (not just cloud tooling - agentic coordination), How is it different from X? (comparison framing without naming competitors), Is it production-ready? (evidence-based answer citing test coverage and security posture), licensing (Apache-2.0), how to get support, relationship between skills/agents/rules/MCP references.",
+    "Create docs/adr/ directory and docs/adr/0001-initial-architecture.md - ADR documenting the three-layer architecture decision (Maestro -> Specialists -> Cross-functional), context (enterprise AI agents need coordination not just execution), decision drivers (safety, auditability, multi-cloud), consequences (complexity vs safety trade-off).",
+    "Create docs/adr/0002-documentation-site-with-jekyll-github-pages.md - ADR documenting: why Jekyll (GitHub-native, Markdown-first, no build complexity), why GitHub Pages (zero infra, integrated with repo), why not alternatives (Docusaurus requires Node build, MkDocs requires Python build, custom sites require hosting), consequences (limited to static content, theme constraints)."
+  ],
+  "acceptance_criteria": [
+    "All 14 documentation files exist in docs/ with valid Jekyll front matter (layout, title, optional permalink)",
+    "Both ADR files exist in docs/adr/ with proper ADR format (Status, Context, Decision, Consequences)",
+    "docs/architecture.md contains at least 2 Mermaid diagrams",
+    "docs/security.md references actual workflow files and configuration as evidence",
+    "docs/testing.md lists all 17 validation gates with their npm script names",
+    "Every page has Enterprise reviewer notes or How to verify sections where appropriate",
+    "No marketing fluff - every claim backed by evidence or marked [NEEDS OWNER INPUT]",
+    "Writing style is direct, technical, uses short sections and checklists",
+    "Pages reference actual file paths in the repository (not generic placeholders)"
+  ],
+  "verification": [
+    "Run: for f in docs/index.md docs/getting-started.md docs/architecture.md docs/configuration.md docs/deployment.md docs/github-pages.md docs/security.md docs/testing.md docs/operations-runbook.md docs/troubleshooting.md docs/contributing.md docs/governance.md docs/roadmap.md docs/faq.md docs/adr/0001-initial-architecture.md docs/adr/0002-documentation-site-with-jekyll-github-pages.md; do test -f \"$f\" && echo \"OK: $f\" || echo \"MISSING: $f\"; done",
+    "Run: grep -l 'layout:' docs/*.md docs/adr/*.md | wc -l - should be 16",
+    "Run: grep -c 'mermaid' docs/architecture.md - should be >= 2",
+    "Run: grep -c 'NEEDS OWNER INPUT' docs/roadmap.md - should be >= 1 (marking speculative items)",
+    "Run: grep 'validate:' docs/testing.md | wc -l - should reference the 17 validation gates"
+  ],
+  "blocked_reason": null,
+  "findings": "All 16 files created successfully. Each file has valid Jekyll front matter (layout: default, title set). All files are 80+ lines of substantive content. architecture.md has 2 Mermaid diagrams. roadmap.md has 14 NEEDS OWNER INPUT markers. testing.md references 24 validate: script names. docs/adr/ directory created for ADRs. No existing files were modified. Pre-existing docs/ files lack front matter but those are untouched."
+}

package/.agents/tasks/task-jekyll-docs-site/task.json

@@ -0,0 +1,14 @@
+{
+  "task_id": "task-jekyll-docs-site",
+  "task_description": "Build complete enterprise-grade documentation system using Jekyll, GitHub Pages, and GitHub Actions. Create 20 files total: _config.yml, Gemfile, Gemfile.lock, index.md (root), 14 docs pages, 2 ADRs, and .github/workflows/jekyll-gh-pages.yml workflow.",
+  "status": "completed",
+  "feature_order": ["FEAT-001", "FEAT-002"],
+  "blocked_reason": null,
+  "verification": {
+    "build": "pass",
+    "tests": "pass",
+    "test_quality": "pass",
+    "docker_build": "skipped",
+    "summary": "All 20+ files created. _config.yml and workflow YAML validated programmatically. Project validation gates (validate-catalog, validate-asset-integrity, validate-links, validate-mcp-trust-matrix, validate-no-lifecycle-scripts, validate-skill-manifest) all pass. Semantic review identified 6 issues - all fixed in subsequent commit. Gemfile.lock generated for deterministic builds."
+  }
+}

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Curated marketplace for cloud and zero-trust AI workflows. Skills, agents, rules, MCP references, and compliance-aware architecture across AWS, Azure, OCI, GCP, Alibaba Cloud, Huawei Cloud, Kubernetes, and Terraform.",
-    "version": "2.5.0"
+    "version": "2.7.0"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vanguard-frontier-agentic",
-  "version": "2.4.4",
+  "version": "2.6.0",
   "description": "Cloud and zero-trust agentic workflow marketplace for skills, agents, rules, MCP references, and compliance-aware architecture.",
   "author": {
     "name": "Raishin",

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vanguard-frontier-agentic",
-  "version": "2.4.4",
+  "version": "2.6.0",
   "description": "Cloud and zero-trust agentic workflow marketplace for skills, agents, rules, MCP references, and compliance-aware architecture.",
   "author": {
     "name": "Raishin",

package/.github/plugin/marketplace.json

@@ -2,7 +2,7 @@
   "$schema": "https://raw.githubusercontent.com/github/copilot-cli/main/schemas/marketplace.schema.json",
   "name": "vanguard-frontier-agentic",
   "description": "Curated marketplace for cloud and zero-trust AI workflows. 331 agents, 286 skills, and rules across AWS, Azure, OCI, GCP, Alibaba Cloud, Huawei Cloud, Kubernetes, and Terraform.",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "owner": {
     "name": "Raishin",
     "url": "https://github.com/Raishin"

package/README.md

@@ -15,6 +15,8 @@
     <a href="https://github.com/Raishin/vanguard-frontier-agentic/actions/workflows/codeql.yml"><img alt="CodeQL" src="https://github.com/Raishin/vanguard-frontier-agentic/actions/workflows/codeql.yml/badge.svg?branch=master" /></a>
     <a href="https://github.com/Raishin/vanguard-frontier-agentic/actions/workflows/install-paths-smoke.yml"><img alt="Install Paths Smoke" src="https://github.com/Raishin/vanguard-frontier-agentic/actions/workflows/install-paths-smoke.yml/badge.svg?branch=master" /></a>
     <a href="https://scorecard.dev/viewer/?uri=github.com/Raishin/vanguard-frontier-agentic"><img alt="OpenSSF Scorecard" src="https://api.securityscorecards.dev/projects/github.com/Raishin/vanguard-frontier-agentic/badge" /></a>
+    <a href="https://www.bestpractices.dev/projects/12964"><img alt="OpenSSF Best Practices" src="https://www.bestpractices.dev/projects/12964/badge" /></a>
+    <a href="https://www.bestpractices.dev/projects/12964"><img alt="OpenSSF Baseline" src="https://www.bestpractices.dev/projects/12964/baseline" /></a>
     <a href="https://github.com/Raishin/vanguard-frontier-agentic/actions/workflows/docs-quality.yml"><img alt="Docs Quality" src="https://github.com/Raishin/vanguard-frontier-agentic/actions/workflows/docs-quality.yml/badge.svg?branch=master" /></a>
     <a href="https://docs.npmjs.com/generating-provenance-statements"><img alt="npm provenance" src="https://img.shields.io/badge/npm-provenance-26a566.svg?logo=npm" /></a>
     <a href="CONTRIBUTING.md"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" /></a>