Flow-Next Files

Changed

• Opinionated, structure-aware /flow-next:prime (fn-92). At portfolio scale the old existence-checks lie: a repo could pass prime's criteria (a CLAUDE.md exists, a hook file exists, a lint script exists) yet be un-agentic in practice (empty template, broken build, unresolved imports, or really one of 99 sibling repos), and there was no way to hand-verify hundreds of repos across 10-11 stacks. Prime is rebuilt to classify what kind of project this is, judge substance not existence, and lead with a verdict + ranked next-actions instead of a maturity level. No new mode and no flag toggling the old behavior back on (that would preserve the failure mode this retires); the 8-pillar scan stays as the evidence layer underneath, and existing args (--report-only, --fix-all, repo-root path) keep their semantics. The one new arg is --classify-only.
• Phase 0.5 classification - a five-axis project profile (lifecycle, topology as two independent bits monorepo/constellation-member, size/legibility band, stack(s), delivery shape(s)) plus an orthogonal assessment_scope (repository | workspace-member | constellation-home-base). It parameterizes everything downstream: scout dispatch hints, N/A denominators, report shape, and playbook selection.
• Operability ladder + hard gates - Phase 2 now judges whether an agent can actually operate the repo from executed evidence: tier 1 (build runs) / tier 2 (tests discoverable and run) / tier 3 (app boots to a ready signal), per-surface with a min-deployable headline and per-member tiers on monorepos. Three hard gates - G1 (build actually runs), G2 (tests discoverable when a framework is claimed), G3 (agent-file quoted commands resolve/execute) - are named in the headline and cap the maturity level at 2 when failing. The maturity level is demoted to secondary metadata below the scores table.
• New agent-readiness groups - agent observability & drivability (AO/DR), a tooling/operability group (TO), and a harness & permissions group (HP) synthesized host-inline in Phase 3, feeding the verdict; the enable-QA recommendation fires only at operability tier 3 with all four DR-core passing.
• Per-shape playbooks + per-stack matrix - five delivery-shape playbooks (greenfield / standard / monorepo / huge-legacy / constellation, plus a light variant), a tiered ranked-actions catalog, the LEG1-LEG9 legibility patterns, and a 15+-row per-stack matrix where adding a stack is a data row, never a skill-logic edit; an unknown stack degrades to the generic operability ladder with an honest "no per-stack playbook yet" line.
• New deterministic flowctl surface - flowctl prime classify [root] --json (the ONLY flowctl addition): a pure-stdlib, bounded, no-LLM emitter for Phase 0.5's raw signals (axes 1-4 values + mechanical confidence, raw Axis-5 shape markers, per-collector completeness diagnostics). All judgment (shape reasoning, final confidence, clarification asks, playbook selection) stays in the skill. Dual-copy byte-identical across plugins/flow-next/scripts/flowctl.py and .flow/bin/flowctl.py (parity-tested), with a redaction contract (evidence carries key names only, never secret values or complete sensitive config lines; fixture-asserted) and per-collector budgets that keep it under ~10s on a multi-M-LOC repo.
• --classify-only - wraps the emitter plus the judgment layer, prints the classification block and exits in seconds; the portfolio-triage entry point for 100+ repos. Never asks (prints confidence + a would-ask list instead of the Phase 0.6 clarification).
• Two-oracle eval split - a CI oracle tests the EMITTER only (raw signals, markers, exclusions on synthetic fixtures, 3-OS deterministic, wired into .github/workflows/test-flow-next.yml); a non-CI agentic harness under optimization/prime/ (defined runner, model/version provenance, pass rubric, blocking threshold) evaluates the final five-axis judgment. Prose-contract tests pin skill wording but never claim to prove judgment.
• Supporting rewrites - pillars.md (substance pass-conditions, new group tables, single N/A whitelist, and a criterion-to-score map carrying a probe-owner column: emitter / host-inline / scout); four new reference files under the skill (classification.md, playbooks.md, stacks.md, harness.md) plus remediation.md for the new artifacts (orientation map, home-base kit, encoding guard, compile wrapper, deny-rules baseline, run-and-observe recipe); claude-md-scout gains a DC2 substance rubric + stack-row dispatch context. Codex mirror regenerated.
• Vocabulary - GLOSSARY.md gains Operability ladder, Hard gate, Delivery shape, and Classification (prime) as public terms.
• Pending downstream (flow-next.dev, deferred to the maintainer's release walk per amended R14): a public prime docs-site page reflecting the verdict/classification framing, plus its entries in both navigation sources (the DocsRail.astro/site.ts left rail AND the astro.config.mjs Starlight sidebar), and a docs-site changelog entry. In-repo docs keep skills.md (+ the SKILL.md and its four references) as the canonical surface; there is deliberately no plugins/flow-next/docs/prime.md page.
• Post-plan hardening via PR review (29 bot-review waves on PR [#207]) - the emitter absorbed a long adversarial review cycle: envelope truthfulness (capped reads/scans mark truncated, sampled LOC never ranks stacks), CI-gate honesty (gated_test_step/gated_lint_step per-workflow conjunction, executable-content-only matching, installer/echo/comment segments excluded, gitlab/bitbucket/azure/CircleCI trigger semantics, default-write formatters count as mutating), security hardening (metacharacter-rejection/argv-only rule in §2.6 pinned by prose-contract tests, build probe captures its own exit status, hook matched_tokens whitelist, root-containment + symlink guards on all tracked reads, eval-harness isolation breaches incl. projection tamper/stderr leaks/deleted sentinels), and classification fixes (single-squash source imports are brownfield, lockfile is a corroborator only, workspace-member re-rooting, gitdir-pointer resolution, LOC-weighted stack shares). 187 emitter tests in the CI oracle.