UnvibeCode — Private Production Source & Operations

This private repository is the single source of truth for UnvibeCode.

A fresh clone of this repository must always be sufficient to:

1. modify UnvibeCode,
2. run tests,
3. build the Python package,
4. validate the customer workflow,
5. publish a new PyPI release.

Do not depend on old OneDrive folders, ZIP backups, extracted wheels, site-packages, or historical dist directories.

---

1. Current Architecture

CUSTOMER MACHINE
│
├── Python package: unvibecode
├── Repository parsing
├── Code graph construction
├── Context generation
├── Business workflow analysis
├── Risk-analysis orchestration
├── Report generation
│
└──────── HTTPS ────────► HOSTED GATEWAY
                           │
                           ├── Provider credentials
                           ├── Model access
                           ├── Request controls
                           ├── Usage controls
                           └── Spend protection

The customer's repository is processed primarily on the customer's machine. Model requests required by the analysis workflow are routed through the hosted UnvibeCode gateway.

---

2. Hosted Production Gateway

Production API:

https://shipready-api.alphashots.ai/v1/responses

Health endpoint:

https://shipready-api.alphashots.ai/health

Production flow:

Internet
   ↓
Nginx / HTTPS
   ↓
Uvicorn
   ↓
UnvibeCode API Gateway
   ↓
Model Provider

Production gateway directory:

/home/yash/shipready_api_gateway_v1

Nginx site configuration:

/etc/nginx/sites-available/shipready-api

Runtime environment and provider credentials:

/etc/shipready/shipready-api.env

The gateway is responsible for provider credentials, model access, request validation, payload protection, concurrency controls, usage metering, spend protection, and emergency service controls.

Secrets

Never commit:

.env
.env.*
API keys
provider credentials
private keys
GitHub tokens
PyPI tokens
server secrets

No production credential should be required inside the Python package.

Minimum server health checks:

sudo nginx -t
sudo systemctl reload nginx
curl -i http://127.0.0.1:8100/internal/health
curl -i https://shipready-api.alphashots.ai/health

---

3. Repository Structure

unvibecode-product-private/
│
├── README.md
├── pyproject.toml
├── .gitignore
├── .gitattributes
│
├── src/
│   ├── unvibecode/
│   │   ├── __init__.py
│   │   └── __main__.py
│   │
│   └── shipreadyv2/
│       ├── __init__.py
│       ├── __main__.py
│       ├── cli.py
│       ├── customer_runner.py
│       ├── SOURCE_MANIFEST.json
│       └── engine_sources/
│           ├── 00a_shipreadyv2_fast_lane_v11_api_context_bundle.py
│           ├── 01_shipreadyv2_merged_graph_pipeline_5chunks.py
│           ├── 02_shipreadyv2_prepare_pass1_inputs.py
│           ├── 03_shipreadyv2_pass1_full_runner.py
│           ├── 04_shipreadyv2_business_path_compiler.py
│           ├── 05_shipreadyv2_critical_business_insight_selector_v4.py
│           ├── 06_shipreadyv2_step4_v2_with_v4_inputs.py
│           ├── agent_knowledge_graph.db
│           ├── archetype_taxonomy.yaml
│           ├── archetype_taxonomy_pass1_compact.yaml
│           ├── build_pass1_compact_taxonomy.py
│           ├── generate_combinedjson.py
│           ├── normalized_business_path.schema.json
│           ├── shipready_business_insight_implementation_plan_v2.md
│           └── universal_insight_rules.yaml
│
└── tests/

---

4. Source Ownership

src/unvibecode

Public package compatibility layer for:

python -m unvibecode

src/shipreadyv2/cli.py

Handles CLI behavior, command arguments, gateway configuration, and starting repository reviews.

src/shipreadyv2/customer_runner.py

Handles repository-size routing, pipeline orchestration, progress reporting, execution of analysis stages, customer result generation, and browser/report behavior.

src/shipreadyv2/engine_sources

This directory contains the core UnvibeCode analysis engine. Treat everything inside this directory as proprietary production source.

Main pipeline:

00a → Connected Code Map / repository context

01 → 02 → 03 → 04 → 05 → 06
                    ↓
          Business Workflow & Risk Review

Supporting taxonomies, schemas, rules, and knowledge files used by the engine also live here.

