sustainable-vibe-coding 10.0.0__tar.gz

sustainable_vibe_coding-10.0.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.1
+Name: sustainable-vibe-coding
+Version: 10.0.0
+Summary: Packaged SVC corpus and local development-collaboration CLI.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Sustainable Vibe Coding
+
+Sustainable Vibe Coding (SVC) is a source-first framework delivered as a versioned local corpus and a small development-collaboration CLI. It helps AI-assisted teams retain costly-to-rediscover truth without copying upstream framework documents into every repository.
+
+## Develop SVC
+
+Requirements: Python 3.11+ and PDM.
+
+```bash
+pdm install
+pdm run test
+pdm run build-monolith
+pdm run svc --help
+pdm build
+```
+
+Edit canonical framework content under `src/`, never `build/monolith.md`. `src/` contains only SVC corpus content and release metadata; Python runtime code is in `svc_cli/`, and repository-only builders/release tools are in `tools/`.
+
+## Use a Released Corpus
+
+Install the CLI, then query the guidance you need. The wheel contains the read-only corpus and a deterministic catalog, so ordinary lookup writes nothing and contacts no service.
+
+```bash
+python -m pip install sustainable-vibe-coding==10.0.0
+
+svc lookup --name 'sections/working-protocol\.md'
+svc lookup --name 'assets/templates/AGENTS\..*\.template\.md' --all
+svc lookup --keyword "task packet mutation gate"
+```
+
+`--name` is a full-path regular expression over source-relative SVC document paths—not a document ID. Keyword results are short, deterministic candidates; use a returned path with `--name` to read canonical content. Semantic search is intentionally deferred until a local artifact and quality contract are measured.
+
+## Initialize a Consumer Project
+
+Initialization is dry-run by default. It creates no copied SVC documents and never silently overwrites consumer content.
+
+```bash
+svc init /path/to/project --agent codex --json
+svc init /path/to/project --apply <plan-digest>
+svc status /path/to/project
+```
+
+The exact-plan apply may create:
+
+```text
+svc.json
+.agents/skills/svc/SKILL.md
+AGENTS.md                  (a bounded generated SVC navigation block)
+docs/index.md              (created when absent, with a bounded generated navigation block)
+```
+
+`svc.json` records only the project's adopted SVC baseline (plus its file schema):
+
+```json
+{
+  "schema_version": 1,
+  "svc_version": "10.0.0"
+}
+```
+
+Everything unmarked in `AGENTS.md` and `docs/index.md` remains Consumer-owned. The Codex skill is a substantial operational guide to `svc` commands, not a duplicate of the framework corpus. Modified generated blocks or skills block refresh for human review.
+
+## Upgrade Deliberately
+
+The executable and project adoption are deliberately separate:
+
+```bash
+svc self-update --json
+svc self-update --apply <plan-digest>
+
+svc status /path/to/project
+svc lookup --keyword "migration"
+svc adopt 10.0.0 /path/to/project --apply <plan-digest>
+```
+
+`self-update` changes only a supported non-editable pip installation in the current interpreter. It never changes `svc.json`. After reviewing any packaged migration guidance and applying Consumer-owned changes under the project's mutation gate, `svc adopt` records the new baseline in `svc.json` through another exact plan.
+
+## Behavioral SemVer and Releases
+
+SVC uses Behavioral SemVer:
+
+- **MAJOR** changes required obligations, defaults, permission/authority boundaries, task-packet semantics, consumer layout, or a stable CLI/catalog contract.
+- **MINOR** adds an optional backward-compatible capability.
+- **PATCH** fixes or clarifies the existing protocol without changing those behaviors.
+
+Towncrier fragments and the release planner make the impact reviewable. GitHub Releases are the canonical release record; the Python package is the installation projection. See [CONTRIBUTING.md](CONTRIBUTING.md) for commit, fragment, and release workflow rules.
+
+## Repository Layout
+
+```text
+src/                         canonical SVC corpus and release metadata
+svc_cli/                     installable Python runtime
+tools/                       catalog, monolith, and release tooling
+pdm_build.py                 wheel corpus projection hook
+tests/                       contract and fixture tests
+tasks/                       volatile work packets
+```

sustainable_vibe_coding-10.0.0/README.md

@@ -0,0 +1,97 @@
+# Sustainable Vibe Coding
+
+Sustainable Vibe Coding (SVC) is a source-first framework delivered as a versioned local corpus and a small development-collaboration CLI. It helps AI-assisted teams retain costly-to-rediscover truth without copying upstream framework documents into every repository.
+
+## Develop SVC
+
+Requirements: Python 3.11+ and PDM.
+
+```bash
+pdm install
+pdm run test
+pdm run build-monolith
+pdm run svc --help
+pdm build
+```
+
+Edit canonical framework content under `src/`, never `build/monolith.md`. `src/` contains only SVC corpus content and release metadata; Python runtime code is in `svc_cli/`, and repository-only builders/release tools are in `tools/`.
+
+## Use a Released Corpus
+
+Install the CLI, then query the guidance you need. The wheel contains the read-only corpus and a deterministic catalog, so ordinary lookup writes nothing and contacts no service.
+
+```bash
+python -m pip install sustainable-vibe-coding==10.0.0
+
+svc lookup --name 'sections/working-protocol\.md'
+svc lookup --name 'assets/templates/AGENTS\..*\.template\.md' --all
+svc lookup --keyword "task packet mutation gate"
+```
+
+`--name` is a full-path regular expression over source-relative SVC document paths—not a document ID. Keyword results are short, deterministic candidates; use a returned path with `--name` to read canonical content. Semantic search is intentionally deferred until a local artifact and quality contract are measured.
+
+## Initialize a Consumer Project
+
+Initialization is dry-run by default. It creates no copied SVC documents and never silently overwrites consumer content.
+
+```bash
+svc init /path/to/project --agent codex --json
+svc init /path/to/project --apply <plan-digest>
+svc status /path/to/project
+```
+
+The exact-plan apply may create:
+
+```text
+svc.json
+.agents/skills/svc/SKILL.md
+AGENTS.md                  (a bounded generated SVC navigation block)
+docs/index.md              (created when absent, with a bounded generated navigation block)
+```
+
+`svc.json` records only the project's adopted SVC baseline (plus its file schema):
+
+```json
+{
+  "schema_version": 1,
+  "svc_version": "10.0.0"
+}
+```
+
+Everything unmarked in `AGENTS.md` and `docs/index.md` remains Consumer-owned. The Codex skill is a substantial operational guide to `svc` commands, not a duplicate of the framework corpus. Modified generated blocks or skills block refresh for human review.
+
+## Upgrade Deliberately
+
+The executable and project adoption are deliberately separate:
+
+```bash
+svc self-update --json
+svc self-update --apply <plan-digest>
+
+svc status /path/to/project
+svc lookup --keyword "migration"
+svc adopt 10.0.0 /path/to/project --apply <plan-digest>
+```
+
+`self-update` changes only a supported non-editable pip installation in the current interpreter. It never changes `svc.json`. After reviewing any packaged migration guidance and applying Consumer-owned changes under the project's mutation gate, `svc adopt` records the new baseline in `svc.json` through another exact plan.
+
+## Behavioral SemVer and Releases
+
+SVC uses Behavioral SemVer:
+
+- **MAJOR** changes required obligations, defaults, permission/authority boundaries, task-packet semantics, consumer layout, or a stable CLI/catalog contract.
+- **MINOR** adds an optional backward-compatible capability.
+- **PATCH** fixes or clarifies the existing protocol without changing those behaviors.
+
+Towncrier fragments and the release planner make the impact reviewable. GitHub Releases are the canonical release record; the Python package is the installation projection. See [CONTRIBUTING.md](CONTRIBUTING.md) for commit, fragment, and release workflow rules.
+
+## Repository Layout
+
+```text
+src/                         canonical SVC corpus and release metadata
+svc_cli/                     installable Python runtime
+tools/                       catalog, monolith, and release tooling
+pdm_build.py                 wheel corpus projection hook
+tests/                       contract and fixture tests
+tasks/                       volatile work packets
+```

sustainable_vibe_coding-10.0.0/pdm_build.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from tools.build_catalog import build_projection
+
+
+def pdm_build_update_files(context: Any, files: dict[str, Path]) -> None:
+    """Project the canonical corpus once into the wheel's read-only runtime data."""
+    if context.target != "wheel":
+        return
+    root = Path(context.root)
+    files.update(build_projection(root, root / "build" / "catalog"))

sustainable_vibe_coding-10.0.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "sustainable-vibe-coding"
+version = "10.0.0"
+description = "Packaged SVC corpus and local development-collaboration CLI."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.scripts]
+svc = "svc_cli.cli:main"
+
+[dependency-groups]
+release = [
+    "towncrier>=25.8,<26",
+]
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[tool.pdm]
+distribution = true
+
+[tool.pdm.scripts]
+build-monolith = "python -m tools.build_monolith"
+svc = "python -m svc_cli.cli"
+test = "python -m unittest discover -s tests -p 'test_*.py'"
+release = "python -m tools.release"
+
+[tool.pdm.build]
+includes = [
+    "svc_cli",
+]
+source-includes = [
+    "src",
+    "tools",
+    "tests",
+    "pdm_build.py",
+]
+
+[tool.towncrier]
+directory = "changes"
+filename = "CHANGELOG.md"
+title_format = "## [{version}] - {project_date}"
+issue_format = "`{issue}`"
+start_string = "<!-- towncrier release notes start -->\n"
+underlines = [
+    "",
+    "",
+    "",
+]
+type = [
+    { directory = "major", name = "Behavioral breaking changes", showcontent = true },
+    { directory = "minor", name = "Backward-compatible capabilities", showcontent = true },
+    { directory = "patch", name = "Protocol fixes", showcontent = true },
+]

