vibecodedshit 0.0.0-stage → 0.3.0

package/methodology/v1.0/dimensions/6-operability-feedback-loop.yaml

@@ -0,0 +1,279 @@
+dimension:
+  id: 6
+  key: operability_feedback_loop
+  name: Operability & feedback loop
+  question: Can someone new set it up, check a change and know they are done?
+  agent_relevance: >-
+    An agent needs a command that tells it whether its change is correct,
+    and it needs to find that command without asking. A slow or missing
+    check means the agent stops early or guesses.
+
+script_resolution: >-
+  Parameters 6.2, 6.4 and 6.6 follow package.json scripts, Makefile targets,
+  justfile recipes, tox and nox sessions, and pyproject.toml script tables up
+  to 3 levels deep. Recognised tools: typecheckers tsc, vue-tsc, pyright,
+  basedpyright, mypy; linters eslint, biome, oxlint, ruff, flake8, pylint;
+  test runners vitest, jest, mocha, node --test, pytest, python -m unittest,
+  tox, nox. The prefixes npx, bunx, pnpm exec, yarn, uv run, poetry run,
+  pdm run and python -m are removed before a command is matched.
+
+parameters:
+  - id: "6.1"
+    key: install_and_build
+    name: Clean install and build
+    layer: execution
+    weight: 25
+    requires: []
+    pooling: unit_weighted
+    raw:
+      unit: level
+      definition: >-
+        Result of a clean install from the lockfile, followed by the build
+        step, in the pinned runner.
+      when_empty: 0
+    scoring:
+      method: levels
+      levels:
+        - level: install_fails
+          score: 0
+          descriptor: The project does not install from a clean checkout.
+        - level: build_fails
+          score: 40
+          descriptor: It installs, but the build fails.
+        - level: works
+          score: 100
+          descriptor: >-
+            It installs and builds from a clean checkout. A project with no
+            build step scores 100 when the install succeeds.
+    measure:
+      typescript_javascript: >-
+        Install: npm ci, pnpm install --frozen-lockfile, yarn install
+        --immutable or bun install --frozen-lockfile, chosen by lockfile;
+        npm install when there is no lockfile. Build: the build script in
+        package.json, when one exists.
+      python: >-
+        Install: uv sync --frozen, poetry install --sync, pdm sync, pipenv
+        sync, or pip install -r on the requirements files, chosen by
+        lockfile; pip install . when there is only a pyproject.toml. Build:
+        python manage.py check for Django projects; otherwise importing
+        each first-party top-level package.
+    not_applicable_when: null
+    rationale: >-
+      Everything in the execution layer depends on this step. A project that
+      does not install from a clean checkout depends on someone's machine.
+    sources: []
+
+  - id: "6.2"
+    key: one_command_verify
+    name: One-command verify
+    layer: static
+    weight: 15
+    requires: []
+    pooling: unit_weighted
+    raw:
+      unit: count of checks (0-3)
+      definition: >-
+        The largest number of the three checks (typecheck, lint, tests) that
+        a single entry point runs: one package.json script, Makefile target,
+        justfile recipe, tox or nox session, or pyproject script.
+      when_empty: 0
+    scoring:
+      method: levels
+      levels:
+        - level: "0"
+          score: 0
+          descriptor: No single command runs any check.
+        - level: "1"
+          score: 33
+          descriptor: One command runs one check.
+        - level: "2"
+          score: 66
+          descriptor: One command runs two checks.
+        - level: "3"
+          score: 100
+          descriptor: One command runs typecheck, lint and tests.
+    measure:
+      all_languages: Static resolution of entry points as described in script_resolution.
+    not_applicable_when: null
+    rationale: >-
+      "Run this and it tells you if you are done" is the most useful fact
+      an agent can learn about a repository. Without it, the agent has to
+      find and run each check separately, and often skips one.
+    sources: []
+
+  - id: "6.3"
+    key: feedback_loop_time
+    name: Feedback loop time
+    layer: execution
+    weight: 10
+    requires: [install, typecheck_run, lint_run, test_run]
+    pooling: unit_weighted
+    raw:
+      unit: seconds
+      definition: >-
+        Summed wall-clock time of the methodology's own typecheck (2.1),
+        lint (2.5) and test (1.1) runs on the pinned runner.
+      when_empty: 0
+    scoring:
+      method: piecewise_linear
+      anchors:
+        - raw: 60
+          score: 100
+          descriptor: A full check takes about a minute.
+        - raw: 180
+          score: 75
+          descriptor: A full check takes a few minutes.
+        - raw: 600
+          score: 50
+          descriptor: The ten-minute build.
+        - raw: 1200
+          score: 0
+          descriptor: Nobody runs the full check locally.
+    measure:
+      all_languages: Wall-clock time recorded by the orchestrator for the three steps.
+    not_applicable_when: null
+    rationale: >-
+      A slow check gets run less often, by people and by agents. This is
+      the only parameter whose raw value varies between identical runs, so
+      its weight is low and the runner hardware is fixed.
+    sources:
+      - "Beck, K. Extreme Programming Explained, 2nd ed. Addison-Wesley, 2004 (Ten-Minute Build)."
+      - "Fowler, M. Continuous Integration. https://martinfowler.com/articles/continuousIntegration.html"
+
+  - id: "6.4"
+    key: ci_runs_checks
+    name: CI runs the checks on pull requests
+    layer: static
+    weight: 20
+    requires: []
+    pooling: unit_weighted
+    raw:
+      unit: count of checks (0-3)
+      definition: >-
+        How many of the three checks (typecheck, lint, tests) CI runs on
+        pull requests or on every push. Checks may be spread across jobs
+        and workflows.
+      when_empty: 0
+    scoring:
+      method: levels
+      levels:
+        - level: "0"
+          score: 0
+          descriptor: CI runs no checks, or there is no CI.
+        - level: "1"
+          score: 33
+          descriptor: CI runs one check.
+        - level: "2"
+          score: 66
+          descriptor: CI runs two checks.
+        - level: "3"
+          score: 100
+          descriptor: CI runs typecheck, lint and tests on every pull request.
+    measure:
+      all_languages: >-
+        CI files as listed in 3.1. A workflow counts if it is triggered on
+        pull_request, pull_request_target, merge_request events, or on push
+        without a branch filter that limits it to the default branch.
+        Commands are resolved as described in script_resolution.
+    not_applicable_when: null
+    rationale: >-
+      Local checks are optional; CI checks are not. CI is what keeps the
+      score from dropping after the audit ends.
+    sources:
+      - "Fowler, M. Continuous Integration. https://martinfowler.com/articles/continuousIntegration.html"
+
+  - id: "6.5"
+    key: reproducible_environment
+    name: Reproducible environment
+    layer: static
+    weight: 15
+    requires: []
+    pooling: unit_weighted
+    raw:
+      unit: score
+      definition: Mean of two components.
+      when_empty: 0
+    scoring:
+      method: mean_of_components
+      components:
+        - key: runtime_pinned
+          name: Runtime version pinned
+          method: levels
+          levels:
+            - level: "no"
+              score: 0
+            - level: "yes"
+              score: 100
+          measure: >-
+            Any of .nvmrc, .node-version, .tool-versions, mise.toml,
+            engines.node in package.json, volta in package.json,
+            .python-version, requires-python in pyproject.toml, or
+            runtime.txt.
+        - key: env_documented
+          name: Environment variables documented
+          method: ratio
+          definition: >-
+            Variable names read in logic files that appear in an env example
+            file / all variable names read in logic files, times 100. No
+            variables read scores 100.
+          measure: >-
+            Example files: .env.example, .env.sample, .env.template,
+            .env.dist, example.env. Reads: process.env.X, process.env["X"],
+            destructuring from process.env, import.meta.env.X,
+            os.environ["X"], os.environ.get("X"), os.getenv("X"). Excluded
+            names: NODE_ENV, CI, HOME, PATH, PWD, TZ, NEXT_RUNTIME, and
+            names starting with VERCEL_, NETLIFY, RENDER_, RAILWAY_ or
+            GITHUB_.
+    measure:
+      all_languages: Static reads of the files and patterns listed in the components.
+    not_applicable_when: null
+    rationale: >-
+      A missing environment variable is a common reason a fresh checkout
+      does not start, and an agent cannot guess the names. Config read from the
+      environment, with the names documented, is the Twelve-Factor approach.
+    sources:
+      - "The Twelve-Factor App, III. Config. https://12factor.net/config"
+
+  - id: "6.6"
+    key: agent_instructions
+    name: Commands documented for agents
+    layer: static
+    weight: 15
+    requires: []
+    pooling: unit_weighted
+    raw:
+      unit: level
+      definition: >-
+        Whether the repository documents how to install, run and check it,
+        and whether the documented commands exist.
+      when_empty: 0
+    scoring:
+      method: levels
+      levels:
+        - level: none
+          score: 0
+          descriptor: No documented commands.
+        - level: readme
+          score: 50
+          descriptor: >-
+            README documents commands, or an agent instructions file exists
+            but at least one command in it does not resolve.
+        - level: agent_file
+          score: 100
+          descriptor: >-
+            AGENTS.md or CLAUDE.md at the repository root documents
+            commands, and every command in it resolves.
+    measure:
+      all_languages: >-
+        A command is an inline code span or a line in a fenced code block
+        that starts with a package manager (npm, pnpm, yarn, bun, npx, uv,
+        poetry, pdm, pip, pipenv, python, make, just) or a recognised tool.
+        It resolves when the script, target, recipe, session or tool it names
+        exists in the repository or in its declared dependencies.
+    not_applicable_when: null
+    rationale: >-
+      An agent reads AGENTS.md or CLAUDE.md before anything else. Commands
+      in that file that do not exist send it down the wrong path, which is
+      worse than no file, so they drop the level to README.
+    sources:
+      - "AGENTS.md. https://agents.md"

