[OSS POLISH] Bring workspacejson/standard to the public repository polish standard - #2
Merged
qmarcelle merged 2 commits intoJul 26, 2026
Conversation
…sh standard Layers public-readiness work on top of the extraction migration without touching the normative surface. Schema bytes are unchanged: 6220 bytes, sha256 7f1635bbeff47b103566866d1b66c47a604f91bb3948ad2b59a3ba9369a41e36. Added — community and governance SUPPORT.md, GOVERNANCE.md, MAINTAINERS.md, .github/CODEOWNERS and .github/ISSUE_TEMPLATE/config.yml. Each names a real process and a real owner; none is ceremony. Added — documentation the repository claims to own docs/adr/ now holds the architecture decision records, which previously existed only in a private tracker. ADR-001 records the canonical artifact path decision that shipped in 0.4.1 and had never been written down anywhere; its provenance is the package changelog, not a new decision. ADR-002 is transcribed from its internal draft with issue identifiers, private product names and a stale registry snapshot removed — no decision, boundary, metric or stop condition altered. docs/versioning.md, docs/conformance.md, docs/glossary.md, docs/troubleshooting.md and docs/repository-settings.md. Added — automation that keeps the polish true scripts/check-docs.mjs, wired into CI as `pnpm run check:docs`. Every relative link must resolve, every documented `pnpm run` command must exist, and no internal tracker identifier may reach public prose. It found 37 identifier leaks on its first run. .editorconfig, .gitattributes, .github/dependabot.yml. Changed — public surface Internal tracker identifiers removed from prose across the README, OWNERSHIP, AGENTS, CONTRIBUTING, RELEASE-AUTHORITY, the guard scripts, CI comments and two package test descriptions. Every explanation was kept; only the unresolvable identifiers changed. migration/ and docs/adr/ stay exempt as provenance records. README gained a status statement, a cold-verified quickstart, a documentation map and a known-limitations section. Both issue templates were rewritten — they still described agents-audit — and now route out-of-scope reports to the owning repository. Package READMEs no longer claim to be published from the agents-audit workspace, and their brand assets are vendored into assets/ rather than loaded from the frozen historical repository. ci.yml declares least-privilege `permissions: contents: read` at workflow and job level, and cancels superseded non-main runs. Removed the `aaif` keyword from both packages: it implied a standards-body status the project does not hold. Fixed Both package changelogs recorded 0.4.4 as Unreleased while npm published it on 2026-07-23. The registry is the arbiter. Deliberately unchanged Schema $id host, the v1.json filename, package versions, version/specVersion dual-emit, the four ambient interop shims, publication capability and repository visibility. Each changes a contract or needs an authority this pass does not hold.
actions/checkout, actions/setup-node and pnpm/action-setup all targeted Node 20, which GitHub now force-runs on Node 24 and annotates as deprecated on every run. A polish pass should not leave a standing warning on CI. Dependabot's github-actions ecosystem keeps these current from here.
qmarcelle
marked this pull request as ready for review
July 26, 2026 05:12
qmarcelle
deleted the
feature/meta-246-oss-polish-bring-workspacejsonstandard-to-the-public
branch
July 26, 2026 05:17
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Layers public-readiness work on top of the extraction migration. No normative change: schema bytes are identical at 6220 bytes,
sha256 7f1635bbeff47b103566866d1b66c47a604f91bb3948ad2b59a3ba9369a41e36.Before / after
SUPPORT.md,GOVERNANCE.md,MAINTAINERS.md.github/CODEOWNERS,ISSUE_TEMPLATE/config.ymlagents-audit.editorconfig,.gitattributes,dependabot.ymlci.ymlpermissionscontents: readat workflow and job levelpnpm run check:docs, wired into CIdocs/adr/assets/; framing correctedkeywordsaaif0.4.4Unreleased2026-07-23, matching npmVerification receipts
Full local run, all green:
check:architecture,check:architecture:test,check:docs,build,typecheck,test(173 passed),check:schema,check:examples,release:verify-packs, export validation, binary behavior.The 11 unique external links resolve. Five return 404 unauthenticated purely because this repository is private; each was confirmed authenticated.
npmjs.comreturns 403 to non-browser clients — package existence was confirmed againstregistry.npmjs.orginstead (both 200).Three judgment calls
Internal tracker identifiers. The polish standard bans them in permanent public prose. 37 occurrences existed. Every explanation was kept and only the unresolvable identifier replaced.
migration/anddocs/adr/remain exempt as provenance records, andcheck-docs.mjsnow enforces this so it cannot silently regress.ADR-001 status. No ADR-001 existed anywhere, though ADR-002 declared a dependency on it. The decision turned out to be real, dated and shipped —
@workspacejson/spec@0.4.1, 2026-06-02, recorded in the package changelog. It is committed asAcceptedwith that provenance, plus an Open Questions section for what is genuinely still unresolved. It also surfaced a compatibility fact worth not losing:.agents/agents.workspace.jsonremains a valid read fallback.Package README logos. Vendored into
assets/and referenced repo-relative. Known limitation: npm resolves relative images via therepositoryfield, which needs the repository to be public, so they will not render on npm until visibility changes.Found, reported, deliberately not fixed here
VrekoContextis a public export of@workspacejson/rules(src/index.ts). A proprietary vendor name in the public API surface of an Apache-2.0 standard package. Renaming it is a breaking API change, so it belongs with the clean-room boundary work, not with polish.PUT /private-vulnerability-reportingreturns 404. Three committed files direct reporters to the advisory form. Harmless today because nobody outside the org can read them; it stops being harmless the moment visibility flips.SECURITY.mdcarries a maintainer note anddocs/repository-settings.mdmakes enabling it step 1 of going public.@workspacejson/speccarries a stalenext: 0.2.1dist-tag. Correcting it is a registry action requiring publish authority this repository does not hold.Held out of scope, as directed
Schema
$idhost ·v1.jsonnaming · version bumps ·version/specVersiondual-emit · any publish step, credential or release workflow · the four ambient CJS/ESM interop shims · v0.5 or new-signal design · repository visibility.