ether-to-astro 1.0.2 → 1.2.0

package/.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,87 @@
+name: Bug report
+description: Report incorrect, misleading, lossy, or contract-drift behavior.
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template when the current behavior is wrong, misleading, lossy, or does not match docs.
+
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Affected surface
+      options:
+        - MCP
+        - CLI
+        - Docs
+        - Charts / rendering
+        - Validation / tests
+        - Mixed / not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: current
+    attributes:
+      label: Current behavior
+      description: What happens today?
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What should happen instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: impact
+    attributes:
+      label: User impact
+      description: Why does this matter in practice?
+      placeholder: This causes incorrect astrology, misleading UX, or broken workflows because...
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Include tool calls, CLI commands, or input parameters.
+      placeholder: |
+        1. Call `...`
+        2. With input `...`
+        3. Observe `...`
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Relevant chart/date/timezone context
+      description: Add sanitized astrology context if it matters.
+      placeholder: Date, timezone, house system, location, planet categories, days_ahead, etc.
+
+  - type: textarea
+    id: docs_drift
+    attributes:
+      label: Docs or contract drift
+      description: If docs/tool descriptions are involved, note the mismatch here.
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Fix acceptance criteria
+      description: What would make this bug fixed?
+      placeholder: |
+        - Tool docs say...
+        - Response no longer drops...
+        - Validation covers...
+    validations:
+      required: true
+

package/.github/ISSUE_TEMPLATE/capability-request.yml

@@ -0,0 +1,117 @@
+name: Capability request
+description: Request a new feature, MCP primitive, skill, or reporting capability.
+title: "[Capability]: "
+labels:
+  - feature
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template for new capabilities across MCP, CLI, skills, or docs.
+
+        Before filing, check:
+        - `docs/product/product-tenets.md`
+        - `docs/product/architecture-boundaries.md`
+        - whether this belongs in MCP, a skill, or docs
+
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Recommended surface
+      description: Where should this capability primarily live?
+      options:
+        - MCP
+        - Skill
+        - CLI
+        - Docs
+        - Mixed / not sure
+    validations:
+      required: true
+
+  - type: dropdown
+    id: type
+    attributes:
+      label: Capability type
+      options:
+        - Feature
+        - Gap
+        - Skill enhancement
+        - Docs enhancement
+        - RFC / decision needed
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: What is missing or hard today? Write this like a PM problem statement.
+      placeholder: The current product can do X, but it cannot do Y, which blocks Z.
+    validations:
+      required: true
+
+  - type: textarea
+    id: user_story
+    attributes:
+      label: User story
+      description: Use the format “As a..., I want..., so that...”
+      placeholder: As a skill author, I want...
+    validations:
+      required: true
+
+  - type: textarea
+    id: value
+    attributes:
+      label: Why this matters
+      description: What user outcome or product goal does this unlock?
+      placeholder: This matters because...
+    validations:
+      required: true
+
+  - type: textarea
+    id: determinism
+    attributes:
+      label: Determinism and boundary check
+      description: Explain whether the proposed output is deterministic for the same inputs, and why it belongs in MCP, a skill, or another layer.
+      placeholder: The output is deterministic because... It belongs in MCP/Skill because...
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed_scope
+    attributes:
+      label: Proposed scope
+      description: What should this include? Keep it concrete.
+      placeholder: Add a new endpoint or mode that returns...
+    validations:
+      required: true
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: Flat list is fine. Focus on observable outcomes.
+      placeholder: |
+        - A client can...
+        - The response includes...
+        - Docs explain...
+    validations:
+      required: true
+
+  - type: textarea
+    id: examples
+    attributes:
+      label: Example input/output or workflow
+      description: Provide a tool call, user flow, or report snippet if helpful.
+
+  - type: textarea
+    id: dependencies
+    attributes:
+      label: Dependencies or related issues
+      description: Link related issues or note prerequisite work.
+
+  - type: textarea
+    id: non_goals
+    attributes:
+      label: Non-goals or constraints
+      description: What should this issue avoid doing?

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Product triage backlog
+    url: https://github.com/unsalted/ether-to-astro/blob/main/docs/product/product-tenets.md
+    about: Start here for product boundaries and MCP-vs-skill guidance.

package/.github/ISSUE_TEMPLATE/paper-cut.yml

