# Pre-public package and metadata consistency

## Traceability

- Spec ID: pre-public-package-consistency
- Status: Implemented

## Intent

Make the repository's public npm package, CI routing, plugin metadata, internal
Skill declarations, and canonical script paths internally consistent before the
project becomes public. The maintenance must preserve supported host schemas
and cross-platform output rather than introducing compatibility fields that a
host rejects.

## Acceptance Scenarios

- **PPC-AC-1:** `npm pack` contains the Qoder, Claude, Codex, and Cursor plugin
  manifest roots, and package verification fails when any required manifest is
  missing. The Qoder-oriented runtime ZIP remains host-specific.
- **PPC-AC-2:** CI runs for pushes to `main` and for pull requests; no active
  workflow treats `master` as the default branch.
- **PPC-AC-3:** the Cursor marketplace uses the canonical `better-harness`
  identity and public description. Cursor version ownership stays in
  `.cursor-plugin/plugin.json` because the pinned official marketplace schema
  rejects a `plugins[].version` field.
- **PPC-AC-4:** `scripts/doc-link-graph/cli.mjs` is the only implementation of
  the documentation graph CLI. Its repository-relative paths and Mermaid node
  identifiers use POSIX separators on Windows, and the retired root duplicate
  is absent.
- **PPC-AC-5:** repo-local Skill guidance no longer requires a `mirror.json`
  sidecar. Each direct `.agents/skills/<skill>/` directory uses `SKILL.md` as its
  entrypoint, while wrapper routing and generated ownership stay with the skill
  instructions or generator.
- **PPC-AC-6:** repository-evidence fixtures use the canonical
  `scripts/npm-package/verify-pack.mjs` path and do not preserve the retired
  `scripts/package/` spelling.
- **PPC-AC-7:** `package.json` and all four `plugin.json` files use one public
  description, manifest versions stay aligned at `0.3.0`, and contributor docs
  describe the current `0.3.x` line.

## Non-goals

- Do not publish a package or create a release.
- Do not add unsupported Cursor marketplace fields or change the pinned Cursor
  schemas.
- Do not add non-Qoder plugin roots to the Qoder-oriented runtime ZIP.
- Do not retain a compatibility shim for the pre-public root doc-link command;
  current documentation and tests already route to the canonical CLI.
- Do not redesign plugin capabilities, Skill content, or CI test coverage.

## Plan and Tasks

1. Align npm file roots and package verification with the four supported host
   manifests while preserving the runtime ZIP boundary.
2. Route CI pushes to `main` and normalize Cursor marketplace identity without
   violating its schema.
3. Remove the duplicate root doc-link implementation and add regression
   coverage for canonical ownership and POSIX-relative paths.
4. Remove the unused mirror sidecar contract from repo-local Skill guidance and
   its architecture references.
5. Replace the stale package-script fixture path and align public descriptions
   and contributor version wording.
6. Run focused manifest, doc-link, repository-evidence, and script
   ownership tests; then run the full suite and package verification.

## Test and Review Evidence

- **PPC-AC-1, PPC-AC-3, PPC-AC-7:** `node --test
  test/plugin-manifests.test.mjs` and `npm run pack:verify` with an isolated npm
  cache when required.
- **PPC-AC-2:** inspect `.github/workflows/ci.yml` and search active workflows
  for the retired default branch name.
- **PPC-AC-4:** `node scripts/doc-link-graph/cli.mjs
  skills/better-harness`, `node --test test/doc-link-graph.test.mjs
  test/scripts-refactor-contract.test.mjs`, and `git diff --check`.
- **PPC-AC-5:** search active guidance for `mirror.json`, `mirror_type`, and the
  retired mirror validator path; only explicit sidecar-removal statements may
  remain.
- **PPC-AC-6:** `node --test
  test/task-loop-repository-evidence.test.mjs` plus a repository search for
  `scripts/package/verify-pack.mjs`.
- **Regression:** `npm test` and `npm run pack:verify`.
- **Risk review:** inspect the actual npm pack entry set, confirm the runtime
  ZIP remains Qoder-specific, confirm the Cursor schema test rejects an entry
  version, and verify no staged or unstaged files fall outside this spec.

Observed evidence on 2026-07-27:

- Focused manifest, architecture, doc-link, script-ownership, and repository
  evidence checks passed (`35/35` after the final owner-chain update).
- `npm test` passed (`825/825`).
- `npm run pack:verify` passed with 299 npm entries and 327 runtime ZIP entries.
  The five new npm entries are the two Claude, one Codex, and two Cursor
  manifest files; the runtime ZIP retained its Qoder-only shell boundary.
- Active workflow and metadata searches found no `master`,
  `better-harness-dev`, `0.1.x`, or retired package-script fixture path outside
  historical migration/spec rationale.