chore(agent_platform): remove stub hooks/plugins/skills + ship AUDIT.md

opensin_agent_platform/AUDIT.md

@@ -0,0 +1,62 @@
+# opensin_agent_platform — Overlap Audit (April 2026)
+
+> Read this before deciding what to port, retire, or keep.
+
+## TL;DR
+
+The "overlap with `opensin_core`" called out in `README.md` was largely a false alarm. The two trees live at **different layers of the stack** and only share three namespace names — which in this folder turned out to be empty stubs.
+
+- **Removed in this PR:** `src/hooks/`, `src/plugins/`, `src/skills/` — each was a 16-line stub `__init__.py`, no logic.
+- **Kept:** the rest of `src/` — 28 subdirectories of terminal-UI / agent-framework code that `opensin_core` does not cover.
+- **Still to decide (strategic):** whether this Python terminal surface should be retired in favor of `OpenSIN-Code` (TypeScript CLI), absorbed into `opensin_core`, or kept as a separate first-class package.
+
+## What the audit actually found
+
+### Namespace collisions (before this PR)
+
+| Namespace | `opensin_core/` | `opensin_agent_platform/src/` | Verdict |
+|---|---|---|---|
+| `hooks/` | 294 LOC across `events.py`, `executor.py`, `session_store.py` | 16 LOC stub `__init__.py` | Stub removed. Canonical: `opensin_core.hooks`. |
+| `plugins/` | 281 LOC across `base.py`, `manager.py`, `types.py` | 16 LOC stub `__init__.py` | Stub removed. Canonical: `opensin_core.plugins`. |
+| `skills/` | 878 LOC across `cli/`, `core/`, `models/`, `scanner/`, `sources/` | 16 LOC stub `__init__.py` | Stub removed. Canonical: `opensin_core.skills`. |
+
+No code needed to be ported — the stubs carried no logic.
+
+### Unique territory (kept)
+
+`opensin_agent_platform/src/` after stub removal holds ~66 Python files across 28 subdirectories that have **no counterpart in `opensin_core`**:
+
+- **Terminal UI:** `cli/`, `screens/`, `keybindings/`, `outputStyles/`, `vim/`, `voice/`
+- **Agent framework:** `assistant/`, `buddy/`, `coordinator/`, `bridge/`, `remote/`, `upstreamproxy/`
+- **Infrastructure:** `bootstrap/`, `entrypoints/`, `migrations/`, `memdir/`, `native_ts/`, `state/`
+- **Data:** `components/`, `constants/`, `schemas/`, `types/`, `reference_data/subsystems/`, `services/`, `utils/`
+
+This is a terminal/agent framework, not a runtime engine. `opensin_core` is the runtime engine.
+
+### What `opensin_core` already owns
+
+`opensin_core` is the production runtime — 171 Python files across `agent/`, `analytics/`, `api_server/`, `checkpoints/`, `core/`, `cron/`, `engine/`, `hooks/`, `lsp/`, `mcp/`, `memory/`, `permissions/`, `plugins/`, `routing/`, `sandbox/`, `session/`, `skills/`. Everything an agent needs to **run** lives here.
+
+## The real open question
+
+**Do we need a Python terminal surface at all?**
+
+- If `OpenSIN-Code` (TypeScript CLI) is THE autonomous terminal, this Python surface is duplicate work in a different language.
+- If `OpenSIN-Code` targets a different audience (developer using a TS ecosystem) than a Python-native terminal would, then this package has a reason to exist.
+
+Until that decision is made, the package stays as-is under `opensin_agent_platform/`. It:
+- is **not** imported by `opensin_core` / `opensin_cli` / `opensin_api`
+- is **not** built or shipped
+- carries a banner in its README making that explicit
+
+## Recommended next PR (not this one)
+
+Pick one of:
+
+1. **Retire.** Move the 28 subdirs to a read-only archive location (`OpenSIN/archive/agent_platform_py/`). Accept that `OpenSIN-Code` is the canonical terminal surface.
+
+2. **Productize.** Add a `pyproject.toml` under `opensin_agent_platform/`, wire it up as an installable package, import the three removed namespaces from `opensin_core` explicitly (`from opensin_core.hooks import ...`), and ship it as a separate PyPI project.
+
+3. **Absorb.** Move any framework-grade logic (e.g. `assistant/`, `coordinator/`) into `opensin_core.agent.*` and retire the rest. Mostly-UI code (`screens/`, `vim/`, `voice/`) probably doesn't belong in a runtime package at all.
+
+Any of these is a real PR with tests. The current audit just removes the three stub directories so the "overlap" story stops scaring future readers.