package/methodology/v1.0/methodology.yaml

@@ -0,0 +1,242 @@
+# Codebase Health methodology, version 1.0
+#
+# This file holds the parts of the methodology that apply to every dimension:
+# aggregation, bands, execution rules, delta rules and regression flags.
+# Parameters and their rubrics live in dimensions/*.yaml. File scope lives in
+# scope.yaml. Framework presets for dimension 3 live in presets/*.yaml.
+#
+# Any change to a weight, anchor, band, threshold or rule in this folder
+# requires a new methodology version. Runs from different versions are never
+# compared.
+
+methodology: codebase-health
+version: "1.0"
+
+purpose: >-
+  Health = how safely and cheaply someone with no memory of this codebase,
+  whether a contractor or an agent, can make a correct change.
+
+languages:
+  - typescript
+  - javascript
+  - python
+
+scale:
+  min: 0
+  max: 100
+
+dimensions:
+  - id: 1
+    key: safety_net
+    file: dimensions/1-safety-net.yaml
+  - id: 2
+    key: type_static_rigor
+    file: dimensions/2-type-static-rigor.yaml
+  - id: 3
+    key: architecture_boundaries
+    file: dimensions/3-architecture-boundaries.yaml
+  - id: 4
+    key: complexity_maintainability
+    file: dimensions/4-complexity-maintainability.yaml
+  - id: 5
+    key: dependency_security_hygiene
+    file: dimensions/5-dependency-security-hygiene.yaml
+  - id: 6
+    key: operability_feedback_loop
+    file: dimensions/6-operability-feedback-loop.yaml
+
+scoring:
+  # How one parameter's raw value becomes a 0-100 score.
+  piecewise_linear: >-
+    Anchors are sorted by raw value. Between two anchors the score is
+    interpolated linearly. Below the lowest anchor the score equals the
+    lowest anchor's score; above the highest anchor it equals the highest
+    anchor's score. The same rule covers higher-is-better and
+    lower-is-better parameters; only the order of the scores differs.
+  levels: >-
+    The parameter's raw value is one of a fixed set of named levels, and each
+    level has a fixed score.
+  mean_of_components: >-
+    The parameter is the unweighted mean of its components, each scored by
+    its own rule.
+
+aggregation:
+  parameter_to_dimension:
+    method: weighted_mean
+    weights: per parameter, declared in each dimension file, summing to 100
+  not_applicable:
+    method: redistribute_within_dimension
+    rule: >-
+      A parameter's weight is spread over the other parameters in the same
+      dimension, in proportion to their weights. A parameter may only be not
+      applicable when its precondition is a design choice the methodology does
+      not score. Each dimension file lists the allowed conditions. Missing
+      tests and failed execution always score 0, never not applicable.
+  dimension_to_health:
+    method: capped_mean
+    weights: equal
+    formula: health = min(mean(dimension scores), min(dimension scores) + cap_margin)
+    cap_margin: 30
+  precision:
+    stored: full
+    displayed:
+      health: integer, rounded half up
+      health_delta: one decimal
+      dimension_score: integer, rounded half up
+      dimension_delta: integer, rounded half up
+    band_is_taken_from: displayed health
+
+bands:
+  - key: vibe_coded
+    name: Vibe-coded
+    min: 0
+    max: 39
+    meaning: >-
+      Changes break things without anyone noticing. Nobody, human or agent,
+      can work here safely.
+  - key: fragile
+    name: Fragile
+    min: 40
+    max: 59
+    meaning: It works, but every change is a gamble.
+  - key: stable
+    name: Stable
+    min: 60
+    max: 79
+    meaning: Changes are safe with care and review.
+  - key: agent_ready
+    name: Agent-ready
+    min: 80
+    max: 100
+    meaning: >-
+      An agent with no memory of the codebase can make a correct change and
+      verify it alone.
+
+layers:
+  static:
+    description: >-
+      Reads tracked files only: source, configuration, manifests and
+      lockfiles. Parses ASTs and builds import graphs. Never runs repository
+      code. Always runs.
+  execution:
+    description: >-
+      Installs dependencies, then runs the typechecker, the pinned lint
+      ruleset, the build and the test suite with coverage. Attempted on every
+      run.
+
+execution:
+  runner:
+    image: health:1.0
+    cpus: 4
+    memory_gb: 8
+  network: >-
+    Allowed during dependency install and while fetching the advisory and
+    registry snapshots. Off for build, typecheck, lint and tests.
+  environment: >-
+    Variables documented in the repository's env example file (see 6.5) are
+    loaded with their example values. No other secrets or variables are
+    provided. External services (databases, queues, browsers) are not
+    provided.
+  timeouts_seconds:
+    install: 900
+    build: 900
+    typecheck: 600
+    lint: 600
+    tests: 600
+  outcomes:
+    repository_failure: >-
+      An install, build, typecheck or test command fails or times out because
+      of the repository. Every parameter that requires that step scores 0.
+      A timeout counts as a failure. An install that fails in one install
+      root zeroes only the units beneath that root (same language group,
+      package or logic file under the root); the checks of the other roots
+      still run and their units are measured. If the install fails in every
+      root, the parameters that need it score 0 for the whole repository.
+    tool_error: >-
+      The tool itself fails (a crash in the orchestrator, a missing tool in
+      the image, coverage data missing after a test run that produced
+      results). The run is marked invalid and produces no score.
+  requirements:
+    install: dependencies installed from the lockfile, or from the manifest when no lockfile exists
+    build: install succeeded and the build step (see 6.1) exited 0
+    typecheck_run: install succeeded and the typechecker ran to completion and reported diagnostics
+    lint_run: install succeeded and the pinned lint ruleset ran to completion
+    test_run: install succeeded, a supported test runner was found, and it produced a results report
+
+minimum_repository: >-
+  At least one logic file (see scope.yaml). Repositories below this are not
+  scored.
+
+pooling:
+  # How parameters combine across languages and workspace packages in one
+  # repository. The repository always gets one headline score.
+  ratio: >-
+    Numerators and denominators are summed across languages and packages,
+    then the pooled ratio is scored once. Used for counts per 1,000 lines,
+    percentages and pass rates. A unit under an install root whose install
+    failed takes no part in the sums; the pooled score is multiplied by the
+    share of the logic lines that is not failed.
+  unit_weighted: >-
+    The parameter is scored separately for each language or package, then
+    the scores are combined by logic-line weight. Used for configuration and
+    yes/no parameters. Example: 2.2 scores 100 for a TypeScript frontend with
+    8,000 logic lines and 0 for a Python backend with 2,000; the pooled score
+    is 80.
+  report: Every dimension is also reported per package and per language.
+
+delta:
+  description: >-
+    health diff compares two runs only when all conditions match. Otherwise
+    it refuses and names the conditions that differ.
+  conditions:
+    - key: layers
+      rule: Both runs attempted the same layers.
+    - key: tool_versions
+      rule: Both runs used the same tool versions (the same image digest).
+    - key: methodology_version
+      rule: Both runs used the same methodology version.
+    - key: as_of_date
+      rule: >-
+        Both runs were scored at the same as-of date. For a contract, this is
+        the baseline's as-of date. The report also shows today's score for
+        the newer run.
+    - key: ignore_set
+      rule: >-
+        Both runs used the same .healthignore and .gitleaksignore contents
+        (compared by hash).
+  rescoring: >-
+    run.json stores raw values and the resolved dependency list, so health
+    diff can rescore parameters 5.1 and 5.2 of both runs against one advisory
+    and registry snapshot.
+
+regression:
+  description: Used by sprint-loop. Flags a regression; never blocks.
+  flag_when:
+    - Any dimension score drops by 3.0 or more (unrounded).
+    - The band drops.
+  pr_label: health-regression
+  telegram_format: "Health {health} {band} ({health_delta}) · {dimension_deltas} · ⚠ {regressions or 'none'}"
+  telegram_example: "Health 62 Stable (+1.4) · Safety net +6 · Complexity −1 · ⚠ none"
+  baseline: >-
+    The base branch commit, cached by tree hash, methodology version and
+    as-of date. Both runs use the as-of date of the day sprint-loop runs.
+
+report_only:
+  # Signals that appear in the report and never change the score.
+  - key: hotspots
+    description: >-
+      Files ranked by churn (commits touching the file in the last 12 months)
+      multiplied by cognitive complexity. This is the "fix these first" list.
+  - key: secrets_in_history
+    description: Secrets found in git history. The fix is rotating the key.
+  - key: dev_dependency_vulnerabilities
+    description: Known vulnerabilities in packages reachable only from development dependencies.
+  - key: top_scares
+    description: >-
+      The first three of a fixed list of plain-English consequences that the
+      scan's findings trigger, for example a Supabase service-role key in the
+      tree. Copy lives in code.
+  - key: excluded_lines
+    description: Percentage of lines excluded by .healthignore.
+  - key: per_package_breakdown
+    description: Every dimension per workspace package and per language.

package/methodology/v1.0/presets/django.yaml

@@ -0,0 +1,43 @@
+preset:
+  key: django
+  name: Django
+  languages: [python]
+  detect: The project declares django as a dependency.
+
+conventions: >-
+  Layers are matched by module name inside each Django app, either as a
+  module (views.py) or a package (views/__init__.py and its submodules).
+
+modules:
+  roots: Django apps (directories that contain apps.py).
+  public_entry: [__init__.py, models, services, selectors]
+
+layers:
+  models: [models]
+  http: [views, urls, forms, serializers, admin]
+  views: [views]
+  urls: [urls]
+  services: [services, selectors]
+
+rules:
+  - name: models-do-not-import-http
+    description: Models do not depend on views, urls, forms, serializers or admin.
+    from: { in: [models] }
+    to: { in: [http] }
+    severity: error
+    type_only_imports: included
+  - name: services-do-not-import-views
+    description: Services and selectors do not depend on views or urls.
+    from: { in: [services] }
+    to: { in: [views, urls] }
+    severity: error
+    type_only_imports: included
+  - name: only-urls-import-views
+    description: Views are imported only by urls modules.
+    from: { not_in: [urls] }
+    to: { in: [views] }
+    severity: error
+    type_only_imports: included
+
+sources:
+  - "HackSoft Django Styleguide. https://github.com/HackSoftware/Django-Styleguide"