@@ -0,0 +1,59 @@
+name: Paper-cut
+description: Report small UX, API, formatting, or workflow friction that should be easy to improve.
+title: "[Paper-cut]: "
+labels:
+  - paper-cut
+body:
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Affected surface
+      options:
+        - MCP
+        - CLI
+        - Docs
+        - Skill workflow
+        - Mixed / not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: friction
+    attributes:
+      label: Current friction
+      description: What is awkward or annoying today?
+    validations:
+      required: true
+
+  - type: textarea
+    id: desired
+    attributes:
+      label: Desired improvement
+      description: What small change would make this noticeably better?
+    validations:
+      required: true
+
+  - type: textarea
+    id: workaround
+    attributes:
+      label: Current workaround
+      description: How are you working around it now?
+
+  - type: textarea
+    id: user_story
+    attributes:
+      label: User story
+      description: Optional but helpful. Use “As a..., I want..., so that...”
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: Keep this small and concrete.
+      placeholder: |
+        - Response includes...
+        - Docs show...
+        - A client no longer needs to...
+    validations:
+      required: true
+

package/.github/pull_request_template.md

@@ -14,3 +14,4 @@
 - [ ] Scope is focused and avoids unrelated churn
 - [ ] Tests were added or updated when behavior changed
 - [ ] Docs were updated when workflow or interfaces changed
+- [ ] This change respects the MCP vs skill boundary in `docs/product/product-tenets.md` and `docs/product/adrs/0001-mcp-vs-skill-boundary.md`

package/.github/workflows/release.yml

@@ -13,10 +13,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Use Node.js 24
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: 24
           cache: npm

package/.github/workflows/test.yml

@@ -11,10 +11,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Use Node.js 24
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: 24
           cache: npm

package/AGENTS.md

@@ -1,7 +1,7 @@
 # AGENTS.md
 
 ## Purpose
-This file is for coding agents working in `astro-mcp`. It documents the real architecture and safe change workflow so edits stay correct and low-risk.
+This file is for coding agents working in `ether-to-astro`. It documents the real architecture and safe change workflow so edits stay correct, low-risk, and release-safe.
 
 ## Current Runtime Facts
 - Engine is native Node binding: `sweph` (not WASM/WASI).
@@ -68,8 +68,15 @@ Defined in `tests/validation/utils/tolerances.ts`:
 - `EphemerisCalculator.findExactTransitTimes()` in `src/ephemeris.ts`.
 - Transit root-selection policy in `src/transits.ts`.
 - Time conversion/disambiguation in `src/time-utils.ts`.
+- CLI/MCP surface drift between `src/cli.ts`, `src/index.ts`, and `src/astro-service.ts`.
+- Packaging / bin / publish behavior for `e2a` and `e2a-mcp`.
 - Capability checks and comparator severity in validation harness.
 
+## Review Priority Ladder
+- **P1** - Wrong astro math, wrong timezone/DST handling, wrong transit/root behavior, CLI/MCP contract drift, packaging/bin/publish breakage, or validation regressions that could ship incorrect results.
+- **P2** - Missing or weak tests for high-risk changes, docs/help-text drift, profile resolution regressions, or changes that make validation/debugging harder.
+- **P3** - Style, cleanup, wording, and low-risk refactors with no behavioral impact.
+
 ## Safe Change Workflow
 1. Make focused edits (avoid broad refactors).
 2. Run `npm run quality:gate` for normal changes.
@@ -86,9 +93,43 @@ Defined in `tests/validation/utils/tolerances.ts`:
 - Routine merge gate is `npm run build`, `npm run lint`, and `npm test -- --run`.
 - `npm run validate:astro` is targeted validation, not the default gate for every change.
 - Biome is the source of truth for formatting, import order, and linting.
+- CLI profile resolution is adapter-only behavior; do not leak `.astro.json`, `--profile`, or profile-file semantics into MCP tool contracts.
+- `src/astro-service.ts` is the shared behavior layer; prefer fixing logic there before adding surface-specific patches in CLI or MCP.
 - Preferred commit types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `build`, `ci`.
 - Keep commits scoped to one coherent change whenever possible.
 
