pcina 0.1.1__tar.gz

pcina-0.1.1/.gitignore

@@ -0,0 +1,13 @@
+# pcina development
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+pcina-baseline.json

pcina-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alexkay28
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pcina-0.1.1/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.5
+Name: pcina
+Version: 0.1.1
+Summary: Python Code-pattern Investigator & Nonsense Analyzer - KISS/YAGNI harness for AI-generated code
+Project-URL: Homepage, https://github.com/AlexKay28/pcina
+Project-URL: Repository, https://github.com/AlexKay28/pcina
+Project-URL: Issues, https://github.com/AlexKay28/pcina/issues
+Project-URL: Changelog, https://github.com/AlexKay28/pcina/blob/main/docs/agentic-loop-goal.md
+Author: alexkay28
+License: MIT
+License-File: LICENSE
+Keywords: ai-generated-code,ast,code-quality,dead-code,kiss,linter,static-analysis,yagni
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# pcina
+
+Automatic checker for **KISS/YAGNI paradigm alignment**. pcina parses your Python code
+(pure `ast`, one pass) and rates it per aspect out of 10 — mechanizing the ethos of the
+classic KISS/YAGNI advice ("write the minimum code a new reader understands in one
+pass; build nothing speculative") into a single fast command. It targets the
+over-defensive, over-abstracted, over-nested output that both AI agents and humans
+produce — without importing anyone's opinion on formatting or typing.
+
+## Install
+
+Pure stdlib. Python >= 3.10. Zero runtime dependencies.
+
+```bash
+pip install pcina        # from PyPI
+# or
+pipx install pcina       # isolated CLI tool
+# or straight from GitHub
+pip install git+https://github.com/AlexKay28/pcina.git
+```
+
+Use it from Python too — scores and findings are plain data:
+
+```python
+from pcina.analyzer import analyze
+from pcina.metrics import findings_for
+from pcina.scoring import score
+
+project = analyze(["src/"], [])
+findings = findings_for(project)
+print(score(project, findings)["overall"])   # e.g. 9.48
+for f in findings:
+    if f.severity in ("warn", "error"):
+        print(f.severity, f.aspect, f"{f.file}:{f.line}", f.message)
+```
+
+
+## Quickstart
+
+```bash
+pcina scan src/                 # advisory report
+pcina check src/                # budget gate: exit 1 on violations (CI)
+pcina report --md src/          # markdown report (drops into an agent context)
+pcina baseline --save src/      # snapshot findings
+pcina baseline --compare src/  # delta vs snapshot
+pcina scan --json src/          # stable pcina/1 JSON schema
+pcina scan --diff main src/     # only findings on lines changed vs BASE (git)
+pcina scan --exclude 'tests/*' src/
+```
+
+## The 8 aspects
+
+| Aspect | Principle | Meaning |
+|---|---|---|
+| complexity | KISS | a reader should understand a function in one pass |
+| paranoia | KISS | validate at trust boundaries, not inside internal helpers |
+| nesting | KISS | flat beats nested — guard clauses, early return |
+| hardcode | KISS | no magic values forcing the reader to reconstruct facts |
+| clever | KISS | if a reader must mentally execute the line, rewrite it |
+| deadcode | YAGNI | unused code was never (or no longer) needed |
+| yagni | YAGNI | no speculative abstraction for hypothetical futures |
+| size | KISS | one outcome per function; a docstring is the 30-second test |
+
+## Terminal output (real run)
+
+`pcina scan src/` on pcina's own source:
+
+```
+== pcina scan: src/  (22 files, 974 LLOC) ==
+
+complexity : 9.9/10   paranoia : 10.0/10
+nesting    : 10.0/10   hardcode : 10.0/10
+deadcode   : 9.9/10   yagni    : 10.0/10
+clever     : 10.0/10   size     : 10.0/10
+
+src/pcina/analyzer.py:365 [warn][nesting] nesting depth 5 - invert conditions, return early
+  fix: guard clauses: invert the outer conditions and return
+src/pcina/cli.py:138 [warn][complexity] function _cmd_baseline complexity cc=15
+  fix: split the function or name complex conditions as predicates
+
+statistics:
+  loc=1485 lloc=974 files=22 functions=107 classes=11
+  docstring_coverage=79% comment_ratio=2%
+
+Your code has been rated at 9.82/10
+```
+
+Finding lines are single-line, greppable: `file:line [sev][aspect] message`.
+
+## Known false positives (honest)
+
+**Dynamic dispatch.** The deadcode aspect flags "no callers found" for functions wired
+up dynamically — CLI entry points, plugin registries, `__all__` re-exports. Static
+analysis cannot see those callers. **Verify before deleting anything** pcina marks
+as a deletion candidate.
+
+pcina already excludes from deadcode analysis: dunders (`__init__`, `__call__`, …),
+contents of `__init__.py` (import surface), functions named `main`, and test files.
+Typing imports used only in annotations, class bases and cross-module re-exports
+count as uses — all verified on real-world repos (see `docs/field-triage.md`).
+
+**Intentional import markers.** Two conventions from the wider tooling
+ecosystem (Ruff/Vulture) that pcina honors:
+
+```python
+from pkg import thing as thing  # redundant alias = explicit re-export marker
+import encodings.idna           # noqa: F401  # noqa = intentional, do not report
+```
+
+
+## Exit codes (contract)
+
+| Code | Meaning |
+|---|---|
+| 0 | clean — no budget violations |
+| 1 | budget violation (`pcina check`) |
+| 2 | error / CLI usage problem |
+
+Scores themselves are advisory; `pcina check` fails only on explicit budget
+violations, never on the rating.
+
+## Roadmap
+
+v0.1.1 "real-world proof" cycle — install from GitHub, proven on foreign repos,
+CI-gated: see [docs/agentic-loop-goal.md](docs/agentic-loop-goal.md).
+
+## License
+
+MIT

pcina-0.1.1/README.md

@@ -0,0 +1,129 @@
+# pcina
+
+Automatic checker for **KISS/YAGNI paradigm alignment**. pcina parses your Python code
+(pure `ast`, one pass) and rates it per aspect out of 10 — mechanizing the ethos of the
+classic KISS/YAGNI advice ("write the minimum code a new reader understands in one
+pass; build nothing speculative") into a single fast command. It targets the
+over-defensive, over-abstracted, over-nested output that both AI agents and humans
+produce — without importing anyone's opinion on formatting or typing.
+
+## Install
+
+Pure stdlib. Python >= 3.10. Zero runtime dependencies.
+
+```bash
+pip install pcina        # from PyPI
+# or
+pipx install pcina       # isolated CLI tool
+# or straight from GitHub
+pip install git+https://github.com/AlexKay28/pcina.git
+```
+
+Use it from Python too — scores and findings are plain data:
+
+```python
+from pcina.analyzer import analyze
+from pcina.metrics import findings_for
+from pcina.scoring import score
+
+project = analyze(["src/"], [])
+findings = findings_for(project)
+print(score(project, findings)["overall"])   # e.g. 9.48
+for f in findings:
+    if f.severity in ("warn", "error"):
+        print(f.severity, f.aspect, f"{f.file}:{f.line}", f.message)
+```
+
+
+## Quickstart
+
+```bash
+pcina scan src/                 # advisory report
+pcina check src/                # budget gate: exit 1 on violations (CI)
+pcina report --md src/          # markdown report (drops into an agent context)
+pcina baseline --save src/      # snapshot findings
+pcina baseline --compare src/  # delta vs snapshot
+pcina scan --json src/          # stable pcina/1 JSON schema
+pcina scan --diff main src/     # only findings on lines changed vs BASE (git)
+pcina scan --exclude 'tests/*' src/
+```
+
+## The 8 aspects
+
+| Aspect | Principle | Meaning |
+|---|---|---|
+| complexity | KISS | a reader should understand a function in one pass |
+| paranoia | KISS | validate at trust boundaries, not inside internal helpers |
+| nesting | KISS | flat beats nested — guard clauses, early return |
+| hardcode | KISS | no magic values forcing the reader to reconstruct facts |
+| clever | KISS | if a reader must mentally execute the line, rewrite it |
+| deadcode | YAGNI | unused code was never (or no longer) needed |
+| yagni | YAGNI | no speculative abstraction for hypothetical futures |
+| size | KISS | one outcome per function; a docstring is the 30-second test |
+
+## Terminal output (real run)
+
+`pcina scan src/` on pcina's own source:
+
+```
+== pcina scan: src/  (22 files, 974 LLOC) ==
+
+complexity : 9.9/10   paranoia : 10.0/10
+nesting    : 10.0/10   hardcode : 10.0/10
+deadcode   : 9.9/10   yagni    : 10.0/10
+clever     : 10.0/10   size     : 10.0/10
+
+src/pcina/analyzer.py:365 [warn][nesting] nesting depth 5 - invert conditions, return early
+  fix: guard clauses: invert the outer conditions and return
+src/pcina/cli.py:138 [warn][complexity] function _cmd_baseline complexity cc=15
+  fix: split the function or name complex conditions as predicates
+
+statistics:
+  loc=1485 lloc=974 files=22 functions=107 classes=11
+  docstring_coverage=79% comment_ratio=2%
+
+Your code has been rated at 9.82/10
+```
+
+Finding lines are single-line, greppable: `file:line [sev][aspect] message`.
+
+## Known false positives (honest)
+
+**Dynamic dispatch.** The deadcode aspect flags "no callers found" for functions wired
+up dynamically — CLI entry points, plugin registries, `__all__` re-exports. Static
+analysis cannot see those callers. **Verify before deleting anything** pcina marks
+as a deletion candidate.
+
+pcina already excludes from deadcode analysis: dunders (`__init__`, `__call__`, …),
+contents of `__init__.py` (import surface), functions named `main`, and test files.
+Typing imports used only in annotations, class bases and cross-module re-exports
+count as uses — all verified on real-world repos (see `docs/field-triage.md`).
+
+**Intentional import markers.** Two conventions from the wider tooling
+ecosystem (Ruff/Vulture) that pcina honors:
+
+```python
+from pkg import thing as thing  # redundant alias = explicit re-export marker
+import encodings.idna           # noqa: F401  # noqa = intentional, do not report
+```
+
+
+## Exit codes (contract)
+
+| Code | Meaning |
+|---|---|
+| 0 | clean — no budget violations |
+| 1 | budget violation (`pcina check`) |
+| 2 | error / CLI usage problem |
+
+Scores themselves are advisory; `pcina check` fails only on explicit budget
+violations, never on the rating.
+
+## Roadmap
+
+v0.1.1 "real-world proof" cycle — install from GitHub, proven on foreign repos,
+CI-gated: see [docs/agentic-loop-goal.md](docs/agentic-loop-goal.md).
+
+## License
+
+MIT

pcina-0.1.1/docs/adr/ADR-001-tool-scope-engine.md

@@ -0,0 +1,55 @@
+# ADR-001: Tool scope, engine and integration model
+
+- **Status:** Accepted (2026-10-30)
+- **Deciders:** user (alexkay28), builder agent
+- **Context:** AI agents write large volumes of over-defensive, over-abstracted, over-nested
+  code ("neuroslop"). Existing SOTA tools (Ruff, Radon, Vulture, Pylint, wemake-python-styleguide)
+  each emit per-rule findings but none answer *"how bloated is this code, per aspect, with one
+  fast command"* in a format both a human and an agent can act on. The user runs the
+  `alexkay/pythont-dry-code-devevelopment@1.1.0` skill, whose KISS/YAGNI smell taxonomy
+  (paranoid raises, deep nesting, magic values, speculative abstraction, shadowed names,
+  clever-code towers) pcina must mechanize.
+- **Core mission (user-confirmed 2026-10-30):** pcina plays the role of an **automatic checker
+  for YAGNI and KISS paradigm alignment**. This is the backbone and the actual goal of the
+  library. Every metric, finding, score and budget must justify itself as enforcing KISS
+  (minimum code a new reader understands in one pass, flat over nested, no cleverness
+  towers, no magic values, no paranoia at non-boundary call sites) or YAGNI (nothing
+  speculative: no unused/dead code, no zero-caller abstractions, no "in case we need it
+  later" layers). Findings that cannot be traced to KISS or YAGNI do not belong in pcina;
+  general style/typing/lint coverage is explicitly out of scope (Ruff's job). Principle map:
+
+| Aspect | Principle | Principle anchor |
+|---|---|---|
+| complexity | KISS | understands in one pass: limited branching per responsibility |
+| paranoia | KISS | keep validation only at trust boundaries; internal paranoia is cognitive noise |
+| nesting | KISS | flat is better than nested (guard clauses, early return) |
+| hardcode | KISS | magic values force the reader to reconstruct domain facts |
+| clever | KISS | if a reader must mentally execute the line, rewrite it |
+| deadcode | YAGNI | unused code was never (or no longer) needed |
+| yagni | YAGNI | speculative abstraction for hypothetical futures |
+| size | KISS | one outcome per function; docs == the 30-second reconstruction test |
+- **Decision:**
+  1. pcina is a **single pure-stdlib `ast` analyzer** (one parse per file, one visitor pass)
+     with **zero runtime dependencies**. Ruff/Vulture are optional future backends, never core.
+  2. Metric families (v1, all included): `complexity`, `paranoia`, `nesting`, `hardcode`,
+     `deadcode`, `yagni`, `clever`, `size` (docs/params/LOC). Findings attach to code
+     **sections** (module → class → function) and are advisory review candidates.
+  3. CLI: `scan` (report), `check` (budget gate, exit 1 on violation), `report`
+     (markdown), `baseline` (snapshot/delta). `--diff BASE` filters to changed lines.
+  4. Three output formats: human terminal (color), `--json` (stable schema v1, agent
+     target), `--md` (drops into an agent context per skill step 6).
+  5. Every report ends with the **pylint-style rating line, per-aspect scores and a
+     statistics block** (spec in ADR-002).
+  6. Validation heuristics distinguish **trust boundaries** (entry points, IO, config,
+     `__init__`, decorated endpoints, CLI `main`) from internal code; repeated defensive
+     validation inside internal helpers is flagged, boundary validation is not.
+  7. Acceptance: pcina must rate its own source ≥ 9.0/10 and produce zero `error` findings
+     on itself (self-application gate), zero warn/error on the `clean/` fixture, and the
+     expected finding set on the `neuroslop/` fixture.
+- **Consequences:** we own all semantics (no Radon dependency, which is largely
+  unmaintained) at the cost of writing our own reference scanner for dead-code. The tool
+  stays installable everywhere via stdlib only, and fast (target: 100k LOC < 5 s,
+  parallel parse via `concurrent.futures`).
+- **Alternatives rejected:** wrapping external tools (slow, dependency-heavy, unsuitable
+  for inline agent loops); Ruff-plugin form (Ruff cannot express aggregate per-aspect
+  scoring and section grouping the user requires).

pcina-0.1.1/docs/adr/ADR-002-scoring-model.md

@@ -0,0 +1,143 @@
+# ADR-002: Scoring model and statistics calculation (internal_spec)
+
+- **Status:** Accepted (2026-10-30)
+- **Deciders:** user (alexkay28), builder agent
+- **Context:** the user requires a pylint-like evaluation experience:
+  an overall rating (`Your code has been rated at 9.48/10`), per-aspect scores, and a
+  statistics block — but Pylint's own score mixes unrelated message categories and
+  penalizes convention noise heavily. Semgrep's lesson: output must be plain,
+  greppable, line-oriented so both humans and shell/awk-ish consumers can use it.
+- **Decision:** the model below is the **normative internal specification**. Scores are
+  advisory signals, never CI gates (gates are budget violations, see ADR-001).
+
+## 1. Base quantities
+
+| Quantity | Definition (normative) |
+|---|---|
+| `LOC` | physical non-blank lines of the analyzed sources |
+| `LLOC` | logical lines: count of `ast.stmt` nodes, excluding `FunctionDef`/`AsyncFunctionDef`/`ClassDef` **signature lines only** (their bodies count). Comments and docstrings excluded |
+| `N_FUN`, `N_CLS` | counts of analyzed function/class definitions |
+| `DOC_COVERED` | functions/classes/modules with a non-empty docstring |
+
+## 2. Severity and finding weights
+
+Finding severity (per ADR-001 metric table):
+
+| Severity | Meaning | Base weight `w` |
+|---|---|---:|
+| `error` | near-certain defect or strong bloat (bare except, shadowed module import, unused-export) | 3.0 |
+| `warn` | smell needing review | 1.0 |
+| `info` | advisory observation | 0.2 |
+
+## 3. Aspect scores
+
+Every finding belongs to exactly one aspect: `complexity`, `paranoia`, `nesting`,
+`hardcode`, `deadcode`, `yagni`, `clever`, `size`.
+
+For aspect `a` over scope with `LLOC` statements:
+
+```
+P_a = Σ (w(severity_i) * aspect_penalty_mult[a] * fix_loc_mult_i)   for findings i in a
+score_a = clamp(0, 10 - K * P_a / max(LLOC, 50))
+```
+
+- `K = 10` (so weighted penalty equal to LLOC ⇒ score 0; pylint's "10 - …" shape).
+- `max(LLOC, 50)`: small files must not produce wild scores from 2 findings.
+- `fix_loc_mult_i` = 1.0 (flat for v1; reserved for severity scaling by lines touched).
+- `aspect_penalty_mult` — because aspects differ in natural frequency:
+
+| Aspect | mult | Rationale |
+|---|---:|---|
+| complexity | 1.5 | one bad function is a real comprehension cost |
+| paranoia | 1.0 | frequent; most common AI smell |
+| nesting | 1.5 | strong readability damage |
+| hardcode | 0.5 | mostly cosmetic |
+| deadcode | 1.5 | deleted code is pure win |
+| yagni | 1.0 | speculative layers |
+| clever | 1.0 | localized cleverness |
+| size | 0.5 | docs/params are softer signals |
+
+These multipliers are software calibration constants: they live in
+`pcina/scoring.py` as a data table, are printed via `pcina report --show-weights`,
+and must never be duplicated elsewhere.
+
+## 4. Overall rating
+
+```
+P = Σ P_a over all aspects
+rating = clamp(0, 10 - 10 * P / max(LLOC, 50))    # one decimal, pylint-style line
+```
+
+The overall rating is **not** a quality verdict (per skill: tool scores guide review).
+`pcina check` never fails on the rating — only on explicit budget violations.
+
+## 5. Statistics block (normative fields)
+
+Report must always end with (term and `--md` formats; same fields under `statistics`
+in JSON):
+
+```
+statistics:
+  loc=520 lloc=231 files=9 functions=47 classes=8
+  docstring_coverage=72% comment_ratio=11%
+  avg_cc=4.2 max_cc=17 p75_cc=6
+  raises=31 try_except=12 bare_excepts=0
+  dead_candidates=5 yagni_candidates=3 magic_values=14
+```
+
+Definitions:
+
+- `avg_cc`, `max_cc`, `p75_cc`: cyclomatic complexity over functions (radon CC semantics:
+  +1 per `if/elif/for/while/except/with/assert/comprehension/bool-op`).
+- `comment_ratio` = comment lines / LOC (as `%`).
+- `docstring_coverage` = documented defs+modules / total defs+modules (as `%`).
+- Counters (`raises`, …) = raw pattern occurrences as defined per metric module.
+
+## 6. Human output template (term format)
+
+```
+== pcina scan: src/  (9 files, 231 LLOC) ==
+
+complexity : 9.3/10   paranoia : 4.2/10
+nesting    : 8.8/10   hardcode : 6.1/10
+deadcode   : 9.9/10   yagni    : 9.0/10
+clever     : 9.7/10   size     : 9.5/10
+
+src/api.py:42 [warn][paranoia] 6 'raise' guards in internal helper 'load_user_args' — validation belongs to trust boundary
+  fix: keep one boundary check in caller; delete redundant guards
+...
+
+statistics:
+  loc=... lloc=... (see §5)
+
+Your code has been rated at 8.42/10
+```
+
+- Finding lines are single-line `file:line [sev][aspect] message` — greppable,
+  `awk`/`grep`-friendly (`grep '\[warn\]'`), mirroring semgrep's usability lesson.
+- The rating line is machine-matchable: `^Your code has been rated at ([0-9.]+)/10$`.
+- With `--compare-baseline` the rating line gains `(previous: X.XX/10, +Δ)`, pylint-style.
+
+## 7. JSON schema v1 (frozen at v1.0.0)
+
+```json
+{
+  "schema": "pcina/1",
+  "scope": {"roots": ["src"], "files": 9, "loc": 520, "lloc": 231},
+  "scores": {"overall": 8.42, "aspects": {"complexity": 9.3, "...": 0}},
+  "statistics": {"functions": 47, "...": 0},
+  "findings": [
+    {"aspect": "paranoia", "severity": "warn", "file": "src/api.py", "line": 42,
+     "section": "api:load_user_args", "metric": "raise-guard-burst",
+     "message": "...", "fix": "..."}
+  ],
+  "budget_violations": []
+}
+```
+
+Additive-only changes allowed within schema version; renames require `pcina/2`.
+
+- **Consequences:** deterministic, testable scores (snapshot tests on fixtures);
+  calibration is one data table; small-file floor of 50 LLOC prevents noise spikes.
+  Risk: multipliers are judgment calls — mitigated by fixture calibration tests
+  (clean fixture must rate ≥ 9.0, neuroslop fixture ≤ 6.0).

pcina-0.1.1/docs/agentic-loop-goal.md

@@ -0,0 +1,80 @@
+# Agentic loop goal — v0.1.1 "real-world proof" cycle
+
+- **Status:** Active (2026-10-30)
+- **Loop:** `/loop 5m [investigate - plan - todo - implement - check - apply pcina on itself - check - fix - log]`
+- **Session protocol (unchanged):** plan in main session, spawn subagent "developers"
+  with strict file ownership and normative ADRs as contracts; main session keeps
+  headroom for common sense and verification only.
+
+## Vision (why this cycle exists)
+
+v0.1 closed the self-application loop: 8 KISS/YAGNI metric families, scoring
+(ADR-002), CLI with scan/check/report/baseline, 42 tests green, self-rated
+**9.82/10 with zero errors**. A tool that scores itself is credible; a tool nobody
+else can install and run is a diary entry. This cycle upgrades pcina from a
+verified prototype to a **shippable, externally-consumable tool proven on code it
+did not write** — without breaking its own backbone rule: every change must
+enforce KISS or YAGNI (ADR-001 principle map).
+
+## Goal statement (v0.1.1)
+
+Any developer (or AI agent) must be able to `pipx install pcina` (or from GitHub),
+run `pcina scan` on an arbitrary Python repo in one command, get per-aspect
+scores with actionable findings, and gate CI with `pcina check` — and pcina's
+own self-score must stay >= 9.0 with zero errors.
+
+## Success criteria (all must be true at cycle end)
+
+1. **README.md exists** at repo root: what/why (anti-"neuroslop" KISS/YAGNI checker),
+   install, quickstart, aspect table (from ADR-001), exit-code contract, output
+   format samples (term + json + md). Written for someone who has never seen an ADR.
+2. **Runs clean on foreign code:** `pcina scan` (and `--json`) executes without
+   crash on >= 3 real external repos (e.g. local clones chosen by size/variety —
+   must include one repo that is deliberately over-engineered). Triage every crash
+   and every obviously-bogus finding found this way; either fix the metric or
+   document the exclusion — no silent ignoring.
+3. **CI gate:** a GitHub Actions workflow (pure stdlib, no pip deps) running pytest +
+   `pcina check src/` with budgets configured so the gate fails on error findings.
+   The repo's own main branch must pass it.
+4. **False-positive budget shrinks:** the two bug classes found by self-scan
+   (decorators, `__all__`) get regression tests in `tests/`; any new FP found on
+   foreign code gets a test too. "Known FP list" documented in README honestly.
+5. **Self-discipline maintained:** pcina self-score >= 9.0, zero errors, pytest green,
+   `pyproject.toml` version bumped to 0.1.1, everything pushed to GitHub `main`.
+
+## Non-goals (say no in this cycle)
+
+- No new metric families (beyond the 8) — reach comes before depth.
+- No Ruff/Vulture backends, no LLM integration, no config language growth.
+- No refactoring round for the accepted warns in analyzer/diff/files/cli
+  (tracked, but roadmap belongs to v0.2), unless a foreign-code crash forces it.
+
+## Out-of-scope guard (from ADR-001, restated)
+
+Findings that cannot be traced to KISS or YAGNI do not belong in pcina. General
+style/typing/lint coverage stays out — Ruff's job.
+
+## Suggested developer split (subagents with file ownership)
+
+- **dev-R:** `README.md` (+ nothing else). Input: both ADRs + `--help` output.
+- **dev-F (field testing):** no src ownership — drives `pcina scan --json` on 3+
+  foreign repos, writes `docs/field-triage.md` with crash log + FP triage. Fixes
+  assigned back to owners.
+- **dev-Ci:** `.github/workflows/ci.yml` + minimal `pcina.toml` budgets for src/.
+- **dev-M (metric fixes):** `src/pcina/metrics/*` + `tests/` regression tests
+  for every FP dev-F reports.
+- Owners of analyzer/scoring/cli stay as in docs/dev-tasks.md for crash fixes.
+
+## Cycle log
+
+- 2026-10-30 (main session I): goal defined after v0.1 verification closed (9.82/10 self-score).
+- 2026-10-30 (main session II): COMPLETE — all 5 success criteria met:
+  1. README.md shipped (dev-R subagent; install via git+ URL, real output sample, honest FP section).
+  2. Field runs: requests (9.55), flask (9.68), poetry (9.59) — zero crashes, valid pcina/1 JSON; poetry (over-engineered target) shows ~6x findings density.
+  3. CI gate: DESOPED by user decision (2026-10-30) — "we don't need ci now". The blocker was account-level Actions scheduling on a private repo (no runner assigned, 3s, no logs — billing/quota side). The `pcina.toml` baseline budget gate stays as a LOCAL gate (`pcina check src/` -> exit 0); workflow was removed. Re-add CI in a later cycle when the repo goes public or billing is sorted.
+  4. Five FP classes fixed (annotations, class bases, cross-module re-exports, `__init__.py` surface + latent INIT_BASENAME bug, noqa markers) — each has a regression test in tests/test_field_regressions.py (52 tests total, incl. over-suppression guard and self-score floor >= 9.0). Industry conventions adopted after web research: Ruff F401 (redundant alias, ignore-init-module-imports), Vulture (#216 annotation refs, noqa, confidence laddering).
+  5. Version 0.1.1, pushed to origin/main; pytest 52 passed; self-scan 9.80/10 zero errors; `pcina check` exit 0.
+
+Every loop iteration appends one line to this file under "Cycle log"
+(timestamp, what was investigated/implemented, self-score, verdict).
+Full triage: docs/field-triage.md.