package/methodology/v1.0/presets/express.yaml

@@ -0,0 +1,47 @@
+preset:
+  key: express
+  name: Express
+  languages: [typescript, javascript]
+  detect: The package declares express as a dependency and not next.
+
+conventions: >-
+  Globs are relative to the package root and match with or without a src/
+  prefix. When a file matches several layer globs, the innermost matching
+  directory decides its layer.
+
+layers:
+  http: ["routes/**", "controllers/**", "middleware/**", "middlewares/**"]
+  services: ["services/**"]
+  data: ["models/**", "repositories/**", "db/**", "dal/**"]
+  shared: ["utils/**", "lib/**", "helpers/**"]
+
+modules:
+  roots: ["features/*", "modules/*", "packages/*"]
+  public_entry: "index.{ts,js,mts,mjs,cjs}"
+
+rules:
+  - name: services-do-not-import-http
+    description: Services do not depend on the HTTP layer or on express.
+    from: { in: [services] }
+    to:
+      in: [http]
+      packages: [express]
+    severity: error
+    type_only_imports: included
+  - name: data-does-not-import-up
+    description: The data layer does not depend on services, the HTTP layer or express.
+    from: { in: [data] }
+    to:
+      in: [services, http]
+      packages: [express]
+    severity: error
+    type_only_imports: included
+  - name: shared-does-not-import-up
+    description: Shared helpers do not depend on the HTTP layer or services.
+    from: { in: [shared] }
+    to: { in: [http, services] }
+    severity: error
+    type_only_imports: included
+
+sources:
+  - "Cockburn, A. Hexagonal Architecture (Ports and Adapters), 2005. https://alistair.cockburn.us/hexagonal-architecture/"