sustainable_vibe_coding-10.0.0/src/assets/templates/AGENTS.local.template.md

@@ -0,0 +1,25 @@
+# Local Instructions: <Subtree>
+
+## Scope
+
+- Applies to: `<path or pattern>`
+- Does not apply to: `<boundary if needed>`
+
+## Invariants and Authority
+
+- <non-negotiable local invariant>
+- Authority lives in: `<source>`
+- Allowed write path: `<entry point>`
+- Forbidden shortcut: `<shortcut and failure it causes>`
+
+## Hazard and Tripwire
+
+- Fragile seam: <description>
+- Recurrence signal: <observable symptom>
+- Required check: `<test, assertion, log, or command>`
+- Escalate when: <condition that invalidates local action>
+
+## Navigation
+
+- Stable anchors: `<symbols, ids, or selectors>`
+- Relevant tests: `<paths>`

sustainable_vibe_coding-10.0.0/src/assets/templates/AGENTS.root.template.md

@@ -0,0 +1,46 @@
+# <Project Name>
+
+<One sentence describing the product or repository.>
+
+Replace every angle-bracket placeholder. Delete any optional owner row that is not admitted; a completed root must contain no placeholder or `absent` marker.
+
+## Repository Map
+
+- `<path>`: <crucial responsibility>
+- `<path>`: <crucial responsibility>
+- `docs/`: durable project knowledge
+- `tasks/`: active task-local state
+
+## Knowledge Owners
+
+- Working protocol and mutation gate: `docs/00-meta/working-protocol.md`
+- Non-trivial implementation judgment: `docs/00-meta/implementation-taste.md`
+- Product what and why: `docs/10-prd/README.md`
+- Cross-unit technical contracts, when admitted: `<path>`
+- Unit design and local seam guidance, when admitted: `<paths>`
+- Technical decisions and ADRs, when admitted: `<path>`
+- Runtime, packaging, migration, observability, and recovery truth, when admitted: `<path>`
+- Nearer `AGENTS.md` files are additive for their subtree.
+- Task retention: <concrete deletion or time-to-live rule; no archive or deletion-time promotion review>
+
+## Development Workflow
+
+- Runtime and package manager: <versions/tools>
+- Install: `<command>`
+- Test: `<command>`
+- Lint/type/check: `<command>`
+- Build/package: `<command>`
+- Smoke/debug entry: `<command, inspector, or harness>`
+- Runtime data: `<state, database, logs, cache, and config paths>`
+- Environment overrides: `<locations>`
+
+Keep these entries executable and project-specific. Put durable behavior or architecture in its knowledge owner, not here.
+
+## Execution Rules
+
+- Read `docs/00-meta/working-protocol.md` for non-trivial work and follow its permission boundary.
+- Load `docs/00-meta/implementation-taste.md` only when its implementation trigger is present.
+- Read the nearest local `AGENTS.md` before editing a governed subtree.
+- Prefer code, configuration, schemas, tests, and automation for mechanically enforceable truth.
+- Follow the working protocol's documentation-quality contract.
+- <project-specific approval, commit, or release rule>

sustainable_vibe_coding-10.0.0/src/assets/templates/alignment-change-request.template.md

@@ -0,0 +1,40 @@
+# Alignment Substrate Request Template
+
+## Request Metadata
+
+- request id:
+- target surface:
+- requester:
+
+## Coordination Primitives
+
+### Reference
+
+- object:
+- address:
+
+### Mutation Contract
+
+- operation:
+- invariants / boundaries:
+
+### Grounding and Synchronization
+
+- applicable state / context:
+- evidence:
+- protocol / handshake checkpoint:
+
+## Desired State Diff
+
+- from:
+- to:
+
+## Blast Radius Forecast
+
+- touched anchors / files:
+- downstream surfaces at risk:
+- explicitly out of scope:
+
+## Acceptance Check
+
+- verification contract:

sustainable_vibe_coding-10.0.0/src/assets/templates/deployment-runbook.template.md

@@ -0,0 +1,37 @@
+# Deployment Runbook Template
+
+## Incident Metadata
+
+- incident id:
+- service:
+- start time:
+- severity:
+
+## Symptoms and Blast Radius
+
+- user-visible impact:
+- affected endpoints or jobs:
+
+## Telemetry Snapshot
+
+- key logs:
+- metrics:
+- traces:
+
+## Mitigation Plan
+
+1. immediate containment:
+2. temporary workaround:
+3. risk note:
+
+## Rollback Plan
+
+1. rollback trigger:
+2. rollback steps:
+3. post-rollback verification:
+
+## Forward Fix Entry Criteria
+
+- evidence quality threshold:
+- approval owner:
+- approved forward-fix entry:

