Skip to content

Commit 3885b47

Browse files
minkoi007csminkoi007cs
committed
feat(governance): initialize repository governance, tech specs, and process enforcement
1 parent fa72d48 commit 3885b47

12 files changed

Lines changed: 1794 additions & 1 deletion

File tree

‎.env.example‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# ==============================================================================
2+
# PyPath Environment Configuration Template
3+
# Copy this file to .env and fill in your local or deployment secrets.
4+
# NEVER commit the real .env file into source control.
5+
# ==============================================================================
6+
7+
# Application Environment
8+
# Options: development | staging | production | test
9+
ENVIRONMENT=development
10+
LOG_LEVEL=info
11+
12+
# ------------------------------------------------------------------------------
13+
# Backend API Configuration (FastAPI)
14+
# ------------------------------------------------------------------------------
15+
API_HOST=0.0.0.0
16+
API_PORT=8000
17+
CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
18+
19+
# PostgreSQL Database (AsyncPG driver required)
20+
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/pypath_dev
21+
22+
# Supabase Auth & JWT Verification
23+
SUPABASE_URL=https://your-project-id.supabase.co
24+
SUPABASE_ANON_KEY=your-supabase-anon-key-placeholder
25+
SUPABASE_JWT_SECRET=your-supabase-jwt-secret-placeholder
26+
27+
# ------------------------------------------------------------------------------
28+
# Frontend Application Configuration (Next.js)
29+
# ------------------------------------------------------------------------------
30+
NEXT_PUBLIC_API_URL=http://localhost:8000
31+
NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
32+
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key-placeholder
33+
34+
# In-Browser Execution Safeguards
35+
NEXT_PUBLIC_PYODIDE_EXECUTION_TIMEOUT_MS=5000
36+
NEXT_PUBLIC_MAX_STDOUT_CHARS=50000
37+
38+
# ------------------------------------------------------------------------------
39+
# Optional AI Tutor Integration (Phase 10)
40+
# ------------------------------------------------------------------------------
41+
AI_TUTOR_PROVIDER=disabled
42+
AI_TUTOR_API_KEY=your-ai-api-key-placeholder

‎.github/workflows/ci.yml‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
concurrency:
10+
group: ${{ github.workflow }}-${{ github.ref }}
11+
cancel-in-progress: true
12+
13+
jobs:
14+
governance:
15+
name: Verify Process & Governance
16+
runs-on: ubuntu-latest
17+
steps:
18+
- name: Checkout repository
19+
uses: actions/checkout@v4
20+
with:
21+
fetch-depth: 0
22+
23+
- name: Setup Node.js
24+
uses: actions/setup-node@v4
25+
with:
26+
node-version: 20
27+
28+
- name: Verify process.md update
29+
run: node scripts/verify-process-update.mjs --ci
30+
31+
- name: Architecture synchronization check
32+
if: github.event_name == 'pull_request'
33+
run: |
34+
# Warn if architecture-sensitive files changed but tech.md was not updated
35+
CHANGED_FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
36+
ARCH_SENSITIVE=$(echo "$CHANGED_FILES" | grep -E '^(apps/api/app/core/|apps/web/lib/pyodide/|alembic/|docker-compose)' || true)
37+
TECH_UPDATED=$(echo "$CHANGED_FILES" | grep '^tech.md$' || true)
38+
if [ -n "$ARCH_SENSITIVE" ] && [ -z "$TECH_UPDATED" ]; then
39+
echo "::warning title=tech.md Not Updated::Architectural/core files were modified without updating tech.md. Please ensure tech.md reflects architectural changes."
40+
fi
41+
42+
lint-and-typecheck:
43+
name: Lint & Typecheck
44+
runs-on: ubuntu-latest
45+
steps:
46+
- name: Checkout repository
47+
uses: actions/checkout@v4
48+
49+
- name: Setup Node.js
50+
uses: actions/setup-node@v4
51+
with:
52+
node-version: 20
53+
54+
- name: Setup Python
55+
uses: actions/setup-python@v5
56+
with:
57+
python-version: "3.11"
58+
59+
- name: Check Frontend (if initialized)
60+
run: |
61+
if [ -f "apps/web/package.json" ]; then
62+
echo "Running frontend lint and typecheck..."
63+
# npm run lint / npm run typecheck when web app is installed
64+
else
65+
echo "Frontend not yet initialized. Skipping."
66+
fi
67+
68+
- name: Check Backend (if initialized)
69+
run: |
70+
if [ -f "apps/api/pyproject.toml" ] || [ -f "apps/api/requirements.txt" ]; then
71+
echo "Running backend lint and typecheck..."
72+
# ruff check / mypy when api is installed
73+
else
74+
echo "Backend not yet initialized. Skipping."
75+
fi
76+
77+
backend-tests:
78+
name: Backend Tests (pytest)
79+
runs-on: ubuntu-latest
80+
steps:
81+
- name: Checkout repository
82+
uses: actions/checkout@v4
83+
84+
- name: Setup Python
85+
uses: actions/setup-python@v5
86+
with:
87+
python-version: "3.11"
88+
89+
- name: Run pytest (if initialized)
90+
run: |
91+
if [ -d "apps/api/tests" ]; then
92+
echo "Running pytest..."
93+
# pytest apps/api/tests
94+
else
95+
echo "Backend tests not yet initialized. Skipping."
96+
fi
97+
98+
frontend-tests:
99+
name: Frontend Tests (vitest)
100+
runs-on: ubuntu-latest
101+
steps:
102+
- name: Checkout repository
103+
uses: actions/checkout@v4
104+
105+
- name: Setup Node.js
106+
uses: actions/setup-node@v4
107+
with:
108+
node-version: 20
109+
110+
- name: Run vitest (if initialized)
111+
run: |
112+
if [ -f "apps/web/package.json" ]; then
113+
echo "Running frontend vitest..."
114+
# npm test when web app is installed
115+
else
116+
echo "Frontend tests not yet initialized. Skipping."
117+
fi
118+
119+
build:
120+
name: Build Verification
121+
runs-on: ubuntu-latest
122+
needs: [governance]
123+
steps:
124+
- name: Checkout repository
125+
uses: actions/checkout@v4
126+
127+
- name: Setup Node.js
128+
uses: actions/setup-node@v4
129+
with:
130+
node-version: 20
131+
132+
- name: Build Web (if initialized)
133+
run: |
134+
if [ -f "apps/web/package.json" ]; then
135+
echo "Building web..."
136+
else
137+
echo "Apps not yet created. Governance build check passed."
138+
fi