package/methodology/v1.0/presets/fastapi.yaml

@@ -0,0 +1,52 @@
+preset:
+  key: fastapi
+  name: FastAPI
+  languages: [python]
+  detect: The project declares fastapi as a dependency and not django.
+
+conventions: >-
+  Layers are matched by module or package name anywhere under a first-party
+  package. When a module matches several layers, the innermost match
+  decides its layer.
+
+modules:
+  roots: >-
+    Subpackages that contain router.py, and the direct subpackages of any
+    features or modules package.
+  public_entry: [__init__.py]
+
+layers:
+  http: [routers, router, routes, api, endpoints]
+  services: [services, service]
+  data: [models, repositories, repository, db, crud]
+  schemas: [schemas, schema]
+  app_entry: [main, app]
+
+rules:
+  - name: services-do-not-import-http
+    description: Services do not depend on routers, fastapi or starlette.
+    from: { in: [services] }
+    to:
+      in: [http]
+      packages: [fastapi, starlette]
+    severity: error
+    type_only_imports: included
+  - name: data-does-not-import-up
+    description: >-
+      The data layer does not depend on the HTTP layer, services or fastapi.
+      Importing schemas is allowed.
+    from: { in: [data] }
+    to:
+      in: [http, services]
+      packages: [fastapi, starlette]
+    severity: error
+    type_only_imports: included
+  - name: routers-are-leaves
+    description: Only main.py and app.py import routers.
+    from: { not_in: [http, app_entry] }
+    to: { in: [http] }
+    severity: error
+    type_only_imports: included
+
+sources:
+  - "FastAPI: Bigger Applications - Multiple Files. https://fastapi.tiangolo.com/tutorial/bigger-applications/"