sustainable_vibe_coding-10.0.0/src/assets/templates/edit-shared-docs.template.md

@@ -0,0 +1,42 @@
+# Shared Docs Edit Protocol Template
+
+Use this protocol in a Spoke repo when local work discovers that shared Hub truth must change.
+
+## Capture Local Pressure
+
+- spoke task:
+- local code path or seam:
+- missing shared rule or ambiguity:
+- local consequence if left unresolved:
+- verification pressure after return:
+
+## Preconditions
+
+- `docs/_shared/` points at the intended upstream and is not detached
+- the active task packet explains why shared truth must change
+- human approval is required before commit or push
+
+## Phase 1: Status Check
+
+- upstream branch or source:
+- freshness check result:
+- stale-pointer risk:
+
+## Phase 2: Solidify Global
+
+- shared files to edit:
+- canonical owner:
+- summary for human approval:
+- approval received from:
+- Hub commit:
+
+## Phase 3: Bump Local
+
+- Spoke repo:
+- pointer or reference update:
+- isolated bump commit:
+
+## Phase 4: Resume Local
+
+- local work resumed:
+- verification after bump:

sustainable_vibe_coding-10.0.0/src/assets/templates/product-tdd.template.md

@@ -0,0 +1,24 @@
+# Product TDD: <Contract Surface>
+
+## Admission
+
+- Dependent units: <units that must interoperate>
+- Failure if lost: <compatibility, authority, or topology risk>
+- Why code, schemas, and tests are insufficient: <reason>
+
+## Authority and Topology
+
+- Authority owner: <unit/system>
+- Participating units: <boundaries>
+- State or reference flow: <concise description>
+
+## Cross-Unit Contract
+
+- Inputs and outputs: <schema or semantic contract>
+- Compatibility invariants: <rules>
+- Failure semantics: <observable behavior>
+
+## Verification
+
+- Contract tests or schema checks: <paths/commands>
+- Product claim realization pointers: <links when useful>

sustainable_vibe_coding-10.0.0/src/assets/templates/product-truth.template.md

@@ -0,0 +1,29 @@
+# Product Truth
+
+## Purpose and Pressure
+
+- Product purpose: <problem and beneficiary>
+- Current drivers: <market, user, business, hard-constraint, or operational pressure>
+
+## Claims and Evaluation
+
+| Product Claim | Rationale | Observable Success | Expected Evidence |
+| --- | --- | --- | --- |
+| | | | |
+
+## Capabilities and Workflows
+
+- Capability: <what the product can do>
+- Workflow: <externally observable path>
+
+## Rules and Scope
+
+- Invariant: <product rule that must remain true>
+- In scope: <boundary>
+- Out of scope: <boundary>
+
+## Business Language
+
+- **<term>**: <stable product meaning>
+
+Keep this as `docs/10-prd/README.md` until distinct consumers or change cadence justify a split. Do not add implementation topology or internal contracts.

sustainable_vibe_coding-10.0.0/src/assets/templates/task-diagnostics-matrix.template.md

@@ -0,0 +1,18 @@
+# Diagnostic Task: <Symptom>
+
+- **Objective**: identify the supported root cause of <symptom>
+- **Guardrails**: gather evidence before mutation; preserve existing claims until disproven
+- **Verification**: reproduce or falsify the cause with observable evidence
+- **Current Truth**: <known symptoms, evidence, and uncertainty>
+- **Next Step**: <next diagnostic action or blocking decision>
+
+## Failure Matrix
+
+| Suspected Cause | Supporting Evidence | Missing Evidence | Validation Step | Likely Owner |
+| --- | --- | --- | --- | --- |
+| | | | | |
+
+## Durable Follow-up
+
+- Root-cause owner, if confirmed: <source, config, test, product, technical, deployment, or local seam>
+- Recurrence guard, if justified: <mechanical check or local tripwire>

sustainable_vibe_coding-10.0.0/src/assets/templates/task-packet.template.md

@@ -0,0 +1,15 @@
+# <Task>
+
+- **Objective**: <concrete outcome>
+- **Guardrails**: <boundaries and invariants that must remain true>
+- **Verification**: <objective proof of completion>
+- **Current Truth**: <evidence-backed understanding, decisions, and material uncertainty>
+- **Next Step**: <next action or blocking decision>
+
+## Supporting Material (Optional)
+
+- Evidence: <links to task-local evidence>
+- Decisions: <only decisions needed to understand current state>
+- Work: <links to bounded artifacts>
+
+Keep this file as the compact control surface. Split supporting material only when it becomes hard to scan here.