---

5. Files That Are NOT Source

Never treat these as authoritative:

.venv/
build/
dist/
*.egg-info/
__pycache__/
.pytest_cache/
shipready_results/

Also never edit:

site-packages/

Generated wheels and .tar.gz files are outputs, not source.

---

6. GitHub Is the Source of Truth

Private repository:

https://github.com/FinanceFlash/unvibecode-product-private

Operating model:

Private GitHub
      ↓
git clone
      ↓
Temporary local working copy
      ↓
modify source
      ↓
tests + build + validation
      ↓
git commit + push
      ↓
Private GitHub
      ↓
tagged release
      ↓
PyPI

GitHub is permanent. Local working copies are disposable.

A developer must be able to delete the local repository completely, clone GitHub again, and reproduce the production package. If that is not possible, something required for production is missing from GitHub.

---

7. Start Work on Any Computer

Clone:

git clone https://github.com/FinanceFlash/unvibecode-product-private.git "D:\unvibecode"

Enter the repository:

Set-Location "D:\unvibecode"

Create a clean environment:

py -3.13 -m venv ".venv"

Install development tools:

& ".\.venv\Scripts\python.exe" -m pip install --upgrade pip build pytest twine

Build:

& ".\.venv\Scripts\python.exe" -m build .

Install the generated wheel:

$wheel=(Get-ChildItem ".\dist\*.whl" | Sort-Object LastWriteTime -Descending | Select-Object -First 1); & ".\.venv\Scripts\python.exe" -m pip install --force-reinstall $wheel.FullName

Run tests:

& ".\.venv\Scripts\python.exe" -m pytest -q

Validated 0.3.3 baseline:

11 tests passing

---

8. Change a .py File

Always edit the canonical source in this repository.

Never modify copies inside site-packages, build, dist, old project folders, or old ZIP files.

Example:

src\shipreadyv2\engine_sources\05_shipreadyv2_critical_business_insight_selector_v4.py

Syntax-check the changed Python file:

& ".\.venv\Scripts\python.exe" -m py_compile ".\src\shipreadyv2\engine_sources\05_shipreadyv2_critical_business_insight_selector_v4.py"

Run all tests:

& ".\.venv\Scripts\python.exe" -m pytest -q

Do not continue with a release if tests fail.

---

9. SOURCE_MANIFEST.json

Authoritative engine hashes are stored in:

src\shipreadyv2\SOURCE_MANIFEST.json

When a listed engine file changes:

1. calculate its new LF-normalized SHA-256,
2. update only that file's stored hash,
3. add a short description to engine_changes_from_baseline,
4. leave unrelated hashes unchanged.

Example:

$relative="engine_sources/01_shipreadyv2_merged_graph_pipeline_5chunks.py"; & ".\.venv\Scripts\python.exe" -c "from pathlib import Path; import hashlib; p=Path('src/shipreadyv2')/'$relative'; print(hashlib.sha256(p.read_bytes().replace(bytes([13,10]),bytes([10]))).hexdigest())"

Do not add ordinary tests, README files, or packaging files to the engine manifest.

---

10. Versioning

A PyPI release cannot replace an already published version.

For a normal compatible change:

0.3.3 → 0.3.4

Update the version in:

pyproject.toml
src\shipreadyv2\__init__.py
src\shipreadyv2\SOURCE_MANIFEST.json
tests\test_package.py

Use a patch version for fixes/tuning, a minor version for significant new functionality, and a major version for breaking changes.

---

11. Review the Exact Change

git status --short

git --no-pager diff

Confirm that no wheel, virtual environment, generated result, secret, API key, token, or .env file is included.

---

12. Build a Production Candidate

Remove old build outputs:

Remove-Item -Recurse -Force ".\dist" -ErrorAction SilentlyContinue

Remove-Item -Recurse -Force ".\build" -ErrorAction SilentlyContinue

Get-ChildItem -Recurse -Directory -Filter "*.egg-info" | Remove-Item -Recurse -Force

Run tests:

& ".\.venv\Scripts\python.exe" -m pytest -q

Build:

& ".\.venv\Scripts\python.exe" -m build .

Validate distributions:

& ".\.venv\Scripts\python.exe" -m twine check ".\dist\*"

Expected:

