Skip to content
49 changes: 44 additions & 5 deletions README.ko.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,10 +104,49 @@ $EDITOR .sdlc/config.md # build, test, lint, run, e2e,
logs/ 모든 PASS·FAIL 뒤의 원본 출력, scripts/는 시나리오별 재실행 스크립트
```

끝난 기능은 `.sdlc/archive/`로 옮겨집니다. 검증된 사실은 `memory` 폴더로
옮기고, 다음 기능의 scout가 그 폴더부터 읽습니다. 그 안의 `glossary.md`가
프로젝트 용어집입니다. Intent는 요청의 용어를 여기에 대조하고, Evidence는 기능에서
확정한 용어를 여기에 더합니다.
끝난 기능은 `.sdlc/archive/`로 옮겨지고, `logs/` 아래 다시 만들 수 있는 캐시
(`gradle-home`, `node_modules`, `build` 등, config.md `prune:`)는 지웁니다.
검증된 사실은 `memory` 폴더로 옮깁니다. 코드에서 싸게 알 수 없는, 다시 쓸 사실·규칙·함정만
둡니다. 사실 한 줄은 근거와 날짜로 끝납니다(`[verified: <경로> @ <sha> | as-of: <날짜>]`,
`[source: <slug 또는 대화 기록> | as-of: <날짜>]`, `[unconfirmed]`). 에이전트는 close 때만이
아니라, 그런 것을 검증하거나 함정에 빠진 그 순간에 페이지를 씁니다. `INDEX.md` 맨 위의
`## Core`는 사람이 관리하는 칸으로, 모든 에이전트에게 필요한 규칙 몇 개만 한 줄과 링크로
둡니다(25줄, `memory_core_kb` 이하). 그 아래는 페이지마다 한 줄인 생성 목록입니다(`sdlc.sh memory
index`가 다시 만들고 `close`가 갱신). 색인은 없는 파일을 가리키는 링크, `MOVED TO` 껍데기 페이지,
근거 표시 없는 페이지, `memory_page_kb`를 넘는 페이지, `## Current picture` 없이 8,000바이트를
넘는 페이지도 셉니다. 에이전트는 색인부터 읽고 그 색인이 가리키는 페이지만 열며, 항목이 없으면
memory를 grep합니다. `close <slug> shipped`에는 evidence.md Shipping의 `Memory:` 줄(고친 페이지,
또는 `none — <이유>`)이 필요합니다. 그 안의 `glossary.md`가 프로젝트 용어집입니다. Intent는
요청의 용어를 여기에 대조하고, Evidence는 기능에서 확정한 용어를 여기에 더합니다.

`sdlc.sh dream --check`는 마지막 정리 뒤 기능 3개가 닫혔거나(shipped·dropped 모두), 하나 이상
닫힌 채 14일이 지나면 10으로 끝나고(닫힌 것이 없으면 하지 않음, 예: `due: 3/3 closes since <시각>`),
`sdlc.sh dream`은 새 에이전트에게 줄 지시(`roles/dreamer.md`)를 출력할 뿐 아무것도 기록하지
않습니다. 그 에이전트는 memory를 HEAD 코드와, 세션에서 일어난 일은 그 기능의 대화 기록과 `logs/`와
대조해 낡은 내용을 고치거나(대체됨·충돌 표시) 지우고, 중복을 합치고, 여러 세션에서 되풀이된 실수를
규칙으로 만들고, `## Core` 규칙을 올리고 내리고, 닫힌 기능에서 쓸 사실을 거두고, 크기 예산을
지킵니다. 마지막 단계 `sdlc.sh dream --done [--through <시각>] [--note <메모>]`가 `.dream-state`에
기록합니다(지시문이 `--through` 시각을 알려 주므로 그 뒤에 닫힌 기능은 다음 정리 대상으로 남음).
dreamer가 `.dream-log.md`를 쓰지 않았으면 한 줄을 더합니다. 일정 실행기가 dreamer를 띄우지
못해도 정리 차례를 잃지 않습니다.

대화 기록(transcript)은 dream이 메모를 대조하는 세션 원본입니다. `transcripts:`에 셸 명령을 두면
프로젝트 루트에서 `{slug}`와 `{since}`(마지막 정리 UTC 시각)를 바꿔 실행하고, 그 기능의 대화
기록·로그 경로나 `경로:줄` 위치를 출력하게 합니다. 예: `transcripts: grep -rln {slug} ~/agent-sessions`.
지시문에는 기능마다 `transcripts_max`개까지 `경로` 또는 `경로:줄`만 실리고(본문은 싣지 않음),
dreamer는 파일 전체를 읽지 않고 grep합니다.

지식은 종류마다 집이 하나입니다. 프로젝트 지식은 memory 폴더가 집이고, 따로 쓰는 다른 메모 저장소
(비서의 개인 메모, 다른 노트 시스템)는 사용자 선호·피드백이나 원본 기록처럼 제 종류만 둡니다. 그런
저장소를 `peers:`에 적습니다(공백이나 쉼표로 구분, `~`와 glob 허용, 상대 경로는 프로젝트 루트 기준).
지시문에는 저장소마다 파일 수와 크기만 실리고(본문은 싣지 않음), dreamer는 손대는 사실을 그곳에서
grep하되 고치지 않으며, 중복이나 모순은 `peer: <peer 파일> duplicates|contradicts <memory 페이지> —
propose: keep in <페이지>, remove from peer` 줄로 보고해 사람이 처리하게 합니다. 한꺼번에 옮기지 않습니다.

config.md에 선택해 넣을 키와 기본값: `transcripts:`·`peers:`(비우면 없음), `transcripts_max: 20`,
`memory_core_kb: 2`, `memory_page_kb: 16`, `memory_top_kb: 64`, `memory_total_kb: 256`(색인 경고),
`dream_every: 3`, `dream_max_days: 14`, `prune: gradle-home .gradle node_modules build .m2 target`(비우면
지우지 않음), `archive_warn_mb: 50`.

## 설정