+## Request Triage Guidance
+- When responding to bug reports, feature requests, or product-boundary questions, consult these docs first:
+  - `docs/product/product-tenets.md`
+  - `docs/product/architecture-boundaries.md`
+  - `docs/product/adrs/0001-mcp-vs-skill-boundary.md`
+  - `docs/product/post-iteration-2-triage.private.md` if present locally
+- Use those docs to classify the request before proposing implementation:
+  - `bug` for incorrect, lossy, misleading, or contract-drift behavior
+  - `feature` for reusable product capability
+  - `paper-cut` for small interface or workflow friction
+  - `skill` when the work is primarily synthesis, formatting, ranking, or preference-aware orchestration
+  - `MCP` when the work is deterministic or mostly deterministic, computational, reusable, and risky to reconstruct client-side
+- Apply the determinism rule explicitly:
+  - deterministic and generic astro computation is a strong candidate for MCP
+  - deterministic but policy-heavy or personalized workflow synthesis still belongs in a skill
+- If a competent LLM can solve the request in one or two calls using stable MCP primitives, prefer keeping it out of MCP unless there is strong evidence the pattern should become a reusable primitive.
+- For incoming product requests, prefer extending an existing tool with flags, fields, modes, or range support before proposing a new narrowly scoped MCP tool.
+
+## Writing Skills
+- When a request is classified as a `skill`, default the deliverable to a concrete `SKILL.md` or equivalent workflow spec, not a broad product narrative.
+- Repo-owned `SKILL.md` files should follow the Agent Skills spec, including YAML frontmatter with at least `name` and `description`.
+- Treat repo-owned skills as boring, compliant instruction bundles:
+  - clear purpose
+  - required inputs and assumptions
+  - exact MCP/tools to call
+  - output shape
+  - boundaries and non-goals
+- Prefer one or two stable MCP calls plus synthesis over embedding custom astro math, hidden heuristics, or pseudo-tool contracts in the skill.
+- Keep deterministic astro facts in MCP and user-specific ranking, emphasis, and interpretation in the skill.
+- Do not treat every skill idea in product docs or issues as a committed repo artifact. Many skill ideas are incubation examples unless explicitly promoted.
+- If authoring or revising a skill, prefer following the repo-local skill authoring guidance in `skills/.system/write-skill/SKILL.md`.
+
 ## Release Governance
 - `main` is PR-only and branch-protected; do not push directly.
 - Use Conventional Commits / commitizen-style messages for all commits.
@@ -102,9 +143,13 @@ Defined in `tests/validation/utils/tolerances.ts`:
 
 ## Known Gotchas
 - `sweph` has process-wide settings (e.g., ephemeris path); avoid per-request mutation.
+- In the normal Node runtime, rise/set and eclipse functionality are expected to work. Treat breakage there as a real regression, not as optional capability drift.
+- `get_server_status` is the source of truth for loaded-chart state on the MCP side. Do not invent parallel state reporting elsewhere.
 
 ## Agent Style for This Repo
 - Prefer minimal, typed, fixture-driven changes.
 - Keep adapter normalization stable when comparing outputs.
 - Do not mask solver regressions with broad dedupe/tolerance changes.
 - Keep external CLI parity optional and auto-skippable.
+- If changing command/tool signatures, update all three together: schema/help text, implementation, and tests.
+- For release-facing changes, check README/help text/package metadata for drift.

package/DEVELOPER.md

@@ -0,0 +1,78 @@
+# Developer Guide
+
+This guide is for contributors working in the repository.
+
+For product setup and end-user usage, see [SETUP.md](/Users/salted/Code/astro-mcp/SETUP.md).
+
+## Local Repo Setup
+
+Requirements:
+
+- Node.js 22+
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Build the local checkout:
+
+```bash
+npm run build
+```
+
+Use the local CLI after building:
+
+```bash
+npm run start:cli -- --help
+```
+
+## Quality Gates
+
+Routine merge gate:
+
+```bash
+npm run quality:gate
+```
+
+This runs:
+
+- `npm run build`
+- `npm run lint`
+- `npm test -- --run`
+
+Targeted validation for high-risk astrology engine changes:
+
+```bash
+npm run validate:astro
+```
+
+## Contributor Contract
+
+- Keep changes focused and avoid unrelated churn in the same diff.
+- Treat Biome as the source of truth for formatting, import order, and linting.
+- Use conventional commit messages: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `build`, `ci`.
+- Keep PR descriptions short and explicit about what changed and how it was verified.
+- Respect the MCP-vs-skill boundary documented in:
+  - [docs/product/product-tenets.md](/Users/salted/Code/astro-mcp/docs/product/product-tenets.md)
+  - [docs/product/architecture-boundaries.md](/Users/salted/Code/astro-mcp/docs/product/architecture-boundaries.md)
+  - [docs/product/adrs/0001-mcp-vs-skill-boundary.md](/Users/salted/Code/astro-mcp/docs/product/adrs/0001-mcp-vs-skill-boundary.md)
+
+## Technical Notes
+
+- Engine: native Swiss Ephemeris via Node `sweph` bindings
+- `sweph` is pinned to an exact version to keep validation fixtures and numerical baselines stable
+- Primary accuracy mode uses Swiss Ephemeris data files
+- `EPHEMERIS_VERSION=moshier` is supported as a lower-precision fallback
+- Chart rendering uses `@astrodraw/astrochart` with JSDOM
+
+## Common Commands
+
+```bash
+npm run build
+npm run lint
+npm test -- --run
+npm run validate:astro
+npm run start:cli -- --help
+```