dist/
├── unvibecode-<VERSION>-py3-none-any.whl
└── unvibecode-<VERSION>.tar.gz

---

13. Validate the Actual Wheel

Do not validate only from the editable source tree.

Create a clean external environment:

py -3.13 -m venv "D:\unvibecode_release_validation"

Install/upgrade pip:

& "D:\unvibecode_release_validation\Scripts\python.exe" -m pip install --upgrade pip

Install the newly built wheel:

$wheel=(Get-ChildItem ".\dist\*.whl" | Sort-Object LastWriteTime -Descending | Select-Object -First 1); & "D:\unvibecode_release_validation\Scripts\python.exe" -m pip install --force-reinstall $wheel.FullName

Verify version:

& "D:\unvibecode_release_validation\Scripts\python.exe" -m unvibecode --version

Verify help:

& "D:\unvibecode_release_validation\Scripts\python.exe" -m unvibecode --help

Run a real repository review:

& "D:\unvibecode_release_validation\Scripts\python.exe" -m unvibecode review --repository "D:\upstox"

A successful normal repository review should create:

01_connected_code_map_for_llm.html
complete_repository_context_for_llm.zip
02_business_workflow_map.html
03_business_risk_findings.html

Only continue when the actual wheel passes the real customer workflow.

---

14. Save the Change Permanently

git status --short

git --no-pager diff

git add .

git commit -m "Describe the production change"

git push origin main

Once pushed, GitHub—not the local computer—is the permanent record.

---

15. Tag a Validated Release

git tag -a "v<VERSION>" -m "Validated UnvibeCode <VERSION>"

git push origin "v<VERSION>"

Example:

v0.3.4

Tags make it possible to reconstruct exactly which source produced each PyPI release.

---

16. Publish to PyPI

Only publish after:

syntax check
      ↓
tests
      ↓
build
      ↓
twine check
      ↓
fresh-environment installation
      ↓
real customer workflow

Upload only the new release artifacts:

& ".\.venv\Scripts\python.exe" -m twine upload ".\dist\unvibecode-<VERSION>-py3-none-any.whl" ".\dist\unvibecode-<VERSION>.tar.gz"

Never upload an old dist directory wholesale.

After publishing, create another clean environment:

py -3.13 -m venv "D:\unvibecode_public_validation"

Install the exact PyPI version:

& "D:\unvibecode_public_validation\Scripts\python.exe" -m pip install --no-cache-dir "unvibecode==<VERSION>"

Verify:

& "D:\unvibecode_public_validation\Scripts\python.exe" -m unvibecode --version

Run the real customer workflow again:

& "D:\unvibecode_public_validation\Scripts\python.exe" -m unvibecode review --repository "D:\upstox"

A release is complete only after the PyPI-installed package works.

---

17. Customer Usage

Install:

pip install unvibecode

Review a repository:

python -m unvibecode review --repository "D:\your_repository"

Results are written automatically under:

shipready_results/

A normal repository produces:

Connected Code Map
Complete Repository Context
Business Workflow Map
Business Risk Findings

---

18. Sustainable Operating Rule

For any future .py change:

1. Clone/pull private GitHub
2. Edit canonical source
3. Syntax-check changed Python
4. Update SOURCE_MANIFEST if required
5. Update/add tests
6. Run all tests
7. Increment version if releasing
8. Build wheel + tar.gz
9. Run twine check
10. Install wheel in clean environment
11. Run real repository review
12. Review git diff
13. Commit
14. Push to private GitHub
15. Tag validated release
16. Publish to PyPI
17. Install from PyPI and test again

The private GitHub repository must always contain everything required to rebuild UnvibeCode from source, except production credentials and other server-only secrets.

---

19. Never Do These

Do not:

• modify installed site-packages,
• modify files inside dist,
• use old ZIPs as source,
• use old OneDrive project copies as source,
• keep production-only changes on one laptop,
• commit .env files,
• commit provider credentials,
• commit PyPI tokens,
• commit GitHub authentication tokens,
• release without testing the built wheel,
• overwrite an existing PyPI version,
• make engine changes without updating the manifest when required.

---

Production Principle

GitHub = source
PyPI = distribution
Customer machine = local execution
Hosted gateway = model access and service controls
Server secrets = server only

The private GitHub repository is the authoritative production source for UnvibeCode.