root/Jyotisha
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5c0bec0c9419e12e2c1fcab8e75fd35d535cb50e
Jyotisha/AGENTS.md
T
Jesse_Chen 534f5e617c ci(gate): skip the staging gate for docs-only pushes without releasing stale code 
Twenty-four of the last sixty staging pushes were pure documentation, yet each
one ran (and cancelled) the full gate and image publish. Introduce
deploy/gated-paths.txt as the single source of truth for what must rerun the
gate: every Dockerfile COPY source, the Python package inputs, the workflow and
build-context files, and the repository files frontend/tests read at gate time.
Both triggers of backend-quality-gate.yml now carry that exact list; pushes
that touch none of it neither run the gate nor cancel a running code gate.

Because staging head may then legitimately sit ahead of the last tested SHA,
add deploy/is-docs-only-range.sh: it proves <base> is an ancestor of <head>
and that no changed path matches a gated glob, from local history when it is
available and otherwise from the Gitea compare API (per-commit `files`, parent
walk for ancestry, total_commits cross-checked). The publish dispatch and the
deploy-staging head checks accept an advanced head only when that script
succeeds; diverged, older, or code-bearing heads are still refused. In
deploy-staging the check runs after the gate-attested controller bundle is
extracted so only the tested checker and path list are ever executed; the
manual rollback branch is unchanged.

AGENTS.md §6.3/§6.4 describe the new contract: `.deployment.gitCommit` must
equal the latest staging commit that touched a gated path, not staging head.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VawU7Xfd5jS9wUEXz1XYmS
2026-09-02 04:02:04 +00:00