‎.gitignore‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Dependencies
2+
node_modules/
3+
.pnpm-store/
4+
__pycache__/
5+
*.py[cod]
6+
*$py.class
7+
8+
# Environments & Virtual Environments
9+
.env
10+
.env.local
11+
.env.development.local
12+
.env.test.local
13+
.env.production.local
14+
!.env.example
15+
.venv/
16+
venv/
17+
ENV/
18+
env/
19+
20+
# Build and Distribution Outputs
21+
.next/
22+
out/
23+
build/
24+
dist/
25+
*.egg-info/
26+
.eggs/
27+
28+
# Testing & Coverage
29+
coverage/
30+
.nyc_output/
31+
.coverage
32+
.coverage.*
33+
htmlcov/
34+
.pytest_cache/
35+
.ruff_cache/
36+
.mypy_cache/
37+
38+
# Runtime and Cache
39+
.cache/
40+
*.log
41+
npm-debug.log*
42+
yarn-debug.log*
43+
yarn-error.log*
44+
pnpm-debug.log*
45+
46+
# System and Editor Files
47+
.DS_Store
48+
.AppleDouble
49+
.LSOverride
50+
Thumbs.db
51+
.idea/
52+
.vscode/
53+
*.swp
54+
*.swo

‎.husky/pre-commit‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
#!/bin/sh
2+
node scripts/verify-process-update.mjs

