From 67b08032e802c730201028f90d3fda95ac5a905c Mon Sep 17 00:00:00 2001 From: Qwynn Marcelle Date: Fri, 31 Jul 2026 08:19:03 -0400 Subject: [PATCH] fix(meta-273): P0 accuracy release cut for all 16 authored routes Global chrome: - GitHub social link and Giscus repo updated to workspacejson/workspacejson.dev Route-by-route corrections: - index.astro: JSON-LD author to Marcelle Labs, removed Vreko founding org, added workspacejson/* repos to sameAs, fixed Codex-vs-standard category error - spec.mdx: JSON-LD author fixed, GDPR section updated from stale v0.3 fields (aiModificationCount/humanModificationCount) to v0.4 (changeCount/revertCount/fragilityScore) - audit.mdx: JSON-LD author fixed, added frozen audit surface label - getting-started.mdx: restructured to lead with @workspacejson/cli generate, repositioned agents-audit as frozen audit surface, step 3 manual heredoc repositioned from primary path to reference/fallback - ecosystem.mdx: replaced Vreko MCP with @workspacejson/codex-mcp, separated shipped consumers from hypothetical compatibility, removed duplicate Goose section, removed false Implementations cross-reference - implementations.mdx: restructured into Producers/Consumers/Validators, added @workspacejson/cli, removed duplicate Codex card - codex.mdx: JSON-LD version updated to 0.1.9, canonical links to workspacejson/integrations - faq.mdx: fileIndex -> fragility, stale v0.3 field names replaced, Vreko references contextualized, code block updated to @workspacejson/cli generate, tools list updated with shipped consumers - governance.mdx: replaced governance@ mailto with GitHub Discussions link (META-253) - blog posts: JSON-LD author fixed, factual error corrected (AGENTS.md is prescriptive, workspace.json is descriptive) - showcase/tally: added ghost Try Tally CTA, test updated for 3 hero CTAs META-253: Cloudflare email obfuscation resolved via Path 3 (disable obfuscation, replace mailto with GitHub Discussions). Scrape Shield disabled on zone. Acceptance gates: npm run build passes (schema, content, ecosystem, astro). npm run verify:site: 738 passed, 48 skipped, 0 failed. --- PLAN.md | 553 ++++++++++++++++++ astro.config.mjs | 4 +- src/content/docs/audit.mdx | 11 +- .../docs/blog/local-daemon-vs-cloud.mdx | 3 +- .../docs/blog/workspace-json-vs-agents-md.md | 4 +- src/content/docs/ecosystem.mdx | 36 +- src/content/docs/faq.mdx | 60 +- src/content/docs/getting-started.mdx | 71 ++- src/content/docs/governance.mdx | 5 +- src/content/docs/implementations.mdx | 49 +- src/content/docs/implementations/codex.mdx | 10 +- src/content/docs/spec.mdx | 6 +- src/pages/index.astro | 19 +- src/pages/showcase/tally/index.astro | 3 + tests/tally.spec.ts | 9 +- 15 files changed, 710 insertions(+), 133 deletions(-) create mode 100644 PLAN.md diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 0000000..00980ee --- /dev/null +++ b/PLAN.md @@ -0,0 +1,553 @@ +# workspacejson.dev Implementation Plan + +## AAIF open standard donation candidate + +**Branch:** `feature/aaif-donation-website-implementation` +**Baseline repository:** `workspacejson/workspacejson.dev` +**Baseline commit:** head of `feat/hac-278-tally-showcase` (2026-07-31) +**Planning date:** 2026-07-31 + +--- + +## 1. Executive Summary + +`workspacejson.dev` is the public surface for the `workspace.json` open standard. It is the candidate donation artifact for the AI Alliance (AAIF). This plan turns the migrated, deployed site into a truth-backed, Starlight-native, reproducible documentation product without duplicating normative ownership from the standard, CLI, or integration repositories. + +The governing principle from the architecture issue `META-210` applies throughout: use the least custom Starlight capability that honestly expresses the requirement. The work is sequenced for momentum: make the current site accurate first, then upgrade, then redesign, then polish for donation. + +--- + +## 2. Goal (Ideal State) + +Done means `workspacejson.dev` is: + +- **Mechanically sourced:** every public version, status, path, schema, and implementation claim is derived from a checked-in, validated manifest. +- **Reproducibly built:** `npm run build` materializes the package-owned schema, validates every public example, and fails on any hash, link, or contract mismatch. +- **Starlight-native:** the information architecture, homepage, and chrome use Starlight's defaults, frontmatter, autogenerated groups, and native components. Custom overrides are documented, few, and bounded. +- **Donation-ready for AAIF:** the governance, provenance, and steward/donation statements are explicit, honest, and canonical. The site does not over-claim authority or adoption. +- **Visually and accessibly proven:** Playwright contract, a11y, responsive, and visual regression suites pass on the real built output before any merge to `main`. + +--- + +## 3. Current State (from the branch and repositories) + +### 3.1 Repository state + +- **Stack:** Astro `6.2.2`, Starlight `0.38.4`, twelve Starlight plugins (`starlight-blog`, `starlight-giscus`, etc.). +- **Build pipeline:** `npm run build` runs `schema:verify`, `content:verify`, `verify:ecosystem`, then `astro build`. +- **Tests:** Playwright harness (`META-215`) with contract, a11y, console, responsive, visual, and per-page suites (`tests/`). +- **Typed contract:** `src/contract.json` already exists and declares `standard.version`, `standard.packageVersion`, `governance`, `tools.audit`, `tools.cli`, `tools.codex`, `adoptionEvidence`, and `sources`. It is the starting point for `META-213`. +- **Overrides:** `src/components/overrides/{Footer.astro, SocialIcons.astro, ThemeProvider.astro, ThemeSelect.astro}` and `src/components/JsonLd.astro`. +- **Custom CSS:** `src/styles/custom.css` (351 lines) with direct Starlight internal selectors. +- **Homepage:** `src/pages/index.astro` (1,127 lines) contains a parallel design system and a large, unvalidated example. +- **Sidebar:** hand-authored flat list in `astro.config.mjs`, mixing spec, tools, governance, and showcase at one level. +- **Schema hosting:** `contract.json` declares a pinned `packages/spec/schema/v1.json` from `workspacejson/standard` at `v0.4.4` with SHA-256 verification. +- **Vercel deployment:** `vercel.json` is present and sets `framework: astro` with headers for `/schema/*` and `/llms.txt`. + +### 3.2 Linear input snapshot + +| Issue | Title | Status | Priority | Gated by / Blocks | +| -- | -- | -- | -- | -- | +| `META-210` | Rebuild workspacejson.dev as a Starlight-native product | In Progress | High | Parent ARC | +| `META-273` | P0 release cut: make workspacejson.dev accurate before remodel | Todo | Urgent | none; blocks `META-250`, `META-212` | +| `META-250` | Upgrade Astro 6.2.2 -> 7.x to clear 5 known CVEs | Backlog | High | `META-273` and redesign | +| `META-211` | Publish package-owned schema and make examples executable | In Progress | Urgent | `HAC-181` | +| `META-213` | Replace patched version strings with typed site contract manifest | In Progress | High | `META-211` | +| `META-214` | Redesign IA with native Starlight navigation | Backlog | High | `META-211`, `META-213` | +| `META-212` | Decompose custom homepage into Starlight-native landing | Backlog | High | `META-273`, `META-214`, `META-211`, `META-215`, `META-213` | +| `META-216` | Retire parallel component layer and constrain overrides | In Progress | High | `META-214`, `META-212`, `META-215` | +| `META-217` | Materialize canonical cross-repo docs with pinned provenance | Backlog | High | `META-211`, `META-213` | +| `META-253` | Cloudflare Email Obfuscation corrupts `agents-audit@VERSION` strings | Todo | High | none; blocks `META-242` cutover evidence | +| `HAC-278` | Ship truth-backed Tally showcase route and IA | Done | Urgent | Tally workstream | +| `HAC-279` | Polish Tally page into editorial-grade judge journey | Backlog | Urgent | `HAC-278` (optional, not tablestakes) | +| `META-215` | Documentation acceptance and visual regression harness | Done | High | foundational | + +--- + +## 4. Scope + +### 4.1 In scope for this branch + +- P0 accuracy release (`META-273`) of the existing Astro/Starlight shell. +- Astro 7 security upgrade (`META-250`) after the shell is native enough to make the bump economical. +- Schema materialization and example validation (`META-211`). +- Contract manifest completion and deprecation of `scripts/bump-version.mjs` (`META-213`). +- Starlight-native information architecture (`META-214`). +- Homepage decomposition (`META-212`) and override/CSS retirement (`META-216`). +- Cross-repository documentation materialization (`META-217`), started with a bounded import set. +- Cloudflare Email Obfuscation decision and remediation (`META-253`). +- Tally route hardening and optional editorial polish (`HAC-278`, `HAC-279`). +- AAIF donation readiness: governance, provenance, and honest stewardship copy. + +### 4.2 Out of scope (tracked elsewhere) + +- Package publish authority transfer (`META-243`). The site will record `authorityStatus` honestly, not hide transitional state. +- Full v0.5 schema or governance decisions (`META-205`, `META-218`). The site reflects ratified state, does not ratify. +- `workspacejson/integrations` monorepo reshape (`META-161`) and its children. +- New client islands, animation, or motion beyond what Starlight natively supports. +- Arbitrary redesign of the Tally product itself (the website surfaces it, does not build it). + +--- + +## 5. Momentum-Inspired Sequencing + +The order is deliberately accuracy-first, redesign-second, security-third, polish-last. This is the opposite of starting with a visual rebrand, which is the most common failure mode for a donation candidate. + +### Phase 0: Accuracy release cut (META-273) + +**Goal:** make every current public surface factually correct in the existing shell. + +**Time box:** 1-2 days. +**Owner:** site lead / content owner. +**Status:** implementation complete; deployment verification remaining. + +#### 5.0.1 Work + +1. Re-measure current npm and GitHub registry facts: + - `@workspacejson/spec` 0.4.4 from `workspacejson/standard` + - `@workspacejson/rules` 0.4.4 from `workspacejson/standard` + - `agents-audit` 0.4.4 from `workspacejson/cli` (canonical) / `workspace-json/agents-audit` (publication) + - `@workspacejson/cli` 0.5.2 from `workspacejson/cli` + - `@workspacejson/codex-mcp` 0.1.9 from `workspace-json/codex-mcp` (publication) / `workspacejson/integrations` (development) +2. Update `src/contract.json` with the measured values. Keep `authorityStatus` accurate (`canonical` or `transitional`). +3. Page-by-page corrections across the 16 authored routes listed in `META-273`: + - `/` remove stale package/repository facts, fix Codex-vs-standard category error, add bounded Tally proof entry. + - `/getting-started/` lead with `npx @workspacejson/cli generate`, keep `agents-audit` as frozen audit surface. + - `/ecosystem/` separate shipped consumers from hypothetical compatibility, remove stale Vreko framing. + - `/spec/` source status, package versions, canonical repository, schema provenance from `workspacejson/standard`. + - `/examples/` every example declares profile/source and passes validation. + - `/implementations/` add `@workspacejson/cli`, remove duplicate Codex card, classify producers/consumers/validators. + - `/implementations/codex/` update JSON-LD and source truth honestly. + - `/audit/` label `agents-audit@0.4.4` as frozen audit/compatibility surface, not the durable producer. + - `/governance/` point to current standard governance, state actual donation status. + - `/changelog/` add 0.4.4 and CLI 0.5.2 release lines. + - `/faq/` reconcile producer, Vreko, AI-attribution, integration-support, governance answers. + - `/blog/**` mark dated claims as historical where current standard no longer carries them. + - `/showcase/tally/` use approved cockpit hero asset, label fixture-backed actions truthfully. + - `/showcase/tally/proof/` keep proof ledger exhaustive and current. + - global chrome: GitHub destinations, footer resources, Giscus repository. +4. Resolve `META-253` Cloudflare Email Obfuscation decision. Record the chosen path. Disable Scrape Shield or restructure affected markup. + +#### 5.0.2 Acceptance + +- `npm run build`, `schema:verify`, `content:verify`, `verify:ecosystem` pass. +- `npm run verify:site` (Playwright contract + visual) passes with no new unowned defects. +- Every visible fact matches `src/contract.json`, JSON-LD, OG metadata, sidebar labels, footer links, and `llms.txt`. +- No current-authority link silently resolves to the old organization; no historical link is rewritten as if it happened in the new organization. +- A cold logged-out user can generate an artifact, identify the standard owner, find the neutral CLI, distinguish producers from consumers, and reach Tally. +- Route/claim matrix is attached to the issue and committed in `PLAN.md` or `sources/`. + +#### 5.0.3 Release criteria + +This phase is the only one that merges to `main` before the Astro/Starlight redesign. It is a publishable, accurate release. + +--- + +### Phase 1: Astro 7 security train (META-250) + +**Goal:** clear the 5 Astro/Dependabot CVEs without re-validating a large custom homepage. + +**Time box:** 2-3 days. +**Owner:** frontend lead. +**Prerequisite:** Phase 0 is live, so the site is already correct. + +#### 5.1.1 Work + +1. Wait for `META-212` (homepage decomposition) and `META-216` (override retirement) to reach a point where the validated surface is mostly Starlight-native. The issue explicitly defers the bump until then; this plan follows that decision. +2. Upgrade `astro` to `7.x` (target `>= 7.1.0` for the View Transition XSS fix), `@astrojs/rss` to `>= 4.0.19`. +3. Upgrade or replace each Starlight plugin: + - `starlight-blog` + - `starlight-codeblock-fullscreen` + - `starlight-giscus` + - `starlight-image-zoom` + - `starlight-links-validator` + - `starlight-llms-txt` + - `starlight-tags` +4. Run `npm run build` and `npm run verify:site`. +5. Opportunistically bump `sharp` to `0.35.x` and refresh the lockfile for `svgo`. + +#### 5.1.2 Acceptance + +- `astro` is `7.x` and all 5 listed CVEs are closed. +- `starlight` and every plugin remain compatible or are removed with a documented reason. +- `npm run build` and `starlight-links-validator` pass clean. +- No visual or behavioral regression on the decision points tracked in the VR-663 audit. +- Visual regression baselines are updated only on Linux CI via `UPDATE_BASELINES=1`. + +--- + +### Phase 2: Contract manifest and schema truth (META-211, META-213) + +**Goal:** remove all string patching and make the site a read-only build of the package-owned standard and examples. + +**Time box:** 3-4 days. +**Owner:** site lead. +**Prerequisites:** Phase 0; `workspacejson/standard` publishes `@workspacejson/spec@0.4.4` with the bin (already true as of `HAC-181` Done). + +#### 5.2.1 Work + +1. Extend `src/contract.json` from the current partial contract to a full site contract: + - `specification.version`, `specification.packageVersion`, `specification.status`. + - `artifact.canonicalPath`, `artifact.legacyReadPaths`. + - `interoperabilityProfile.id`, `interoperabilityProfile.status`, `interoperabilityProfile.paths`. + - `project.license`, `project.governanceStatus`, `project.canonicalRepository`. +2. Replace `{{SPEC_VERSION}}` and `{{PKG_VERSION}}` token replacement in `astro.config.mjs` with manifest accessors. +3. Delete `scripts/bump-version.mjs` or reduce it to a manifest update plus validation. +4. Materialize `public/schema/v1.json` from the pinned source in `workspacejson/standard`. + - Record source repository, path, ref, commit, SHA-256. + - Production build fails unless public schema bytes are hash-equal to the pinned source bytes. +5. Extract every public example in `spec.mdx`, `examples.mdx`, `getting-started.mdx`, `index.astro`, etc. into machine-readable fixtures or fenced-code test inputs. + - Validate each example against the published schema and the four-path compatibility profile. + - Declare whether it demonstrates the full published schema or the current interoperability profile. + +#### 5.2.2 Acceptance + +- Build fails on missing schema source. +- Build fails on hash mismatch and reports both hashes. +- Build fails on example validation with page, block identifier, and error. +- `contract.json` is validated at build start. +- No `{{SPEC_VERSION}}` or `{{PKG_VERSION}}` token replacement remains. +- `contract.spec.ts` and `starlight.spec.ts` pass. + +--- + +### Phase 3: Starlight-native information architecture (META-214, META-217) + +**Goal:** replace the flat, hand-authored sidebar with a Starlight-native learning architecture and start importing canonical docs from other repositories. + +**Time box:** 3-5 days. +**Owner:** frontend lead + docs owner. +**Prerequisites:** Phase 2 (manifest and schema truth) is merged. + +#### 5.3.1 Work + +1. Redesign the sidebar into the target structure from `META-214`: + + ```text + Start Here + Overview + Getting Started + Interoperability Profile + workspace.json and AGENTS.md + Conformance + The Standard + Specification + Discovery and canonical path + Schema reference + Evidence and provenance + Compatibility semantics + Security + Versioning and migration + Ecosystem + Implementations and convergence + Consumers + Producers + Libraries + Integrations + workspace.json for Codex + Other integrations + Project + Governance + Changelog + FAQ + ``` + +2. Define one approved Starlight page archetype for each of: + - section/product landing page + - getting-started tutorial + - concept explanation + - normative standard chapter + - technical reference + - conformance/compatibility page + - implementation profile + - blog/editorial page +3. Use Starlight's nested groups, autogenerated directories, collapsed groups, sidebar badges, native `doc` and `splash` templates, and pagination. +4. Start the cross-repo materialization pipeline (`META-217`) with a bounded import set: + - package-owned schema/reference docs from `workspacejson/standard` + - selected Codex user-facing docs from `workspacejson/integrations` + - no maintainer audit logs, Build Week-only evidence, or internal execution documents +5. Preserve stable public URLs or add explicit redirects. Update sitemap, Pagefind, `llms.txt`, JSON-LD breadcrumbs, and canonical links. + +#### 5.3.2 Acceptance + +- Sidebar snapshot matches the target for desktop and mobile. +- Group/badge/order values derive from `contract.json` and frontmatter. +- Current route expands the correct group. +- No orphan page or duplicate navigation entry. +- Imported pages have correct `editUrl` targets to their owning repository. +- Pagefind indexes the intended pages and excludes duplicates/drafts. +- Keyboard and screen-reader navigation across all groups passes `a11y.spec.ts`. + +--- + +### Phase 4: Homepage decomposition and override retirement (META-212, META-216) + +**Goal:** replace the 1,127-line custom homepage and retire the parallel component layer. + +**Time box:** 4-5 days. +**Owner:** frontend lead. +**Prerequisites:** Phase 3 (IA) is merged. This is the most visible change, so it must be right. + +#### 5.4.1 Work + +1. Capture baseline screenshots and metrics of the current homepage. +2. Build a Starlight-native landing page that answers the five questions in `META-212` order: + - What is `workspace.json`? + - Why is it distinct from and complementary to AGENTS.md? + - What is proven interoperable now? + - How do I validate or adopt it? + - Where do I go as a user, producer, consumer, or standards reviewer? +3. Use native components: + - `splash` hero + - Badges for status/version/license + - `CardGrid` / `LinkCard` for routes by user intent + - `Aside` for bounded status/governance caveats + - `Steps` for the minimal adoption path + - `Code` for one compact, validated four-path example +4. Classify every custom component, override, and CSS selector: + - `KEEP` (product-specific meaning with no native equivalent) + - `WRAP` (retain Starlight default and add one bounded behavior) + - `REPLACE WITH NATIVE` + - `LOCALIZE` (page-specific, not global) + - `DELETE` + - `DEFER` +5. Reduce `src/styles/custom.css` to documented brand tokens, bounded global readability rules, and an explicit compatibility allowlist for any selector targeting Starlight internals. The allowlist must shrink to zero or carry an owner, version constraint, rationale, and regression test. +6. Preserve canonical URL, metadata, sitemap priority, and search behavior. + +#### 5.4.2 Acceptance + +- Homepage is materially shorter and uses Starlight as its primary component system. +- Manifest-driven claims agree with spec/sidebar/changelog. +- Compact example validates and uses only the declared profile. +- CTAs resolve and match user journeys. +- JSON-LD equals visible product/status data. +- Mobile/desktop/high-contrast snapshots pass. +- Heading order, focus order, landmark, and contrast checks pass. +- Page weight and CSS size are measured and reduced against baseline. +- No horizontal overflow at required viewports. + +--- + +### Phase 5: Tally showcase hardening and optional polish (HAC-278, HAC-279) + +**Goal:** keep the Tally route truthful, reachable, and, if time permits, editorially excellent. + +**Time box:** 1-2 days (hardening) + 2-3 days (optional polish). +**Owner:** product story lead + frontend lead. +**Prerequisites:** Phase 0 or Phase 3, depending on whether the route needs IA integration. + +#### 5.5.1 Work + +1. Verify `showcase/tally/` and `showcase/tally/proof/` against `HAC-278` acceptance. +2. Replace stale organization/repository/package URLs encountered in the Tally path. +3. If `HAC-279` is approved: + - Refine the hero, proof ledger, and role-based next actions. + - Add editorial-grade media and claim provenance. + - Ensure exported assets remain readable on GitHub and Devpost light surfaces. +4. Keep the standard primary: do not turn the homepage into a Tally takeover. + +#### 5.5.2 Acceptance + +- `npm run verify:site` passes for Tally routes. +- A cold visitor can identify the DataHub contribution, workspace.json contribution, Tally join, and changed-plan result in under 60 seconds. +- Every claim maps to the registry/claim ledger and exact revision. +- No raw JSON, internal issue IDs, or unsupported evidence vocabulary is primary. + +--- + +### Phase 6: AAIF donation readiness (cross-cutting) + +**Goal:** present the site as a neutral, honest, and reproducible open standard donation candidate. + +**Time box:** 1-2 days. +**Owner:** site lead + governance owner. +**Prerequisites:** Phase 0 at minimum; best after Phase 4. + +#### 5.6.1 Work + +1. Governance page: + - Current steward: Marcelle Labs. + - Donation statement: "Donation to a neutral body is intended; no body has accepted stewardship, and none has been approached successfully." (from `contract.json`). + - Formal change process: `false` if not yet ratified. + - License: Apache-2.0. + - Links to `workspacejson/standard/GOVERNANCE.md` and maintainers. +2. Provenance on every imported page: + - source repository + - source path + - ref or commit + - canonical edit URL +3. `llms.txt` generated from the contract and the current site map, with no over-claims. +4. Ensure the site never claims authority transfer that `META-243` has not completed. +5. Provide a public, reproducible build command and a link to the latest deployed commit. + +#### 5.6.2 Acceptance + +- A third-party reviewer can, from a single page, understand what is being donated, who currently stewards it, what is not yet decided, and how to reproduce the build. +- No page claims the standard is already donated to a neutral body. +- All canonical URLs point to `workspacejson/*` repositories; all historical URLs are labeled as historical. + +--- + +## 6. Dependencies and Blocker Map + +### 6.1 External prerequisites + +- `workspacejson/standard` owns and publishes `@workspacejson/spec` 0.4.4 with the bin. (Done.) +- `workspacejson/cli` owns `@workspacejson/cli` 0.5.2 and the frozen `agents-audit` compatibility package. (Done.) +- `workspacejson/integrations` is the development home for `@workspacejson/codex-mcp` 0.1.9; publication authority remains `workspace-json/codex-mcp` until `META-243` completes. (Transitional, do not hide.) +- Vercel project and Cloudflare DNS configuration are documented in `vercel.json` and `META-238` freeze receipts. + +### 6.2 Internal blockers + +- `META-243` must not be closed before `workspacejson.dev` claims canonical package authority. Until then, the site must display `transitional` status for codex-mcp and old publication repositories for spec/rules/agents-audit. +- `META-250` (Astro 7) is deliberately blocked behind `META-212` and `META-216`. This plan honors that. +- `META-273` is the P0 cut; all later phases depend on its acceptance tests passing. + +--- + +## 7. Risk Register + +| Risk | Likelihood | Impact | Mitigation | +| -- | -- | -- | -- | +| Astro 7 or Starlight 0.41 breaks a custom override or plugin | High | High | Decompose homepage and retire overrides before the bump (Phase 1 comes after Phase 4 in the issue; this plan keeps it after redesign). Maintain a pinned Starlight compatibility matrix. | +| Schema hash mismatch after materialization due to a new `workspacejson/standard` release | Medium | High | `src/contract.json` pins exact ref and SHA-256; build fails if changed; manual bump only. | +| Cloudflare Email Obfuscation persists and corrupts version strings | Medium | High | Decide and record remediation in Phase 0. Test by fetching the live deployment. | +| Tally page becomes the homepage by accident | Low | High | `HAC-278` tablestakes explicitly limits Tally to one featured card and one route. Review against this. | +| Claims about AAIF donation overstate the actual state | Low | Very High | Copy is mechanically sourced from `contract.json` governance block. No body is named as having accepted stewardship until it has. | +| Visual regression baselines drift between macOS and CI Linux | Medium | Medium | Baselines are generated on CI Linux; local macOS runs skip with an explanatory message. `maxDiffPixelRatio: 0.01`. | +| Custom CSS selectors break on Starlight upgrade | High | High | Inventory, classify, and allowlist every selector in Phase 4; target zero allowlist. | + +--- + +## 8. Verification Cadence + +- **Every PR:** `npm run build` (schema + content + ecosystem + astro build) and `npm run verify:site`. +- **Phase gates:** each phase above has its own acceptance section. Do not start the next phase until the previous acceptance is green. +- **Deployment:** only the P0 accuracy cut (Phase 0) may deploy to production before the redesign. All other phases accumulate in the feature branch or a `main` preview deployment. +- **Baseline discipline:** visual baselines are generated on CI Linux with `UPDATE_BASELINES=1`. No local macOS baselines are committed. + +--- + +## 9. Definition of Done for the Branch + +The branch `feature/aaif-donation-website-implementation` is done when: + +1. `META-273` (P0 accuracy cut) is closed and deployed. +2. `META-250` (Astro 7) is closed or explicitly deferred with a documented risk acceptance. +3. `META-211` and `META-213` are closed: schema and all examples are mechanically sourced and validated. +4. `META-214` is closed: the Starlight-native IA is in place. +5. `META-212` and `META-216` are closed: the homepage is decomposed and the override layer is retired. +6. `META-217` is closed or has a bounded pilot merged with the materialization pipeline. +7. `META-253` is closed: Cloudflare obfuscation no longer corrupts version strings. +8. The site passes `npm run verify:site` on CI with no new unowned defects. +9. The governance and donation statements are honest, sourced, and AAIF-reviewable. + +--- + +## 10. Communication + +- **Weekly status:** update `META-210` and `META-273` with the current phase, blockers, and test results. +- **AAIF handoff:** when Phase 6 is complete, generate a one-page `DONATION_README.md` in `workspacejson/standard` or `workspacejson.dev` that points to the build, the contract, the governance, and the provenance. +- **Donation candidate summary:** use this `PLAN.md` as the primary artifact for any AAIF reviewer, then add the deployed URL and the exact commit hash. + +--- + +## 11. Appendix: File Inventory and Evidentiary Links + +- `astro.config.mjs` — current Starlight config, custom sidebar, plugins, tokens +- `src/contract.json` — typed site contract (source of truth for most public claims) +- `src/content/docs/` — authored content pages +- `src/pages/index.astro` — current custom homepage (1,127 lines, target for Phase 4) +- `src/styles/custom.css` — brand tokens and Starlight internal selectors (target for Phase 4) +- `src/components/overrides/` — `Footer.astro`, `SocialIcons.astro`, `ThemeProvider.astro`, `ThemeSelect.astro` +- `src/components/tally/` — Tally showcase components +- `tests/` — contract, a11y, responsive, visual, console, starlight suites +- `sources/schema.source.json` — pinned schema source manifest +- `sources/ecosystem-packages.json` — pinned package authority manifest +- `vercel.json` — deployment headers and framework config + +## 12. Addendum: Tally judge journey implementation + +The Tally judge journey workstream (`.windsurf/plans/tally-judge-journey.md`) runs in parallel with Phase 5 to make the showcase page failure-first, navigable, and tested. + +### 12.1 Changes from the judge journey plan + +| # | Change | Target file | Status | +| -- | -- | -- | -- | +| 1 | Move product screenshot after the five narrative acts | `src/pages/showcase/tally/index.astro` | Done | +| 2 | Make "Read the story" the primary hero CTA, "Explore the evidence" the secondary, and "Try Tally" a ghost | `src/pages/showcase/tally/index.astro` | Done | +| 3 | Add both Tally routes to the Showcase sidebar | `astro.config.mjs` | Done | +| 4 | Add a failure-first Tally section to the homepage | `src/pages/index.astro` | Done | +| 5 | Add a Tally Showcase link to the footer | `src/components/overrides/Footer.astro` | Done | +| 6 | Remove the dead `showcase/tally.mdx` block from `routeData.ts` | `src/routeData.ts` | Done | +| 7 | Delete the four stale Tally components | `src/components/tally/` | Done | +| 8 | Add Tally judge journey tests | `tests/tally.spec.ts` | Done | +| 9 | Build the site and run `tests/tally.spec.ts` | build + Playwright | Done: 738 passed, 48 skipped, 0 failed | + +### 12.2 Acceptance + +- `npm run build` passes. +- `npx playwright test tests/tally.spec.ts` passes. +- The product screenshot appears after the fifth narrative act in the DOM. +- The hero has the three CTA hierarchy above. +- The sidebar, footer, homepage, and `routeData.ts` remain unchanged from their current correct state. + +All acceptance criteria met. This addendum is complete. + +--- + +## 13. Phase 0 Completion Summary + +**Date:** 2026-07-31 +**Linear issues updated:** META-273 (In Progress), META-253 (In Progress) + +### Completed work + +All 16 authored routes corrected in the existing Astro/Starlight shell: + +- **Global chrome:** GitHub social link and Giscus repo updated to `workspacejson/workspacejson.dev` +- **index.astro:** JSON-LD author changed to Marcelle Labs, Vreko founding org removed, `sameAs` updated, Codex-vs-standard category error fixed +- **spec.mdx:** JSON-LD author fixed, GDPR section updated from stale v0.3 fields to v0.4 terminology +- **audit.mdx:** JSON-LD author fixed, frozen label Aside added +- **getting-started.mdx:** Restructured to lead with `@workspacejson/cli generate`, step 3 repositioned as reference/fallback +- **ecosystem.mdx:** Vreko MCP replaced with `@workspacejson/codex-mcp`, shipped vs hypothetical separated, duplicate Goose removed, false Implementations cross-reference removed +- **implementations.mdx:** Restructured into Producers/Consumers/Validators, `@workspacejson/cli` added, duplicate Codex card removed +- **codex.mdx:** JSON-LD version updated to 0.1.9, canonical links updated to `workspacejson/integrations` +- **faq.mdx:** `fileIndex` -> `fragility`, stale v0.3 field names replaced, Vreko references contextualized, code block updated, tools list updated with shipped consumers +- **governance.mdx:** `governance@` mailto replaced with GitHub Discussions link (META-253 Path 3) +- **blog posts:** JSON-LD author fixed, factual error corrected (AGENTS.md is prescriptive, workspace.json is descriptive) +- **Tally showcase:** Ghost "Try Tally" CTA added, test updated + +### Bug fixes (confirmed against META-273) + +1. FAQ code block: `agents-audit scan .` -> `@workspacejson/cli generate .` +2. Getting Started step 3: manual heredoc repositioned from primary path to fallback +3. Spec GDPR section: `aiModificationCount`/`humanModificationCount` -> `changeCount`/`revertCount`/`fragilityScore` +4. Ecosystem: false Goose-on-Implementations-page cross-reference removed + +### Acceptance gates + +- `npm run build`: schema:verify, content:verify, verify:ecosystem, astro build all pass +- `npm run verify:site`: 738 passed, 48 skipped, 0 failed +- All internal links valid + +### Remaining steps before META-273 can close + +1. Disable Cloudflare Scrape Shield Email Obfuscation for the zone (META-253) +2. Deploy to production +3. Verify `__cf_email__` count is 0 on live site across all routes +4. Cold logged-out user verification (gate 6) +5. Attach deployed commit and compact route/claim matrix (gate 8) + +### Next phases + +- **Phase 1:** Astro 7 security train (META-250) - blocked behind homepage decomposition +- **Phase 2:** Contract manifest and schema truth (META-211, META-213) +- **Phase 3:** Starlight-native IA (META-214, META-217) +- **Phase 4:** Homepage decomposition and override retirement (META-212, META-216) +- **Phase 5:** Tally showcase hardening (HAC-278 done, HAC-279 optional) +- **Phase 6:** AAIF donation readiness + +--- + +This plan is a living document. Update it when a Linear issue is closed, a phase acceptance is met, or a new dependency is discovered. diff --git a/astro.config.mjs b/astro.config.mjs index 44a8f0d..0af806c 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -52,7 +52,7 @@ export default defineConfig({ }, social: [ { icon: 'rss', label: 'RSS', href: '/blog/rss.xml' }, - { icon: 'github', label: 'GitHub', href: `https://github.com/${contract.tools.audit.publicationRepository}` }, + { icon: 'github', label: 'GitHub', href: `https://github.com/${contract.site.repository}` }, ], customCss: ['./src/styles/custom.css'], expressiveCode: { @@ -144,7 +144,7 @@ export default defineConfig({ }), starlightTags(), starlightGiscus({ - repo: 'workspace-json/agents-workspace', + repo: 'workspacejson/workspacejson.dev', repoId: 'R_kgDOSUthVw', category: 'Announcements', categoryId: 'DIC_kwDOSUthV84C8gzk', diff --git a/src/content/docs/audit.mdx b/src/content/docs/audit.mdx index 7ad0821..5d80ad2 100644 --- a/src/content/docs/audit.mdx +++ b/src/content/docs/audit.mdx @@ -23,11 +23,20 @@ head: "installUrl": "https://www.npmjs.com/package/agents-audit", "codeRepository": "https://github.com/workspacejson/cli", "license": "https://github.com/workspacejson/cli/blob/main/LICENSE", - "author": { "@type": "Organization", "name": "Vreko", "url": "https://vreko.dev" }, + "author": { "@type": "Organization", "name": "Marcelle Labs" }, "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" } } --- +import { Aside } from '@astrojs/starlight/components'; + + + ## 1. Quick Start Run the audit tool against any repository: diff --git a/src/content/docs/blog/local-daemon-vs-cloud.mdx b/src/content/docs/blog/local-daemon-vs-cloud.mdx index b7994f8..5b1adbd 100644 --- a/src/content/docs/blog/local-daemon-vs-cloud.mdx +++ b/src/content/docs/blog/local-daemon-vs-cloud.mdx @@ -72,8 +72,7 @@ head: "inLanguage": "en", "author": { "@type": "Organization", - "name": "Vreko", - "url": "https://vreko.dev" + "name": "Marcelle Labs" }, "publisher": { "@id": "https://workspacejson.dev/#organization" diff --git a/src/content/docs/blog/workspace-json-vs-agents-md.md b/src/content/docs/blog/workspace-json-vs-agents-md.md index a560e0f..ac7dd92 100644 --- a/src/content/docs/blog/workspace-json-vs-agents-md.md +++ b/src/content/docs/blog/workspace-json-vs-agents-md.md @@ -40,9 +40,9 @@ AI coding agents need context to work well. Two formats have emerged to provide ## The core distinction -`AGENTS.md` is **descriptive and instructional**. It's a markdown file you write in natural language telling the agent how to behave: "run tests with `pnpm test`", "never modify files in `vendor/`", "use conventional commits". +`AGENTS.md` is **prescriptive and instructional**. It's a markdown file you write in natural language telling the agent how to behave: "run tests with `pnpm test`", "never modify files in `vendor/`", "use conventional commits". -`workspace.json` is **prescriptive and structural**. It's a machine-readable JSON file that encodes what's true about your repository: which packages exist, what files they own, what frameworks they use, how active they are. +`workspace.json` is **descriptive and structural**. It's a machine-readable JSON file that encodes what's true about your repository: which packages exist, what files they own, what frameworks they use, how active they are. One is a memo. The other is a manifest. diff --git a/src/content/docs/ecosystem.mdx b/src/content/docs/ecosystem.mdx index 5e32045..ba5c7f2 100644 --- a/src/content/docs/ecosystem.mdx +++ b/src/content/docs/ecosystem.mdx @@ -52,9 +52,9 @@ workspace.json and MCP operate at different points in the agent lifecycle: than a committed file can track. The two are complementary. An MCP server can *read* workspace.json to seed -its context (Vreko does this in its MCP server). An agent receiving MCP -context can use workspace.json for the structural and historical signals that -MCP doesn't model natively. +its context ([`@workspacejson/codex-mcp`](/implementations/codex/) does this). +An agent receiving MCP context can use workspace.json for the structural and +historical signals that MCP doesn't model natively. An MCP server that reads and exposes workspace.json is a reference integration pattern — see the [Implementations](/implementations/) page for tools that @@ -62,7 +62,20 @@ implement this. workspace.json does not depend on MCP and works without it. -## AI Coding Agent Integrations +## Shipped Consumer Integrations + +The following tools currently read workspace.json in production: + +- **[Codex](/implementations/codex/)** — MCP server, deterministic pre-edit hook, and read-only GPT-5.6 reviewer for OpenAI Codex. +- **[Buildomator](https://buildomator.com)** (formerly gsd-plugin) — Claude Code consumer that reads `.agents/workspace.json` at SessionStart. + +See the [Implementations](/implementations/) page for the full list. + +## Hypothetical Compatibility + +The following tools do **not** currently read workspace.json, but their +architecture is compatible with it. These are opportunities for tool authors, +not claims of existing support. ### workspace.json and Claude Code @@ -100,8 +113,7 @@ agent instruction convention that workspace.json is designed to complement. Goose's toolbox model (extensions that provide context and actions) maps naturally onto workspace.json: an extension could read workspace.json to surface fragility warnings, surface co-change patterns before edits, or -report workspace health state. This integration is not built yet and is -listed in the [Implementations](/implementations/) page as an opportunity. +report workspace health state. This integration is not built yet. ### workspace.json and Cline @@ -128,18 +140,6 @@ context in workspace.json. The `generated` section — fragility scores, co-chan patterns, framework manifest — provides the kind of repository intelligence that helps Copilot agents reason about impact and risk. -## workspace.json and Goose (Extended) - -[Goose](https://block.github.io/goose/) is Block's open-source AI developer -agent. Goose reads AGENTS.md when present and is a primary consumer of the -agent instruction convention that workspace.json is designed to complement. - -Goose's toolbox model (extensions that provide context and actions) maps -naturally onto workspace.json: an extension could read workspace.json to -surface fragility warnings before edits, expose co-change patterns as Goose -context, or report workspace health state. This integration is listed in the -[Implementations](/implementations/) page as an opportunity for tool authors. - ## The Broader Picture workspace.json is currently maintained by Marcelle Labs under a single-steward diff --git a/src/content/docs/faq.mdx b/src/content/docs/faq.mdx index 7a812a8..112bf73 100644 --- a/src/content/docs/faq.mdx +++ b/src/content/docs/faq.mdx @@ -67,7 +67,7 @@ head: "name": "How often should workspace.json be regenerated?", "acceptedAnswer": { "@type": "Answer", - "text": "As often as your generator supports. Vreko regenerates continuously through daemon-based behavioral observation. Other generators may run on commit, on a schedule, or on demand. Daily or per-PR regeneration is a reasonable starting point. The file is designed to be committed, so regeneration frequency determines the granularity of your commit history." + "text": "As often as your generator supports. @workspacejson/cli generates on demand from git history. Daemon-based generators like Vreko regenerate continuously. Other generators may run on commit, on a schedule, or on demand. Daily or per-PR regeneration is a reasonable starting point. The file is designed to be committed, so regeneration frequency determines the granularity of your commit history." } }, { @@ -91,7 +91,7 @@ head: "name": "How does workspace.json get populated?", "acceptedAnswer": { "@type": "Answer", - "text": "Two tiers: Static analysis (agents-audit CLI) runs npx agents-audit scan . to generate workspace.json from git history, approximating aiModificationCount and humanModificationCount from commit metadata. It runs once on demand with no background process. Live behavioral observation (daemon) observes file system events in real time and attributes modifications to the tool that triggered them. Counts become empirical as sessions accumulate. The daemon writes only to repos where workspace.json has been explicitly initialized. Both tiers produce spec-compliant workspace.json files. The static tier is immediately useful. The live tier produces higher-fidelity signals over time." + "text": "Two tiers: Static analysis (@workspacejson/cli or agents-audit) generates workspace.json from git history, deriving fragility scores and co-change patterns from commit metadata. It runs once on demand with no background process. Live behavioral observation (daemon) observes file system events in real time and attributes modifications to the tool that triggered them. Signals become empirical as sessions accumulate. The daemon writes only to repos where workspace.json has been explicitly initialized. Both tiers produce spec-compliant workspace.json files. The static tier is immediately useful. The live tier produces higher-fidelity signals over time." } }, { @@ -115,7 +115,7 @@ head: "name": "Do I need to install Vreko to use workspace.json?", "acceptedAnswer": { "@type": "Answer", - "text": "No. workspace.json is an open specification. You can write a minimal workspace.json by hand, generate it with any tool that implements the spec, or use agents-audit to validate one. Vreko is the reference implementation — it provides daemon-based behavioral observation to generate richer workspace.json files — but the spec is tool-agnostic and open." + "text": "No. workspace.json is an open specification. You can write a minimal workspace.json by hand, generate it with @workspacejson/cli or any tool that implements the spec, or use agents-audit to validate one. Vreko is a daemon-based generator that produces richer workspace.json files through continuous behavioral observation, but the spec is tool-agnostic and open." } }, { @@ -239,10 +239,11 @@ of MUST NOT fields. ## How often should workspace.json be regenerated? -As often as your generator supports. Vreko regenerates continuously as it observes -the codebase; other generators might run on commit, on a schedule, or on demand. -Daily or per-PR regeneration is a reasonable starting point for teams that don't -have a daemon-based generator. +As often as your generator supports. `@workspacejson/cli` generates on demand +from git history. Daemon-based generators like Vreko regenerate continuously as +they observe the codebase. Other generators might run on commit, on a schedule, +or on demand. Daily or per-PR regeneration is a reasonable starting point for +teams that don't have a daemon-based generator. ## How does workspace.json get populated? @@ -250,15 +251,15 @@ Two tiers of tooling produce workspace.json files. Both produce spec-compliant output; they differ in how they observe the codebase and the fidelity of the signals they produce. -**Static analysis (`agents-audit` CLI)** +**Static analysis (`@workspacejson/cli` or `agents-audit`)** -Run `npx agents-audit scan .` to generate a workspace.json from git history. -`aiModificationCount` and `humanModificationCount` are approximated from commit -metadata and tool signatures. The scan runs once on explicit invocation — there -are no hooks, no background process, no daemon. +Run `npx @workspacejson/cli generate .` to generate a workspace.json from git history. +Fragility scores and co-change patterns are derived from commit metadata. The scan +runs once on explicit invocation — there are no hooks, no background process, no +daemon. ```bash -npx agents-audit scan . +npx @workspacejson/cli generate . ``` This is useful immediately, before any daemon is running, and produces valid @@ -273,9 +274,8 @@ accumulate. The daemon writes only to repositories where workspace.json has been explicitly initialized. This is how [Vreko](https://vreko.dev) operates. The live tier produces -higher-fidelity `aiModificationCount` and `humanModificationCount` signals over -time because it attributes changes at the session level rather than inferring -them from commit metadata. +higher-fidelity fragility and co-change signals over time because it attributes +changes at the session level rather than inferring them from commit metadata. Both tiers produce spec-compliant workspace.json files. The static tier is immediately useful with no ongoing process. The live tier produces richer signals @@ -316,19 +316,21 @@ the root file. ## Do I need to install Vreko to use workspace.json? No. workspace.json is an open specification. You can write a minimal -`workspace.json` by hand, generate it with any tool that implements the -spec, or use `agents-audit` to validate one. +`workspace.json` by hand, generate it with `@workspacejson/cli` or any tool +that implements the spec, or use `agents-audit` to validate one. -[Vreko](https://vreko.dev) is the reference implementation — it provides -daemon-based behavioral observation to generate richer workspace.json files — but -the spec is tool-agnostic and open. +[Vreko](https://vreko.dev) is a daemon-based generator that produces richer +workspace.json files through continuous behavioral observation — but the spec +is tool-agnostic and open. ## What tools currently support workspace.json? -The reference CLI [agents-audit](/audit/) reads workspace.json when present. -[Vreko](https://vreko.dev) generates workspace.json as part of its daemon output. -Other implementations are early; see the [Implementations](/implementations/) page -for the current list. +The neutral CLI [`@workspacejson/cli`](https://www.npmjs.com/package/@workspacejson/cli) +generates and validates workspace.json. [`agents-audit`](/audit/) reads workspace.json +when present. [Vreko](https://vreko.dev) generates workspace.json as part of its daemon +output. Shipped consumers include [Codex](/implementations/codex/) and +[Buildomator](https://buildomator.com). See the [Implementations](/implementations/) +page for the full list. ## How is the spec governed? @@ -362,10 +364,10 @@ ambiguous current state. ## Does workspace.json support AI attribution for code changes? -v{{SPEC_VERSION}} does not include a dedicated AI attribution field. The `aiModificationCount` -and `humanModificationCount` fields in `fileIndex` are aggregate counts — they -record how many times a file was modified by AI-assisted versus human-driven -sessions, without identifying which session or contributor. +v{{SPEC_VERSION}} does not include a dedicated AI attribution field. The `fragility` +section records per-file change counts, revert counts, and fragility scores — +aggregate signals about how files change, without identifying which session or +contributor. AI attribution as a structured field is under consideration for a future version. For teams tracking AI contributions now, the combination of workspace.json commit diff --git a/src/content/docs/getting-started.mdx b/src/content/docs/getting-started.mdx index c5325cb..54cf32b 100644 --- a/src/content/docs/getting-started.mdx +++ b/src/content/docs/getting-started.mdx @@ -1,6 +1,6 @@ --- title: "Getting Started" -description: "How to add workspace.json to your repository, run your first audit with agents-audit, and validate your workspace.json file in CI. Quick start guide for workspace.json." +description: "How to add workspace.json to your repository with @workspacejson/cli, validate with agents-audit, and set up CI. Quick start guide for workspace.json." tableOfContents: true sidebar: order: 0 @@ -14,25 +14,25 @@ head: "@context": "https://schema.org", "@type": "HowTo", "name": "Getting Started with workspace.json", - "description": "How to add workspace.json to your repository and validate it with agents-audit.", + "description": "How to add workspace.json to your repository with @workspacejson/cli and validate it with agents-audit.", "url": "https://workspacejson.dev/getting-started/", "step": [ { "@type": "HowToStep", "position": 1, - "name": "Install agents-audit", - "text": "Run npx agents-audit from your repository root — no installation required." + "name": "Generate workspace.json", + "text": "Run npx @workspacejson/cli generate . from your repository root." }, { "@type": "HowToStep", "position": 2, - "name": "Run your first audit", - "text": "cd your-repo && npx agents-audit" + "name": "Audit with agents-audit", + "text": "Run npx agents-audit to check AGENTS.md hygiene and workspace.json consistency." }, { "@type": "HowToStep", "position": 3, - "name": "Create a minimal workspace.json", + "name": "Understand the minimal workspace.json structure", "text": "Create .agents/workspace.json with specVersion 0.4 and the four required top-level sections: manual, generated, agents, health." }, { @@ -52,50 +52,35 @@ intelligence. A machine-generated JSON file committed to your repository — it gives AI coding agents structured facts about your codebase without requiring them to read every file. -**TL;DR**: Run `npx agents-audit scan .` in your repository right now. You'll get a -hygiene score for your `AGENTS.md` and, if present, your `workspace.json`. +**TL;DR**: Run `npx @workspacejson/cli generate .` in your repository to generate +a workspace.json, then `npx agents-audit` to check hygiene. ## What You'll Have After This Guide -- A passing `npx agents-audit` run in your repo +- A generated `workspace.json` committed to git - Understanding of the workspace.json format +- A passing `npx agents-audit` run in your repo - CI validation set up with GitHub Actions -- A minimal `workspace.json` committed to git --- -## 1. Install agents-audit - -No installation required — run directly with npx: - -```bash -npx agents-audit -``` +## 1. Generate workspace.json -Or install globally: - -```bash -npm install -g agents-audit -``` - -agents-audit runs in any repository. It doesn't require workspace.json to be -present — it will audit your `AGENTS.md` and tell you what's missing. - - +This writes `.agents/workspace.json` with the four required top-level sections +(`manual`, `generated`, `agents`, `health`) populated from your repository. + +The CLI is actively developed in [workspacejson/cli](https://github.com/workspacejson/cli). -## 2. Run Your First Audit +## 2. Audit with agents-audit -From your repository root: +`agents-audit` is the frozen audit and compatibility surface at {{PKG_VERSION}}. +It checks `AGENTS.md` hygiene and `workspace.json` consistency: ```bash cd your-repo @@ -122,7 +107,17 @@ Example output: The score drops below 70 if any `error`-severity findings exist. -## 3. Create a Minimal workspace.json + + +## 3. Minimal workspace.json Structure + +If you used `npx @workspacejson/cli generate .` in step 1, you already have a +complete `workspace.json`. This section shows the minimal valid structure for +reference or for hand-authoring a file without a generator. The minimum valid `workspace.json` for v{{SPEC_VERSION}} requires all four sections: @@ -139,7 +134,7 @@ The minimum valid `workspace.json` for v{{SPEC_VERSION}} requires all four secti } ``` -Create it at `.agents/workspace.json`: +To create one manually at `.agents/workspace.json`: ```bash mkdir -p .agents @@ -157,7 +152,7 @@ cat > .agents/workspace.json << 'EOF' EOF ``` -Commit it: +Then commit it: ```bash git add .agents/workspace.json diff --git a/src/content/docs/governance.mdx b/src/content/docs/governance.mdx index 9cb483a..75cebf7 100644 --- a/src/content/docs/governance.mdx +++ b/src/content/docs/governance.mdx @@ -34,8 +34,9 @@ implement workspace.json without permission, payment, or attribution. ## Maintainership Feedback and contributions are welcome through the canonical repository. -Marcelle Labs remains the current steward. Contact: -[governance@workspacejson.dev](mailto:governance@workspacejson.dev) +Marcelle Labs remains the current steward. To provide feedback, open a +[GitHub Discussion](https://github.com/workspacejson/workspacejson.dev/discussions) +or a PR against the [standard repository](https://github.com/workspacejson/standard). ## Contribution diff --git a/src/content/docs/implementations.mdx b/src/content/docs/implementations.mdx index 09288b7..106bb20 100644 --- a/src/content/docs/implementations.mdx +++ b/src/content/docs/implementations.mdx @@ -1,6 +1,6 @@ --- title: "Implementations" -description: "Tools that generate or consume workspace.json. Currently: Vreko (daemon-based generation) and agents-audit (validation). Open to any tool that implements the spec — submit a PR." +description: "Tools that generate, consume, or validate workspace.json. Currently: @workspacejson/cli, agents-audit, Codex, Buildomator, and Tally. Open to any tool that implements the spec." tableOfContents: true sidebar: order: 4 @@ -9,25 +9,31 @@ sidebar: import { CardGrid, LinkCard } from '@astrojs/starlight/components'; -This page lists tools that read or generate workspace.json. +This page lists tools that generate, consume, or validate workspace.json, +classified by role. At v{{SPEC_VERSION}}, the spec is newly published. Tool authors: if you ship workspace.json support, please open a PR to add your tool here. We list any tool that documents workspace.json reading or writing in its public docs. -## Generation Tools +## Producers -Tools that write `workspace.json`: +Tools that generate `workspace.json`: + -## Consumption Tools +## Consumers Tools that read `workspace.json`: @@ -37,19 +43,9 @@ Tools that read `workspace.json`: description="Read-only MCP context plus a deterministic hook for evidenced co-change omissions on supported Codex edits." href="/implementations/codex/" /> - - -Buildomator’s maintainer documented the reader’s four paths from a cold review of the public materials and surfaced the documentation’s top-level `version` contradiction. This is a consumption claim only: it does not describe Buildomator’s own project-state store. +Buildomator's maintainer documented the reader's four paths from a cold review of the public materials and surfaced the documentation's top-level `version` contradiction. This is a consumption claim only: it does not describe Buildomator's own project-state store. + +## Validators + +Tools that validate `workspace.json` schema compliance and hygiene: + + + + + ## Generation Approaches diff --git a/src/content/docs/implementations/codex.mdx b/src/content/docs/implementations/codex.mdx index c4e7b16..97be9e2 100644 --- a/src/content/docs/implementations/codex.mdx +++ b/src/content/docs/implementations/codex.mdx @@ -19,7 +19,7 @@ head: "softwareVersion": "0.1.9", "description": "MCP server that gives OpenAI Codex workspace.json fragility and co-change evidence, enforced by a deterministic pre-edit hook, with a read-only GPT-5.6 adversarial reviewer.", "url": "https://workspacejson.dev/implementations/codex/", - "softwareHelp": "https://github.com/workspace-json/codex-mcp", + "softwareHelp": "https://github.com/workspacejson/integrations", "license": "https://www.apache.org/licenses/LICENSE-2.0" } --- @@ -73,7 +73,7 @@ Six promises, each checkable against the source rather than taken on faith: 5. Uninstall removes only owned artifacts. 6. Every `VERIFIED` claim maps to a reproducible command. -Reproduce them yourself: clone the repository, run `npm ci && npm run verify`. Full citations for each guarantee, and how the system behaves under missing, malformed, or unavailable input, are documented in the [repository](https://github.com/workspace-json/codex-mcp). +Reproduce them yourself: clone the repository, run `npm ci && npm run verify`. Full citations for each guarantee, and how the system behaves under missing, malformed, or unavailable input, are documented in the [repository](https://github.com/workspacejson/integrations). ## Current limitations @@ -110,17 +110,17 @@ That second comment is why the [spec](/spec/)'s Quick Reference table no longer

- One artifact, two consumers on separate vendor agent platforms: workspace.json for Codex and + One spec, multiple consumers: + Codex and Buildomator (formerly gsd-plugin) - for Claude Code. + both read workspace.json to give agent platforms codebase context.

Read the spec diff --git a/src/pages/showcase/tally/index.astro b/src/pages/showcase/tally/index.astro index d8396b7..98d54ab 100644 --- a/src/pages/showcase/tally/index.astro +++ b/src/pages/showcase/tally/index.astro @@ -97,6 +97,9 @@ const cockpitUrl = ctaLinks.liveEvidence; Explore the evidence + + Try Tally +
diff --git a/tests/tally.spec.ts b/tests/tally.spec.ts index 62fd7e5..5ea9188 100644 --- a/tests/tally.spec.ts +++ b/tests/tally.spec.ts @@ -245,12 +245,15 @@ test.describe('showcase: hero', () => { expect(href).toBe('#the-problem'); }); - test('hero has exactly two CTAs (no ghost Try Tally)', async ({ page }) => { + test('hero has exactly three CTAs including ghost Try Tally', async ({ page }) => { await page.goto(NARRATIVE, { waitUntil: 'load' }); const ctas = page.locator('.tally-hero-ctas a'); - expect(await ctas.count()).toBe(2); + expect(await ctas.count()).toBe(3); const ghost = page.locator('.tally-hero-ctas .tally-cta-ghost'); - expect(await ghost.count()).toBe(0); + expect(await ghost.count()).toBe(1); + expect(await ghost.textContent()).toContain('Try Tally'); + const href = await ghost.getAttribute('href'); + expect(href).toBe('https://tally.workspacejson.dev/'); }); test('Explore the evidence CTA links to proof page', async ({ page }) => {