opensin_agent_platform/README.md

@@ -1,56 +1,37 @@
 # opensin_agent_platform
 
-> **Origin:** absorbed from the standalone repository `OpenSIN-AI/opensin-ai-code` in April 2026 as part of the OpenSIN-AI repo consolidation.
-
-## Why this folder exists
-
-`opensin-ai-code` was a separate public repo that described itself as the
-"Python Agent Development Platform" (`pip install opensin-ai-code`). It
-contained 98 Python source files under `src/` but no `pyproject.toml` or
-`setup.py` — so the advertised `pip install` path never actually worked.
-
-At the same time, the `OpenSIN` monolith already ships the canonical
-Python implementation as `opensin_core`, `opensin_cli`, `opensin_api`,
-and `opensin_sdk`. Two public repos were claiming the same ground with
-different code.
-
-To stop the drift, the full source tree of `opensin-ai-code` is preserved
-here, inside the canonical `OpenSIN` repo, as `opensin_agent_platform/`.
-The standalone repo is archived and redirects here.
+> **Origin:** absorbed from the standalone repository `OpenSIN-AI/opensin-ai-code` in April 2026.
 
 ## Status
 
-**Preserved, not yet wired into the main build.**
+**Preserved as reference material. Not wired into the OpenSIN build.**
+
+- The source lives under `src/` exactly as it did in the upstream standalone repo.
+- It is **not** imported from `opensin_core`, `opensin_cli`, or `opensin_api`.
+- No `pyproject.toml` is declared yet — the upstream repo never shipped one either.
+- `src/hooks/`, `src/plugins/`, `src/skills/` were removed in April 2026: they were 16-line stubs with no logic, and their real counterparts live in `opensin_core/{hooks,plugins,skills}/`.
 
-- The source lives under `opensin_agent_platform/src/` exactly as it did upstream.
-- It is **not** imported from `opensin_core`, `opensin_cli`, or `opensin_api` today.
-- No `pip install -e .` is declared yet — a follow-up PR will add a proper
-  `pyproject.toml` under this folder *or* migrate the pieces that still
-  provide value into the existing `opensin_*` packages and retire the rest.
+## What it is (really)
 
-## Overlap with `opensin_core`
+`opensin_agent_platform` is a Python **terminal UI + agent framework** — not a runtime engine. See the full audit: [`AUDIT.md`](./AUDIT.md).
 
-Both trees define modules named `hooks`, `plugins`, `skills`, and share
-conceptual components (QueryEngine, Tool system, Permission system,
-Subagent system, MCP client, Sandbox, Memory).
+| `opensin_core` | `opensin_agent_platform` |
+|---|---|
+| Runtime / backend engine | Terminal UI + agent framework |
+| Already canonical and shipped | Reference material pending strategic decision |
+| 171 .py files | ~66 .py files after stub cleanup |
+| Imported by everything | Imported by nothing |
 
-The rationalization plan — to be executed in a follow-up PR:
+## What to do with it
 
-1. Pick `opensin_core` as the canonical home.
-2. For each concept that exists in both, diff the implementations.
-3. Port any genuinely newer or better logic from
-   `opensin_agent_platform/src/` into the matching `opensin_core/*`
-   subpackage.
-4. Delete the migrated pieces from this folder.
-5. When the folder is empty of useful code, remove it entirely.
+See [`AUDIT.md`](./AUDIT.md) for three concrete options (retire / productize / absorb) and the reasoning. The decision depends on whether a Python terminal surface is wanted alongside `OpenSIN-Code` (the TypeScript CLI).
 
-Until then, **treat `opensin_agent_platform/` as read-only reference material**.
-Do not import from it in production paths.
+Until that decision is made, **treat this folder as read-only reference material**. Do not import from it in production paths.
 
-## Upstream README
+## Upstream
 
-The original upstream README is preserved as `README.upstream.md` for
-historical reference.
+- Archived repo: https://github.com/OpenSIN-AI/opensin-ai-code (redirects here)
+- Original README preserved verbatim at [`README.upstream.md`](./README.upstream.md)
 
 ## Redirect mapping