Expand Down Expand Up @@ -174,7 +213,7 @@ TUI와 웹 페이지는 영어나 한국어로 표시합니다. `--lang ko`(TUI
TUI에서는 `L`, 웹 페이지에서는 언어 메뉴로 바꾸며 다시 시작하거나 새로 고칠 때까지 유지됩니다.
상태는 다음에 누가 움직일지 보여 줍니다. 내 차례(범위 승인·계획 승인·답변), 지금 작업 중(에이전트가 3분 안에 `working`으로 표시한 항목, 몇 분째·무슨 일인지 함께 보임), 에이전트 차례(아직 아무도 잡지 않음), 답변 전달됨 — 에이전트 수신 전, 시작 전, 막힘 — 조치 필요, 완료이며, 에이전트가 멈추는 행에는 그 사실을 적습니다.
항목에는 마크다운 브리프를 붙일 수 있습니다(`brief <id> <절대 경로>` 또는 `add --brief PATH`, ` - brief: <경로>`로 저장). 앱과 페이지는 이를 sdlc 작업 문서처럼(At a glance, Questions for you, 전체 문서는 접음) 보여 주며 승인 버튼은 없습니다. 브리프는 앱이 읽는 하나뿐인 형식인 `todo/brief.md`(Your call, What changes, AI pick, Phase, Background, Why)로 쓰고, 채울 수 없는 줄은 뺍니다.
항목에는 변경이 들어간 저장소도 적을 수 있습니다(`repos <id> aidt-lms-api,aidt-viewer-api`, ` - repos: aidt-lms-api, aidt-viewer-api`로 저장, 이름 없이 실행하면 지움). 앱 카드, 페이지 목록·상세, TUI 목록·상세에 항상 보입니다.
항목에는 변경이 들어간 저장소도 적을 수 있습니다(`repos <id> web-api,admin-api`, ` - repos: web-api, admin-api`로 저장, 이름 없이 실행하면 지움). 앱 카드, 페이지 목록·상세, TUI 목록·상세에 항상 보입니다.
결정에는 한 번에 고르는 답을 붙일 수 있습니다(`choices <id> "진행 | 먼저 고침 | 보류" [--pick N]`, ` - choices: 진행 | 먼저 고침 | 보류`와 ` - pick: N`으로 저장, 최대 6개, 답 없이 실행하면 지움). 열린 항목이면 앱 카드, 페이지 상세(답변 칸 위), TUI(숫자 키)에 답마다 버튼이 생기고, 누르면 그 답 글자 그대로 보통 답변으로 보냅니다. `--pick`으로 고른 답은 맨 앞에 "권장"으로 표시합니다. 같은 티켓 링크를 가진, 내가 볼 열린 항목은 앱과 페이지에서 그 티켓 아래에 모아 보입니다.

에이전트는 권장 답을 미리 채워 둘 수도 있습니다(`suggest <id> "답"`, ` - suggest: 답`으로 저장, 내 답변이나 빈 값이 지움). 앱 카드, 페이지 답변 칸, TUI 답변 줄(`r`)이 그 글자로 시작하므로 그대로 보내면 한 번에 끝납니다. 고친 답은 덮어쓰지 않고, 새 권장 답은 고치지 않은 칸만 바꿉니다. 앱 카드의 '에이전트가 묻고 있어요' 칸에는 요약의 Your call과 AI pick만 보이고(요약에 질문이 없을 때만 대기 문구), What changes는 그 아래 흐린 한 줄로 보입니다.
Expand Down
64 changes: 59 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,10 +124,64 @@ always says what comes next.
logs/ raw output behind every PASS and FAIL; scripts/ re-runs each scenario
```

Closed features move to `.sdlc/archive/`. Verified facts move to the
`memory` folder, which the next feature's scouts read first. Its
`glossary.md` holds the project's terms: Intent matches each request's terms
against it, and Evidence adds the terms a feature settled.
Closed features move to `.sdlc/archive/`, with reproducible caches under
`logs/` (`gradle-home`, `node_modules`, `build`, … — config.md `prune:`)
removed. Verified facts move to the `memory` folder: what the project taught
us that the code cannot tell cheaply, each fact line ending in its basis and
date (`[verified: <path> @ <sha> | as-of: <date>]`, `[source: <slug or
transcript> | as-of: <date>]` or `[unconfirmed]`). Agents write a page when
they verify such a thing or hit a trap, not only at close. Its `INDEX.md`
starts with a hand-kept `## Core` — the few rules every agent needs, one line
and a link each, at most 25 lines and `memory_core_kb` — above a generated
list of one line per page (`sdlc.sh memory index` rebuilds it; `close`
refreshes it). The index also lints: links to missing files, `MOVED TO`
stubs, pages without a basis tag, pages over `memory_page_kb`, and pages over
8,000 bytes without a `## Current picture`. Agents read the index first, then
only the pages it names, and grep memory when it has no entry.
`close <slug> shipped` needs a `Memory:` line in evidence.md's Shipping: the
pages updated, or `none — <why>`. Its `glossary.md` holds the project's terms:
Intent matches each request's terms against it, and Evidence adds the terms a
feature settled.

`sdlc.sh dream --check` exits 10 once 3 slugs closed (shipped or dropped)
since the last dream, or 14 days passed with at least one close — never with
none — and prints the count, e.g. `due: 3/3 closes since <time>`.
`sdlc.sh dream` then prints a brief (`roles/dreamer.md`) for a fresh agent,
recording nothing: it verifies memory against the code at HEAD and, for what
happened in a session, against the slug's transcripts and `logs/`; fixes,
supersedes or deletes stale notes; merges duplicates; turns mistakes repeated
across sessions into rules; promotes and demotes `## Core` rules; harvests the
closed slugs and keeps memory within budget. Its last step,
`sdlc.sh dream --done [--through <time>] [--note <text>]`, records the run in
`.dream-state` (the brief names the `--through` time, so slugs closed after
the brief stay due) and adds a `.dream-log.md` line if the dreamer wrote none.
A scheduler that fails to start the dreamer loses nothing.

Transcripts are the session record dreaming checks notes against. Set
`transcripts:` to a shell command, run in the project root with `{slug}` and
`{since}` (the last dream's UTC time) replaced, that prints the paths or
`path:line` hits of that slug's session transcripts or logs, for example
`transcripts: grep -rln {slug} ~/agent-sessions`. The brief lists at most
`transcripts_max` hits per slug, as `path` or `path:line` only — no transcript
text — and the dreamer greps them rather than reading whole files.

Each kind of knowledge has one home: the memory folder holds project
knowledge; other memory stores you run (an assistant's personal memory, a
notes system) keep their own kind, such as preferences or raw history. List
them in `peers:` (space- or comma-separated paths, `~` and globs allowed,
relative to the project root). The brief lists each with its file count and
size, never its content; the dreamer greps them for the facts it touches,
never edits them, and reports each duplicate or contradiction as
`peer: <peer file> duplicates|contradicts <memory page> — propose: keep in
<page>, remove from peer` for a person to act on. Nothing is moved in bulk.

Optional config.md keys, with their defaults: `transcripts:` and `peers:`
(empty: none),
`transcripts_max: 20`, `memory_core_kb: 2`, `memory_page_kb: 16`,
`memory_top_kb: 64` and `memory_total_kb: 256` (index warnings),
`dream_every: 3` and `dream_max_days: 14`,
`prune: gradle-home .gradle node_modules build .m2 target` (empty prunes
nothing) and `archive_warn_mb: 50`.

## Config

Expand Down Expand Up @@ -198,7 +252,7 @@ The TUI and web page show English or Korean: pass `--lang ko` (TUI or `web`) or
Press `L` in the TUI or use the page's language menu to switch until restart or reload.
Statuses say who acts next: your turn (approve intent, approve plan or answer), working now (an agent marked it with `working` within the last 3 minutes; it shows how long and on what), agent's turn (nobody is on it yet), answered — not picked up yet, not started, blocked — fix needed, or done; the row where agents stop says so.
An item may carry a markdown brief (`brief <id> <absolute path>` or `add --brief PATH`, stored as ` - brief: <path>`); the app and page show it like an sdlc work document (At a glance, Questions for you, full text folded) without approval. Write it from `todo/brief.md`, the one format the app reads (Your call, What changes, AI pick, Phase, Background, Why); leave out a line you cannot fill.
An item may also name the repositories its change touches (`repos <id> aidt-lms-api,aidt-viewer-api`, stored as ` - repos: aidt-lms-api, aidt-viewer-api`; no name clears it). The app card, the page row and detail, and the TUI row and detail always show them.
An item may also name the repositories its change touches (`repos <id> web-api,admin-api`, stored as ` - repos: web-api, admin-api`; no name clears it). The app card, the page row and detail, and the TUI row and detail always show them.
A decision can offer one-click answers (`choices <id> "proceed | fix first | hold" [--pick N]`, stored as ` - choices: proceed | fix first | hold` and ` - pick: N`; up to 6 labels, no labels clears them). On an open item the app card, the page detail (above the reply box) and the TUI (number keys) show one button per label; a click sends that exact label as an ordinary reply, and the picked one comes first, marked Recommended. Open items that need you and share a ticket link sit together under that ticket in the app and page.

An agent can also prefill the answer it recommends (`suggest <id> "answer"`, stored as ` - suggest: answer`; a human reply or no text clears it). The app card, the page reply box and the TUI reply line (`r`) start with that text, so sending it as-is takes one press; an edit is never overwritten, and a new suggestion replaces only an unedited one. On the app card the "agent is asking" box shows only the brief's Your call and AI pick (the waiting line only when the brief asks nothing), with What changes as one muted line below it.
Expand Down
22 changes: 11 additions & 11 deletions SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,8 @@ governs phase order, gates and proof.
| 3 | Build | `phases/3-build.md` | code, `review.md`, `logs/` | review PASS |
| 4 | Evidence | `phases/4-evidence.md` | `evidence.md`, `logs/` | `sdlc.sh score` routes |

`sdlc.sh next <slug>` names the next step and why. Run `sdlc.sh` (in this
kit's folder) from anywhere inside the project; it finds `.sdlc/` the way git
finds `.git`.
`sdlc.sh next <slug>` names the next step and why. Run this kit's
`sdlc.sh` from anywhere inside the project.

## Route a request

Expand Down Expand Up @@ -76,14 +75,15 @@ finds `.git`.
## Config and records

`.sdlc/config.md` holds every project value; `templates/config.md` documents
each key, the `knowledge:` alias and `review --repos`.
Default `human_gates`: `intent`.
Records are working
knowledge, not source: `init` keeps `.sdlc/` out of git through
`.git/info/exclude`, changing no tracked file. Closed features move
to `.sdlc/archive/<slug>/`. Scouts read `memory` first; Evidence adds what
was verified. The default `.sdlc/memory` stays on this machine; point
`memory:` at a tracked folder to share it.
each key. `init` keeps `.sdlc/` out of git via `.git/info/exclude`. Closed
features move to `.sdlc/archive/`.

Memory keeps what the next feature would reuse and cannot look up cheaply:
verified facts, traps with their fix, rules with how they were verified.
Read its `INDEX.md` and only the pages it names, else grep it; no hit:
answer "Not in memory" and what to look up. When you verify one or hit a
trap, update its page then — merge, never rewrite it whole — ending the
line `[verified: <path> @ <sha> | as-of: <date>]` or `[unconfirmed]`.

## Automation

Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
2.26.0
2.27.0
6 changes: 4 additions & 2 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ and an optional Node.js to-do add-on. The script never runs a model; the agent
| Phase files | `phases/1-intent.md` … `phases/4-evidence.md` | What the agent does in each phase and which artifact it writes. |
| Role files | `roles/scout.md`, `roles/reviewer.md`, `roles/qa.md` | Prompts for subagents that run in a fresh context: read-only scouts (Plan), the adversarial reviewer (Build), and persona QA (Evidence). |
| Templates | `templates/config.md`, `intent.md`, `PLAN.md`, `evidence.md`, `ref.md` | Skeletons the script copies and later parses. |
| State machine | `sdlc.sh` | `init`, `new`, `status [--json]`, `next`, `check`, `approve`, `review`, `score`, `close`. Parses the Markdown artifacts with awk, keeps per-feature state in `.sdlc/work/<slug>/.state`, and derives phase, state and next action. |
| State machine | `sdlc.sh` | `init`, `new`, `status [--json]`, `next`, `check`, `approve`, `review`, `score`, `close`, `memory index`, `dream [--check]`. The lock, memory index, close-time memory check and log pruning, and dream live in `lib/store.sh`, which `sdlc.sh` sources. Commands that write `.state` hold `.state.lock` from read to write. Parses the Markdown artifacts with awk, keeps per-feature state in `.sdlc/work/<slug>/.state`, and derives phase, state and next action. |
| QA adapter (optional) | `adapters/e2e/` | Templates and a vendored agent guide for writing browser/mobile scenarios as `e2e` tests when `qa_runner: e2e`. |
| Personal to-do (optional) | `todo/todo.mjs`, `todo/core.mjs`, `todo/tui.mjs`, `todo/web.mjs`, `todo/locales/`, `todo/app/` | One Markdown to-do file (`~/.sdlc/todo.md`) shown in a tray app, a TUI and a localhost web page that share one server; syncs each item's sdlc status by calling `sdlc.sh status <slug> --json`. The Rust app only calls the web API. |
| Tests | `tests/selftest.sh`, `tests/todo*.test.mjs`, `tests/fixture/` | Bash selftest of the script and prompt budgets, plus `node --test` suites for the to-do. |
Expand Down Expand Up @@ -69,7 +69,9 @@ One feature lives in `.sdlc/work/<slug>/`. The agent writes the artifacts;
5. **Close.** `close <slug> shipped` re-checks every gate, requires a deliver
route on the current evidence, refuses a `Shipped:` tree that differs from
the verified `Commit:`, and for `pr`/`deploy` requires `Authorized: yes` and
a commit present on a remote. The folder moves to `.sdlc/archive/`.
a commit present on a remote, and needs a `Memory:` decision in evidence.md.
Reproducible caches under `logs/` are pruned, the folder moves to
`.sdlc/archive/`, and the memory `INDEX.md` is rebuilt.

`status --json` and `next` share one function, `derive`, which walks these
checks in order and returns the first thing that is missing as the next action.
Expand Down
Loading
Loading