Add repo hygiene layout and research indexes

2026-06-28 13:11:28 +08:00
parent 4a46b5faad
commit d790949b26
4 changed files with 120 additions and 0 deletions
@@ -3,6 +3,9 @@ __pycache__/
 *.pyo
 *.db
 *.sqlite
+.agents/
+venv_vedastro/
+scratch/local/
 hermes_memory.db/
 *.egg-info/
 dist/
@@ -0,0 +1,50 @@
+# Repository Layout
+
+This repository mixes product code, astrology research, oracle artifacts, and local experimentation. To keep the worktree usable, follow these layout rules.
+
+## Core Areas
+
+- `/Users/wuyongnaren/Documents/印度占星/mcp_server.py`
+  - adjudicator-facing MCP entrypoint
+- `/Users/wuyongnaren/Documents/印度占星/scripts/`
+  - reusable project code and maintained tooling
+- `/Users/wuyongnaren/Documents/印度占星/tests/`
+  - maintained regression and contract tests
+- `/Users/wuyongnaren/Documents/印度占星/references/`
+  - durable knowledge assets, oracle cases, and frozen methodology
+
+## Research
+
+- `/Users/wuyongnaren/Documents/印度占星/docs/research/`
+  - active research and current audits
+- `/Users/wuyongnaren/Documents/印度占星/docs/research/archive/`
+  - historical round notes and local draft research
+
+## Local Scratch
+
+- `/Users/wuyongnaren/Documents/印度占星/scratch/local/scripts/`
+  - one-off debugging scripts, temporary probes, ad hoc runners
+- `/Users/wuyongnaren/Documents/印度占星/scratch/local/outputs/`
+  - local generated JSON, text dumps, temporary reports
+
+These paths are local-only and ignored by git.
+
+## Local Runtime Noise
+
+The following should stay out of normal versioned work:
+
+- `/Users/wuyongnaren/Documents/印度占星/.agents/`
+- `/Users/wuyongnaren/Documents/印度占星/venv_vedastro/`
+- `/Users/wuyongnaren/Documents/印度占星/scratch/local/`
+
+## Practical Rule
+
+Before adding a new file, decide which lifecycle it belongs to:
+
+1. reusable project asset
+2. active research note
+3. archived research
+4. local scratch script
+5. local generated output
+
+If it is category 4 or 5, do not leave it in the repo root.
@@ -0,0 +1,31 @@
+# Active Fronts
+
+This file is the small index for the current engineering fronts that still drive code changes.
+
+## Relationship Adjudication
+
+- `/Users/wuyongnaren/Documents/印度占星/docs/research/marriage_adjudicator_first_pass_audit_2026_06_27.md`
+- `/Users/wuyongnaren/Documents/印度占星/references/event_judgment_marriage.md`
+- `/Users/wuyongnaren/Documents/印度占星/docs/superpowers/specs/2026-06-28-jaimini-marriage-bridge-v1-design.md`
+
+## Wealth Adjudication
+
+- `/Users/wuyongnaren/Documents/印度占星/docs/research/wealth_adjudicator_first_pass_audit_2026_06_27.md`
+- `/Users/wuyongnaren/Documents/印度占星/docs/research/wealth_adjudicator_second_pass_audit_2026_06_27.md`
+- `/Users/wuyongnaren/Documents/印度占星/docs/research/wealth_adjudicator_third_pass_audit_2026_06_27.md`
+- `/Users/wuyongnaren/Documents/印度占星/docs/research/wealth_adjudicator_fourth_pass_audit_2026_06_28.md`
+- `/Users/wuyongnaren/Documents/印度占星/docs/research/wealth_adjudicator_fifth_pass_audit_2026_06_28.md`
+- `/Users/wuyongnaren/Documents/印度占星/docs/research/wealth_adjudicator_sixth_pass_audit_2026_06_28.md`
+- `/Users/wuyongnaren/Documents/印度占星/docs/research/wealth_adjudicator_sixth_pass_avayogi_boundary_2026_06_28.md`
+- `/Users/wuyongnaren/Documents/印度占星/references/event_judgment_wealth.md`
+
+## Oracle Closure
+
+- `/Users/wuyongnaren/Documents/印度占星/docs/research/oracle_closure_master_dashboard_latest.md`
+- `/Users/wuyongnaren/Documents/印度占星/docs/research/public_benchmark_dashboard_latest.md`
+- `/Users/wuyongnaren/Documents/印度占星/references/oracle/`
+
+## VedAstro Adapter MVP
+
+- `/Users/wuyongnaren/Documents/印度占星/scripts/vedastro_service_adapter.py`
+- follow only after the Jaimini marriage bridge v1 regression loop is closed
@@ -0,0 +1,36 @@
+# Research Workspace
+
+This directory stores research notes, audits, benchmark packets, and active adjudicator iteration records for the Jyotish project.
+
+## Layout
+
+- `active/`
+  - reserved for current working research fronts that directly support the next implementation cycle
+- `archive/`
+  - historical round notes, sidecar work orders, and local draft research that should not clutter normal implementation work
+- top-level `docs/research/*.md`
+  - current canonical research notes that are still referenced by active engineering work
+
+## What Stays Top-Level
+
+Keep a research file at the top level only if at least one of the following is true:
+
+- it is referenced by an active implementation spec
+- it is referenced by tests, workflow docs, or benchmark dashboards
+- it captures a currently active adjudicator audit or closure board
+
+## What Moves To Archive
+
+Move a research file into `archive/` when:
+
+- it is a completed round log or sidecar work order
+- it is a local exploration draft with no active code dependency
+- it is superseded by a newer audit, dashboard, or implementation note
+
+## Current Working Rule
+
+When adding new research notes:
+
+1. put active, decision-driving notes at the top level
+2. move noisy round-by-round drafts into `archive/`
+3. avoid storing transient terminal captures or scratch outputs here