docs(readme): markdown-only + mobile-safe listing (no raw HTML) #71
+108
−121
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,51 @@ | ||||||
| # vibe-mod — architecture | ||||||
|
|
||||||
| The single load-bearing idea: **build-time AI, runtime determinism.** The model runs exactly once per | ||||||
| rule edit; runtime evaluation is plain TypeScript — no network, no model, fully reproducible. | ||||||
|
|
||||||
| ``` | ||||||
| Moderator types a rule | ||||||
| │ (only the moderator's sentence is sent — never Reddit content) | ||||||
| ▼ | ||||||
| OpenAI gpt-5.4-mini ──► JSON ──► Zod strict parse + action whitelist ──► rules:draft (Redis) | ||||||
| (build-time only) (reject if invalid) | ||||||
| │ dry-run preview / activate | ||||||
| ▼ | ||||||
| rules:active (Redis) | ||||||
| │ | ||||||
| Reddit triggers (onPostSubmit / onCommentSubmit / onPostReport / onCommentReport / onPostFlairUpdate) | ||||||
| ▼ | ||||||
| Deterministic evaluator (pure TS, 0 network, 0 LLM) ──► fact bag from the item + author + sub state | ||||||
| ▼ | ||||||
| Action executor ──► shadow? log only : live? act + write 30-day undo token + audit entry | ||||||
| ▲ | ||||||
| Scheduler: audit retention (daily) · dry-run replay · shadow-promote check (15 min) · rate-limit breaker (5 min) | ||||||
| ``` | ||||||
|
|
||||||
| ## Guarantees that hold by construction | ||||||
|
|
||||||
| | What | Value | Verify | | ||||||
| | --- | --- | --- | | ||||||
| | LLM calls per post/comment at runtime | **0** (pure-TS evaluator, no network) | [`src/server/evaluator.ts`](../src/server/evaluator.ts) | | ||||||
| | LLM calls per rule | exactly **1**, at edit time | [`src/server/routes/compose.ts`](../src/server/routes/compose.ts) | | ||||||
| | New-rule blast radius for first 24h | **0 live actions** (shadow default on) | `shadow: true` in [`rule-schema.ts`](../src/shared/rule-schema.ts) | | ||||||
| | Live action reversibility | **100% for 30 days** (per-action undo) | [`src/server/executor.ts`](../src/server/executor.ts) | | ||||||
| | Reddit content sent to the LLM | **none** (only the mod's typed sentence) | README → _Fetch domains_ | | ||||||
|
There was a problem hiding this comment. This reference to the README section is currently plain text. Converting it to a Markdown link improves the documentation's usability by allowing readers to navigate directly to the detailed explanation of fetch domains, especially since other entries in this table are already linked to their respective source files.
Suggested change
|
||||||
|
|
||||||
| ## Runtime | ||||||
|
|
||||||
| - **Devvit Web app** (Hono server, `@devvit/web`); all state in Devvit Redis, scoped per installation: | ||||||
| `rules:active`, `rules:draft`, `audit`, `rollback:<actionId>`, plus daily-quota counters. | ||||||
| - The evaluator builds a **fact bag** from the triggering item + author account + subreddit-scoped state, | ||||||
| then evaluates the rule's boolean tree over a closed set of fact paths. Zero network, zero model. | ||||||
| - The executor, in shadow, only logs; live, it acts and writes a 30-day undo token + an audit entry. | ||||||
| - Multi-rule conflicts are surfaced as a read-only preview in _"vibe-mod: View rules + log"_ | ||||||
| (see [`conflict-handling.md`](./conflict-handling.md)). | ||||||
|
|
||||||
| ## Tested without Devvit's runtime | ||||||
|
|
||||||
| A 236-test suite (1 skipped): unit + route tests (`app.fetch()` against Devvit/OpenAI doubles) + | ||||||
| property-based tests, the official [`@devvit/test`](https://www.npmjs.com/package/@devvit/test) harness | ||||||
| for the executor, an `npm run acceptance` gate (G1–G4), and an `npm run replay` event replayer. The Devvit | ||||||
| runtime itself (routing, payload injection, RPC) is verified by `devvit playtest`. See | ||||||
| [`for-developers.md`](./for-developers.md). | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,28 @@ | ||||||||||
| # vibe-mod — for developers | ||||||||||
|
|
||||||||||
| ```bash | ||||||||||
| npm install # installs deps + git hooks (npm ci does NOT work here — esbuild EBADPLATFORM) | ||||||||||
| npm run typecheck # tsc --noEmit | ||||||||||
| npm test # 236 tests (1 skipped); npm run test:devvit for the @devvit/test harness | ||||||||||
| npm run acceptance # G1..G4 exit gates | ||||||||||
| npm run doctor # pre-deploy preflight (devvit.json integrity, fetch-domain↔permissions, route parity) | ||||||||||
| npm run build # tsc --noEmit && vite build → dist/server/index.cjs (CJS server bundle) | ||||||||||
| npm run openai:smoketest # real OpenAI API (needs OPENAI_API_KEY in .env) — model comparison table | ||||||||||
| npm run dev # = devvit playtest (needs `devvit login` + `devvit upload` first) | ||||||||||
| ``` | ||||||||||
|
|
||||||||||
| | Path | What | | ||||||||||
| | --- | --- | | ||||||||||
| | `src/shared/{rule-schema,system-prompt,starter-rules}.ts` | Zod v4 strict schema · gpt-5.4 prompt + few-shot · 6 seed rules | | ||||||||||
| | `src/server/{evaluator,fact-bag,executor,devvit-helpers}.ts` | deterministic evaluator · fact bag · action executor + audit + undo · `@devvit/web` adapters | | ||||||||||
| | `src/server/index.ts` + `src/server/routes/*` | Hono entry (re-exports `app`) + menu / form / trigger / scheduler route modules | | ||||||||||
| | `scripts/{acceptance,devvit-doctor,replay,openai-smoketest}.ts` | the `npm run` tooling | | ||||||||||
| | `test/` + `vitest.devvit.config.ts` | reusable in-memory Devvit testkit + the official `@devvit/test` config | | ||||||||||
| | `docs/devvit-setup-guide.md` | how to take this repo to a published Devvit app (wizard → upload → settings → playtest → publish) | | ||||||||||
| | `docs/architecture.md` | build-time-AI / runtime-determinism design + the by-construction guarantees | | ||||||||||
|
Comment on lines
+21
to
+22
There was a problem hiding this comment. These documentation paths are currently plain text. Since these files reside in the same directory, converting them to relative Markdown links would improve navigability within the documentation, maintaining consistency with how
Suggested change
|
||||||||||
| | `assets/icon.png` | the 1024² App Directory icon (`marketingAssets.icon` in `devvit.json`) | | ||||||||||
|
|
||||||||||
| The Devvit runtime (routing/RPC) is verified by `devvit playtest`; everything else is covered by the test | ||||||||||
| suite + the acceptance gate. CI (`.github/workflows/ci.yml`) runs lint (0 warnings) → format check → | ||||||||||
| `tsc` → tests (coverage) → `@devvit/test` → acceptance → `vite build` → "server bundle loads" smoke on | ||||||||||
| every push. Dependabot groups `@devvit/*` updates into one weekly PR. | ||||||||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
펜스 코드블록에 언어 지정이 빠져 markdownlint(MD040) 경고가 발생합니다.
```대신 예:```text로 언어를 명시해 주세요.수정 예시
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 6-6: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents