diff --git a/AGENTS.md b/AGENTS.md index 68e73c1..554fd8f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -308,11 +308,24 @@ archives the feature to `.sdlc/archive//`. it), `harvest` (unmerged candidates), `index` (contents page). `--area ` covers every store in that folder, including features whose checkout is gone. Exit 0 found · 1 nothing · 2 usage/refusal. -8. **Speak plainly.** Every report, gate request, and question starts with - one short context paragraph (which stage, what happened before, what this - message is for), uses short active sentences and the project's own - vocabulary, and ends with the one decision or action the reader must - take. +8. **Speak plainly, bottom line first** (adapted from Attention-kind, + github.com/alexgreensh/attention-span). What the reader skips was not + delivered. + - **Messages and Human summaries** (reports, gate requests, questions, + the Human summary of spec.md and plan.md): line one is the bottom line, + the result or that a decision is needed; one line of context (stage, + what came before); then one `**→ Lead-in.** rest` paragraph per point, + bold carrying the answer and every warning. The decision itself comes + last, and nothing follows it. + - **Records** (everything else): one idea per line; a fact stated once, + then pointed at (`R3`, `evidence.md §n`); a section without a verdict + line opens with its conclusion. summary.md sections open with their + point in bold. + - **Always:** short active sentences in the project's words; an + unavoidable term glossed in five words or fewer; numbers and scoped + conditions exact; a warning never cut for length. Too much at once: give + what matters most, then name the rest and where it lives. Verbatim + output and every line or heading a script reads keep their form. 9. **Heartbeat.** `.sdlc/work//progress.md` holds exactly one line — `[ n/m] · · ` — overwritten, never appended: as soon as the slug dir exists, on stage diff --git a/README.ko.md b/README.ko.md index 95809dd..b3ac8ad 100644 --- a/README.ko.md +++ b/README.ko.md @@ -173,6 +173,8 @@ agent APPROVED: intent of claims-status (.sdlc/work/claims-status/intent.md) `init.sh`는 프로젝트 `.gitignore`에 루트에 고정된 한 줄, `/.sdlc`만 추가합니다. 그래서 애플리케이션을 클론해도 기록은 따라오지 않습니다. 피처가 열려 있는 동안 `status.sh`가 하트비트를 나이와 함께 `now →` 줄로 보여줍니다. +**훑어 읽도록 씁니다.** 게이트 요청과 Human summary는 결론을 첫 줄에 쓰고 요점마다 굵은 `→` 문단을 하나씩 둡니다. 굵은 글씨만 읽어도 답과 경고가 모두 잡히고, 기록 문서는 같은 사실을 한 번만 씁니다. AGENTS.md 8번 규칙이며 [Attention-kind](https://github.com/alexgreensh/attention-span)를 바탕으로 했습니다. + **기록을 어디에 둘지는 사용자가 정합니다.** 기본값은 프로젝트 작업 사본 안입니다. `init.sh . --area ~/knowledge`를 쓰면 `/-/`에 저장하고 `.sdlc`를 그곳으로 연결합니다. 체크아웃마다 저장소가 하나씩이라 워크트리 두 개가 승인을 공유하지 않습니다. 저장소에 쓰거나 게이트 판정을 보고하는 스크립트는 모두 `/PROJECT`에 다른 체크아웃이 적혀 있으면 거부하므로, 복사한 작업 사본이 원본의 피처를 열거나 닫을 수 없습니다. 읽기는 이 제약을 받지 않아 `tools/kb.sh show|search|list`는 그대로 동작합니다. 킷이 대신 옮겨 주는 것은 없고, **저장소 백업은 사용자의 몫입니다.** 킷 디렉터리에는 프레임워크만 남습니다. **지식은 제품 영역별로 정리됩니다.** 웹앱이면 제품 영역은 메뉴 하나이고 메뉴 경로(`학습 > 평가 > 제출`)로 부릅니다. 그 밖에는 모듈, API, 배치 작업, CLI 명령입니다. 제품 영역마다 페이지 `memory/areas/학습 - 평가 - 제출.md`가 한 장 있고, 개발자가 아니어도 읽을 수 있게 씁니다. 업무 정책 P1, P2…, 건수·비율·점수·차트를 보여주는 영역이면 통계 산정 N1, N2…, 동작 방식, 그 영역을 바꾼 피처마다 이력 한 행이 들어갑니다. 맨 아래 접힌 근거 블록에는 출처, 코드 위치, `Drive:` 줄이 있습니다. `Drive:` 줄은 사용자가 그 영역에 닿는 경로, 그 영역을 구동하는 명령이나 도구, 성공을 증명하는 최종 상태, 함정을 적습니다. ship 단계가 E2E 검사에서 이 줄을 harvest 후보로 올리고, 다음 verifier는 이 줄에서 출발합니다. 피처의 `summary.md`는 제품 영역을 적고, spec은 어떤 정책과 수치를 유지하거나 바꾸는지 밝히며, Side effects verifier가 나머지를 다시 확인합니다. diff --git a/README.md b/README.md index 1f3e527..f0dd79f 100644 --- a/README.md +++ b/README.md @@ -173,6 +173,8 @@ Per feature, inside the **target project**: `init.sh` adds one anchored line, `/.sdlc`, to the project's `.gitignore`, so a clone of the application does not carry the records. While a feature is open, `status.sh` shows its heartbeat as a `now →` line with its age. +**Written to be skimmed.** Gate requests and Human summaries lead with the bottom line, then one bold `→` point each, so the bold alone carries the answer and every warning; records state each fact once. AGENTS.md rule 8, adapted from [Attention-kind](https://github.com/alexgreensh/attention-span). + **Where the records live is your choice.** By default they sit in the project's working copy. `init.sh . --area ~/knowledge` puts them in `/-/` instead, with `.sdlc` linked to it: one store per checkout, so two worktrees never share approvals. Every script that writes to the store or reports a gate verdict refuses when `/PROJECT` names another checkout, so a copied working copy cannot open or close the original's features. Reading is not bound: `tools/kb.sh show|search|list` still works. Nothing is ever moved for you, and **the store is yours to back up**. The kit directory stays framework-only. **Knowledge is filed by product area.** For a web app an area is one menu, named by its menu path (`학습 > 평가 > 제출`); otherwise a module, API, job, or CLI command. Each area has one page, `memory/areas/학습 - 평가 - 제출.md`, written for a non-developer: business rules P1, P2…, figures N1, N2… when the area shows counts, rates, scores, or charts, how it works, and one history row per feature that changed it. A folded evidence block at the bottom holds sources, code locations, and a `Drive:` line: how a user reaches the area, the command or tool that drives it, the end state that proves it, and the traps. Ship harvests that line from the E2E check, and the next verifier starts from it. A feature's `summary.md` names its area, the spec states which rules and figures it keeps or changes, and the Side effects verifier re-checks the rest. diff --git a/VERSION b/VERSION index 2157409..ca222b7 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.22.0 +0.23.0 diff --git a/log/changelog-v0.23.0.md b/log/changelog-v0.23.0.md new file mode 100644 index 0000000..f90a169 --- /dev/null +++ b/log/changelog-v0.23.0.md @@ -0,0 +1,37 @@ +# v0.23.0 — written to be skimmed: bottom line first + +Human summaries could run ten sentences with no bottom line, and long +records restated facts. AGENTS.md rule 8 now adapts the Attention-kind +output style (github.com/alexgreensh/attention-span, AGPL-3.0: principles +restated, no text copied). No new file, axis, gate, or check; no +script-read line changed. + +## Changes + +- **Rule 8, three parts.** Messages and Human summaries: the bottom line + first, one line of context, one `**→ Lead-in.**` paragraph per point, + the decision last. Records: one idea per line, each fact stated once + and then pointed at; a section without a verdict line opens with its + conclusion. Always: numbers and scoped conditions exact, warnings never + cut, verbatim output and script-read lines untouched. +- **Changed:** a message used to start with a context paragraph; it now + starts with the bottom line. +- **templates/spec.md, plan.md:** the Human summary is the bottom line plus + five (spec) or three (plan) `**→**` points, pointing at rule 8 instead of + restating it. skills/3-plan points at the template. +- **templates/summary.md:** each section opens with its point in bold. + +## Example (spec Human summary) + +> Teachers can re-order quiz questions by dragging them; one decision is +> needed. +> +> **→ Students see the new order** from their next attempt; submitted +> answers keep theirs. +> +> **→ Reports and exports are unchanged.** +> +> **→ Decision:** quizzes over **200 questions** load slowly in the editor. +> Recommend re-ordering only below 200 for now. + +Nothing to migrate: older artifacts stay valid. diff --git a/skills/3-plan/SKILL.md b/skills/3-plan/SKILL.md index 14314ad..ed56b71 100644 --- a/skills/3-plan/SKILL.md +++ b/skills/3-plan/SKILL.md @@ -55,9 +55,8 @@ exploration stays out of the main context. Then fill `templates/plan.md`: record the verdict in the template's **Gate tier** section, with reasons. Run `/tools/tripwire.sh .sdlc/work//plan.md` and include its output in the adversary dispatch. -- **Human summary.** Five short sentences or fewer at the top, in plain words - a non-technical reader can follow: what changes, - the main risk, how it is proven. Write it last, place it first. +- **Human summary.** In the template's shape (AGENTS.md rule 8). Write it + last, place it first. Constraints the code does not show (ownership, forbidden areas, deploy windows) are collected at the spec gate, not here. If a missing constraint diff --git a/templates/plan.md b/templates/plan.md index 254d8a5..d77e83c 100644 --- a/templates/plan.md +++ b/templates/plan.md @@ -4,8 +4,8 @@ ## Human summary (read this first) - + ## Gate tier diff --git a/templates/spec.md b/templates/spec.md index 3b65df9..175c8d3 100644 --- a/templates/spec.md +++ b/templates/spec.md @@ -5,14 +5,11 @@ ## Human summary (read this first) - + ## Requirements