‎AGENTS.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# AGENTS.md — Protocol for AI Coding Agents
2+
3+
> **MANDATORY INSTRUCTIONS FOR ALL AI CODING ASSISTANTS**
4+
> (Antigravity, Claude, ChatGPT, Cursor, GitHub Copilot, Devin, etc.)
5+
6+
Welcome, Agent. You are operating on **PyPath**, an interactive Python learning platform engineered to production standards.
7+
8+
You are expected to act as a **Principal Software Engineer, System Architect, and Long-Term Maintainer**. Your responsibility is not merely to emit code snippets, but to design, build, test, document, and preserve the long-term integrity of this codebase.
9+
10+
---
11+
12+
## 1. Non-Negotiable Operating Principles
13+
14+
1. **The Repository is Authoritative**: Never rely on your training memory or assumptions. Always inspect the current repository state before acting.
15+
2. **Never Skip `process.md`**: Every meaningful change you make MUST be recorded as an audit entry in `process.md`. A commit will be rejected if `process.md` is not updated.
16+
3. **Synchronize `tech.md`**: If your changes introduce architectural decisions, new frameworks, database alterations, execution model changes, or security policies, you MUST update `tech.md`.
17+
4. **Absolute Execution Safety**: NEVER execute arbitrary student code inside the FastAPI backend. Never use `exec()` or `eval()` on student inputs in Python server code. Pyodide in Web Workers is the designated execution engine.
18+
5. **No False Claims**:
19+
- Never say "tests pass" unless you have explicitly executed the test runner and verified clean output.
20+
- Never say "feature complete" when UI or logic remains mocked or partial.
21+
- Never fabricate deployment status or integration validity.
22+
23+
---
24+
25+
## 2. Mandatory Session Startup Protocol
26+
27+
At the start of every single interaction or task, you must execute these steps in order:
28+
29+
1. **Read `tech.md`**: Absorb the technical specification, tech stack, architecture, and ADRs.
30+
2. **Read `process.md`**: Inspect `Current Status` (current phase, milestone, active debt, next task) and review the most recent entries.
31+
3. **Read `AGENTS.md`**: Refresh your adherence to these agent protocols.
32+
4. **Inspect Git Status**: Run `git status` to detect uncommitted changes or active branch state.
33+
5. **Review Current Roadmap Phase**: Ensure your proposed task aligns with the active phase in `tech.md` Section 39.
34+
6. **Inspect Relevant Code & Tests**: Read the files and test suites directly affected by your assignment.
35+
7. **Continue Existing Architecture**: Match patterns, formatting, and conventions already established in the codebase.
36+
37+
---
38+
39+
## 3. The Definition of Done for Agents
40+
41+
A task is NOT finished until:
42+
- [ ] Code is cleanly implemented with complete type annotations (TypeScript strict, Python type hints).
43+
- [ ] Automated tests (unit, integration, or E2E) are written or updated.
44+
- [ ] Automated tests are executed and pass.
45+
- [ ] `scripts/verify-process-update.mjs` passes.
46+
- [ ] `process.md` is updated with a new `PROC-XXX` entry and updated `Current Status`.
47+
- [ ] `tech.md` is updated if any architectural decision or schema was modified.
48+
49+
---
50+
51+
## 4. End-of-Session Reporting Format
52+
53+
At the conclusion of your response, you MUST provide a structured summary matching this exact format:
54+
55+
```text
56+
### Work Completed
57+
- [Detailed bullet points of changes made]
58+
59+
### Files Changed
60+
- [List of modified, added, or deleted files]
61+
62+
### Database Changes
63+
- [Migrations created or schema modifications; or "None"]
64+
65+
### API Changes
66+
- [New or modified endpoints; or "None"]
67+
68+
### Code Execution Changes
69+
- [Modifications to Pyodide, Web Workers, or grading; or "None"]
70+
71+
### Curriculum Changes
72+
- [Courses, modules, lessons, or exercises added; or "None"]
73+
74+
### Tests Added & Run
75+
- Tests added: [filenames / test functions]
76+
- Tests run: [exact command executed]
77+
- Results: [exact output, e.g. "X passed in Ys"]
78+
79+
### Known Issues
80+
- [Any active edge cases, or "None"]
81+
82+
### Technical Debt
83+
- [Any debt accepted, rationale, and tracking ID; or "None"]
84+
85+
### Documentation Updated
86+
- `process.md`: Updated with entry PROC-XXX
87+
- `tech.md`: [Updated / No update needed because...]
88+
89+
### Current Roadmap Phase
90+
- [e.g., Phase 0: Project Governance]
91+
92+
### Next Recommended Task
93+
- [Immediate next priority for the next developer or agent]
94+
```
95+
96+
---
97+
98+
## 5. What NOT To Do (Strict Violations)
99+
100+
❌ DO NOT use `exec(user_code)` or `eval(user_code)` in FastAPI.
101+
❌ DO NOT grade exercises using plain string matching (`student_code == solution`).
102+
❌ DO NOT hardcode course content directly inside React components (use version-controlled YAML in `content/`).
103+
❌ DO NOT commit private keys, secrets, or JWT tokens to the repository.
104+
❌ DO NOT delete or rename `tech.md` or `process.md`.
105+
❌ DO NOT abandon uncompleted work without documenting the state in `process.md`.
106+
❌ DO NOT bypass pre-commit hooks unless explicitly authorized by the user for an isolated emergency fix.

0 commit comments

Comments
 (0)