177 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Jyotish Skill Agent Constraints
本文件是当前项目给协作代理、自动化助手与派生工作流的硬约束补充。它不替代 `SKILL.md`，而是把最容易被偷懒、省略、或在多窗口工作时遗失的高严谨规则单独钉死。
## 0. Production Maintenance Truth
任何部署、线上故障、域名、登录或环境变量任务，先读取 `deploy/README.md`，不要重新猜测架构。
- Production domain: `https://jyotisha.chat`
- Primary source: `https://git.copse.top/root/Jyotisha.git`; GitHub upstream/mirror: `https://github.com/jesse-ux/Jyotisha.git`
- Migration target: Ubuntu VPS `118.194.235.34`; confirmed SSH port is a required deployment variable
- Target runtime: `/opt/jyotisha-production`, Compose project `jyotisha-production`
- Target secrets: `/opt/jyotisha-production/.env.production` and `.env.production.database`; never print, copy into chat, or commit
- Public edge: Caddy only; Next.js `3000` and Python API `5200` stay Docker-private
- Migration source: Spaceship DNS and Supabase project `vtvnfqmonbfuxmqkqdlc`; production target uses private PostgreSQL + Better Auth
- Capacity boundary: 2 vCPU / 4 GB RAM; use digest-pinned images, bounded DB pools, and no on-host application builds
- Cutover runbook: `docs/operations/production-server-migration-2026-08.md`; old VPS/Supabase remain rollback assets until final reconciliation
Deployment safety rules:
1. Run `git status --short --branch` before packaging; do not overwrite unrelated dirty files.
2. Before cutover, verify the authoritative DNS still matches the documented current phase; after cutover both user and admin hosts must resolve to `118.194.235.34`.
3. The target uses Better Auth with exact user/admin origins; migrated users must sign in again by OTP.
4. After deployment, verify `/login`, logged-out `/api/account` = `401`, internal `/api/health` = `200`, and `swisseph_available = true`.
5. Never expose port `5200`, `SUPABASE_SERVICE_ROLE_KEY`, model keys, user JWTs, passwords, or SSH private keys.
6. Production deployment is manual-only in Gitea. It consumes the exact staging-gate image digests, requires matching `main`/`staging`/public-staging SHA plus the manual release gate, and never changes DNS or imports production data. GitHub production deployment is retired.
## 1. High-Rigor Override
当用户明确要求以下任一项时，必须进入高严谨模式：
- 不要凭经验泛谈
- 必须拉满三大开源参照引擎能力
- 必须提交底层原始数据
- 必须验证过去案例
- 必须避免偷工减料
进入该模式后，以下规则全部强制执行：
1. 必须尝试交叉参照 `PyJHora`、`VedAstro`、`jyotishganit`，并保持许可证边界。
2. 必须优先调用本仓原生实现，不得只用轻量包装脚本代替主链代码。
3. 涉及 timing / event / outcome，不得只看 `Vimshottari`，至少需要 `Vimshottari + Narayana Dasha` 双轨交叉。
4. 必须按问题域强制调取相关分盘：
- 事业：`D10 + A10`
- 财富：`D2 / D11`
- 婚恋：`D9 + UL`
5. 必须交付原始数据依据：度数、Dasha 边界、Shadbala / Ashtakavarga、Yoga 名称、Ayanamsa / Node mode、外部证据路径。
## 2. Functional Benefic/Malefic Hard Constraint
**强制调取 Functional Benefic / Malefic 判定（功能性吉凶星判定）。**
这条约束与 Dasha / 分盘 / 原始数据交付同级，不得省略。
执行要求：
1. 每次进入高严谨模式，必须显式判定当前 Lagna 下的 `functional benefics` 与 `functional malefics`。
2. 任何关于事业、财富、婚恋、健康、障碍、回报、应期的结论，都不得只依据自然吉凶星（natural benefic/malefic）下判断，必须叠加功能性吉凶星层。
3. 若某颗星在自然属性与功能属性之间冲突，必须在输出中说明冲突来源，并降低置信度或标记 `blocked`。
4. 若未调用功能性吉凶星判定，不得声称该次解读完成了高严谨模式。
5. Technique Audit Table 中必须出现 `Functional Benefic/Malefic` 一行，说明：
- `Used / not used / blocked`
- 关键功能吉星
- 关键功能凶星
- 对结论置信度的影响
## 3. Existing MEVG Invocation Hard Constraint
**强制执行既有 MEVG 规则，不得把它当成可选增强项。**
本节不是新增一套验证系统，而是把 `SKILL.md` 与
`references/mandatory-verification-gate-protocol.md` 中已经存在的 MEVG
外部验证门控提升为协作代理硬约束。
执行要求：
1. 对用户提出的 **所有星盘运势类问题**、**所有有关印度占星推运的问题**，包括命盘解读、事业、财富、婚恋、健康、流年、流月、应期、事件预测、出生时间校正辅助和技法可靠性判断，必须执行 MEVG。
2. MEVG 必须包含：
- 全球 / 全网外部资料采集
- 真实案例参考
- 来源分级
- 冲突仲裁
- 未验证声明降级
3. 输出的 Technique Audit Table 必须出现以下两行：
- `MEVG / Global Web Evidence`
- `Real Case Calibration`
4. 若无法完成外部资料采集、无法找到真实案例、网络/工具不可用、或来源之间出现重大冲突，必须写成 `blocked` 或降级置信度，不得静默跳过。
5. 只有 **纯计算 / 纯代码 / 纯项目维护** 可以豁免 MEVG，例如运行测试、检查 Git 状态、修复代码、输出未解释的原始度数或 Dasha 边界。一旦开始解释“这代表什么运势”，豁免立即失效。
## 4. Honesty Boundary
以下情况必须明确写成 `blocked` 或降级置信度：
- 外部 oracle 尚未闭环
- 三大外部参照引擎中有一层无法合法或稳定调用
- 缺少分盘、Ayanamsa、Node mode 或出生精度
- 功能性吉凶星层未完成
- 双重大运或多系统结果发生实质冲突
- MEVG / Global Web Evidence 或 Real Case Calibration 未完成
禁止把内部一致性伪装成“已经全球顶级精度”。
## 5. Pre-Work Error Ledger Hard Constraint
为避免多窗口、多应用、多文件夹碎片导致重复误判，开工前 / 进行任何实质项目工作前必须读取：
- `docs/research/pre_work_error_ledger.md`
若任务涉及运行入口、镜像边界、外部 oracle、远端同步、适配器、测试验收或大规模资料治理，还必须读取：
- `docs/research/whole_machine_fragment_sweep_2026_07_05.md`
- `docs/research/whole_machine_fragment_sweep_round25_2026_06_25.md`
同时必须运行：
- `python3 scripts/pre_work_check.py --remote-timeout 8 --command-timeout 45`
该预检必须包含：
- `scripts/diagnose_external_engine_adapters.py --json`
执行要求：
1. 不得把 `.workbuddy` 镜像当作运行主仓。
2. 不得在 `git ls-remote` / fetch / push 等远端验证失败时声称云端已同步。
3. 不得在未查看当前 `git status --short --branch` 时覆盖或重置本地变更。
4. 新发现的重复错误、阻塞、碎片目录、远端验证失败，必须追加到错误台账或当轮 sweep 文档。
## 6. Git Branch Delivery Hard Constraint
分支模型：`staging` 是测试环境，`main` 是生产控制分支。所有改动必须先经
`staging` 验收，再提升到 `main`；不存在直接改 `main` 的交付路径。
1. 动手前必须 `git fetch origin --prune`，并以远端 **`origin/staging`** 为基线。不得基于本地 `staging` 或本地 `main`：这两个本地引用经常落后远端上百个提交，基于它们做出的分析和补丁会对不上真实代码。
2. 在独立 worktree 中开发，路径 `.worktrees/<主题>-<日期>`，分支 `codex/<主题>-<日期>`。不得在存在未提交修改的工作树上切换分支、stash、reset、覆盖或顺带提交用户变更。
3. 交付到 staging 用快进推送（`git push origin HEAD:staging`）。这会触发 Gitea `backend-quality-gate`；该工作流的 `push:` 触发带有与 `deploy/gated-paths.txt` 逐行一致的 `paths:` 过滤：改动**全部**落在该清单之外的纯文档推送（`docs/**`、根目录 `TASK-*.md` / `PROGRESS-*.md` / `CHANGELOG*.md` / `progress.md` / `task_plan.md` / `findings.md` / `BLOCKED.md` / `CONTEXT.md`、`AGENTS.md` 等记录文件）不触发门禁、不发布镜像、不部署；任何触及清单内路径的推送都会跑完整构建与部署。仍鼓励把文档与同批代码合并一次推送——文档单独推送虽不再取消正在运行的代码门禁，但会让 staging head 与已部署 SHA 分离，增加核对成本。
4. 由 quality gate 构建 digest 固定镜像并 dispatch `deploy-staging`，随后在 `https://staging.jyotisha.chat` 完成与风险相称的验收。`GET /api/health` 的 `.deployment.gitCommit` 必须等于**最近一次含门禁路径改动的 staging 提交**，而不再是 staging head：若其后只有纯文档提交，`deploy/is-docs-only-range.sh <该 SHA> <staging head>` 必须退出 0（publish 与 deploy-staging 对分叉、落后或含门禁路径的 head 仍会拒绝发布）；否则视为未部署。
5. 提升到 `main` **必须快进，不得 merge**。`.gitea/workflows/deploy-production.yml` 强制 `main` 与 `staging` 指向同一个 commit SHA；任何 merge commit 都会让生产部署以 `main and staging must identify the same reviewed release` 失败。
6. 生产部署手动执行：先跑 `release-quality-gate`，再 dispatch `deploy-production`。它复用 staging 已验收的镜像 digest，不重新构建。
7. 推送后必须核对远端 SHA，确认 `origin/staging`（以及提升后的 `origin/main`）确实包含目标提交；远端验证失败时不得声称已交付。
8. GitHub `upstream` 仅为镜像：其工作流文件已从仓库删除，GitHub Actions 已在仓库设置中关闭，不得用它验证交付状态。
## 7. Bug History Workflow Hard Constraint
任何包含“Bug、报错、失败、异常、回归、无法保存、无法删除、状态码错误、线上故障”等现象的任务，开始诊断前必须用报错原文、接口路径、状态码、模块名和用户操作强制检索，并完整读完命中的记录。该文件体量已不允许通读全文，但检索不是可选步骤，命中记录的防复发措施是否仍然存在必须逐条确认：
- `docs/BUG_HISTORY.md`
这份文件是产品与代码 Bug 的长期历史入口；`docs/research/pre_work_error_ledger.md` 继续负责基础设施、外部引擎、碎片目录与预检风险，两者不得互相替代。
执行要求：
1. 修复前必须用报错原文、接口路径、状态码、模块名和用户操作搜索历史记录，优先检查相同模块的根因与防复发措施。
2. 若历史问题复发，必须关联原 `BUG-NNN`，说明旧测试、约束或发布门禁为何未拦住；不得把复发伪装成无关的新问题。
3. Bug 修复必须在同一变更中更新 `docs/BUG_HISTORY.md`：补充现有记录或新增连续编号，并记录状态、现象、触发条件、根因、修复、验证、防复发、关联记录和修复版本。
4. 若当轮只能诊断或被阻塞，也要把已确认事实写成 `investigating` 或 `blocked`，不得编造根因或提前标记 `resolved`。
5. `resolved` 必须有与风险相称的证据：至少一个针对性回归测试；生产问题还必须有脱敏后的迁移、部署、健康检查或 smoke 证据。
6. Bug 历史严禁写入姓名、出生资料、邮箱、用户/案例 ID、Cookie、JWT、密码、密钥、完整请求体或模型原文。
## Agent skills
### Issue tracker
Issues and PRDs are tracked in this repository's GitHub Issues using the `gh` CLI. See `docs/agents/issue-tracker.md`.
### Triage labels
Triage uses the canonical `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, and `wontfix` labels. See `docs/agents/triage-labels.md`.
### Domain docs
Domain documentation uses the single-context layout. See `docs/agents/domain.md`.
## 8. API Server Growth Freeze
`scripts/jyotish_api_server.py` must not grow. New endpoints and features go in dedicated modules under `scripts/` and are thinly registered from the main file. Do not add new handler bodies, workflows, or feature branches to this file. The line-count cap is enforced by `tests/test_api_server_growth_contract.py` (live count at freeze plus 300 lines of bugfix slack).
Reference in New Issue View Git Blame Copy Permalink