Oss ready

OSS Ready

Makes a repository easier to understand, trust, try, and share. Transfers Impeccable's context → isolated critique → evidence audit → bounded polish → fresh verification loop to OSS surfaces.

Setup

Before any command:

1. Resolve one repository root, owner/repo slug when available, public URL, and current content revision. Dirty-tree content is part of the revision. Never drift into another checkout or a scenario's surrounding workspace.
2. Read references/contract.md. Its launch gates, evidence states, finding schema, and mutation boundary are mandatory.
3. Inspect .oss-ready/BRIEF.md when present. Treat every UNCONFIRMED field as unknown. Never expose this private brief to Critique A.
4. Select one archetype from references/vocabulary.md: visual app, CLI, library/framework, platform/service, template/design system, or infrastructure/headless.
5. For critique and polish, also read references/personas.md and references/vocabulary.md.
6. Record capabilities before judging: fresh subagent, browser, anonymous network access, GitHub surface/API, package registry, and clean-room execution. Missing evidence makes affected gates degraded or unverified; it never becomes a pass.

Routing

• No argument: inspect current context, recommend the best 2–3 exact commands with one-line reasons, then show init, critique, and polish. Never auto-run a command.
• init [root]: establish private confirmed context and the canonical first-value event.
• critique [root|owner/repo|URL]: report-only public visitor and evidence review.
• polish [root]: consume the latest matching critique, fix approved local surfaces, then re-critique in fresh context.
• Unknown first word: map it to the closest command and state the mapping.

audit is Critique B's deterministic phase, not a public fourth command.

init

1. Inspect README, docs, manifests, real media, release/package surfaces, and repository instructions. Extract hypotheses, not facts the user never confirmed.

2. Run:

   python3 <skill-base>/scripts/context.py init <root>
   

   The helper creates mode-0600 .oss-ready/BRIEF.md, adds .oss-ready/ to .git/info/exclude, and refuses overwrite.

3. Ask only for unknown decisions needed to fill: primary audience, category, core promise, canonical first-value event, expected time, supported environment, primary conversion, proof on hand, contribution/support posture, and constraints.

4. Write confirmed answers into the brief. Leave unknowns UNCONFIRMED; never invent claims, proof, compatibility, adoption, timing, or maintainer promises.

5. Confirm the brief before any later public mutation. Missing context does not block a scoped critique, but it blocks READY.

critique

Critique is read-only. It uses two isolated assessments and shows nothing until synthesis.

Start and provenance

Run critique_state.py start <root> with all six required capabilities from the contract as --capability NAME=available|unavailable|degraded|declined. Preserve the returned run path.

The final report's first line must be one of:

• PROVENANCE: isolated Critique A → sealed → isolated Critique B
• ⚠️ DEGRADED: single-context (<reason>)

If a fresh context is available, using it is mandatory. If unavailable, run A fully before B, print the degraded banner, and forbid READY.

Critique A — blind public visitor

Give a fresh reviewer only the anonymous, visitor-visible rendered repository surface and one selected persona. Do not provide .oss-ready/BRIEF.md, source code, local file inventory, detector output, private instructions, Critique B results, or intended positioning.

Ask the reviewer to attempt the visitor path and return JSON containing:

• what the project appears to be, for whom, and why it is different;
• next action and expected first value;
• exact comprehension, trust, proof, and activation break points;
• strengths worth preserving;
• direct public evidence only.

Save the JSON, then seal it before starting B:

python3 <skill-base>/scripts/critique_state.py seal-a <run> <assessment-a.json>

Critique B — audit and real path

Use a separate fresh reviewer. It may read the brief, source tree, repository instructions, and deterministic facts. It must:

1. Run python3 <skill-base>/scripts/evidence.py <root>.
2. Inspect the logged-out rendered GitHub page at desktop and narrow width when browser access exists: description, topics, homepage, social preview, README assets, anchors, primary links, releases, packages, and public support routes.
3. Follow the documented canonical path from a clean clone/container/sandbox in the declared supported environment. Record commands, elapsed time, interventions, exit state, and the observable first-value result. Never silently repair instructions during the test.
4. Validate public claims against current, reproducible evidence. Treat scripts as defect evidence only; clean output is never proof of comprehension or product value.
5. Return JSON with capability limits, local facts, rendered observations, clean-room journey, claim evidence, and findings.

Record B only after A is sealed:

python3 <skill-base>/scripts/critique_state.py record-b <run> <assessment-b.json>

Synthesis

Read both sealed artifacts. Reconcile what A perceived with what B verified. Do not retroactively rewrite A using private facts.

Every finding must name: ID, persona, attempted task, break point, direct evidence, consequence, severity P0|P1|P2|P3, confidence, exact fix, and validation method. Report verified strengths with the same specificity. Synthetic personas are agent reviews, never “user-tested.”

Use only launch gate READY|BLOCKED and evidence states VERIFIED|UNVERIFIED|DEGRADED|NOT_APPLICABLE. Never produce numeric readiness ratings. READY requires every applicable hard gate verified, a successful first-value journey, and zero P0 findings.

If a user requests an N-point score, decline the scale. Do not mirror it as an N-row, point-equivalent, or numbered checklist. Report only applicable hard gates and evidence.

Save synthesis JSON and finalize:

python3 <skill-base>/scripts/critique_state.py finalize <run> <synthesis.json>

Then present: provenance; verdict; gate evidence; P0/P1 findings; strengths; ordered fixes; human-validation gaps; and exact degraded limits.

polish

Polish fixes repository presentation, not the product's whole codebase.

Never add or change application code, runtime behavior, authentication, authorization, login, passkeys, security keys, or product promotion gates as repository polish. If the audit exposes a missing product capability, report it as a finding; do not build it unless the user separately requests that product change.

1. Run critique_state.py latest <root>. Use only a complete snapshot for the same target. If none matches, run critique first. Treat old revision evidence as a prior to reverify, never current truth.
2. Reinspect the surface. Classify each issue by root cause: positioning, information order, activation path, missing/false proof, trust posture, public metadata, or media quality.
3. State the bounded file/surface plan. An explicit polish request authorizes relevant local edits within repository instructions. Get human approval before any broader or public action.
4. Fix P0 then P1. Preserve project voice and real measurements. Use only media and badges that carry current evidence. Never synthesize product UI, fabricate claims, or add community files without a maintainer owner.
5. Do not commit, push, open a pull request, edit GitHub topics/description/homepage/social preview, publish a package/release, merge, or announce without human approval or an exact standing repository authorization.
6. Run repository-prescribed tests plus link, render, asset, and clean-room checks. Fix regressions caused by the polish.
7. Re-run the full critique with a fresh Critique A context that cannot see the implementation transcript or prior findings. Report resolved, unresolved, and new finding IDs.

Non-goals

• General code-health, architecture, lint, or security review, except failures blocking a public promise.
• Automatic testimonials, benchmarks, roadmap promises, support promises, or compatibility claims.
• Synthetic product screenshots or decorative proof.
• Mandatory badges, graphs, community bureaucracy, or contributor surfaces for every archetype.
• Default-branch writes, merges, releases, or promotion without human approval.