From e7ec875eba6c2c967afc9034c1c06c0cdc014bae Mon Sep 17 00:00:00 2001 From: cskwork <76669236+cskwork@users.noreply.github.com> Date: Mon, 12 Oct 2026 13:32:49 +0900 Subject: [PATCH 1/2] docs: show every way back in the loop (README diagram, site SVG) Readers could not see where work returns: the phase list read one way, the build review loop was only "three FAILs stop", and QA routing lived in a table after Evidence. - README.md, README.ko.md: a mermaid flowchart with the plan gap-check loop, the build review loop, Evidence back to Plan (plan wrong or the same failure twice) and to Build (code failed), and the deliver and human exits; the phase table now says when each phase goes back. - docs/index.html: an inline SVG of the same loop with translated labels and an accessible name replaces the routing table; the Build and Evidence cards say where failures go. The loop section is 64-154 px shorter in every view; i18n keys match both ways. --- README.ko.md | 42 +++++----- README.md | 41 ++++++---- docs/index.html | 205 ++++++++++++++++++++++++++---------------------- 3 files changed, 161 insertions(+), 127 deletions(-) diff --git a/README.ko.md b/README.ko.md index fccf431..b51eaf2 100644 --- a/README.ko.md +++ b/README.ko.md @@ -30,24 +30,30 @@ Intent → Plan → Build → Evidence. 코드를 쓰기 전에는 여러 탐색 ## 루프 -| # | 단계 | 하는 일 | 끝나는 시점 | -|---|---|---|---| -| 1 | **Intent** | 요청한 것, 에이전트가 이해한 것, 그 이해에 숨은 위험을 적습니다. 사람이 확인합니다. | intent 승인 | -| 2 | **Plan** | 여러 scout가 나란히 정본·데이터·로직·사용자 흐름을 조사해 `refs/`에 남깁니다. `PLAN.md` 한 장에 AS-IS → TO-BE, 부작용, QA가 돌릴 시나리오를 담습니다. | plan 승인 | -| 3 | **Build** | 가장 작은 완전한 변경을 만들고, 별도 리뷰어가 공격적으로 검토합니다. FAIL이 세 번이면 멈춥니다. | 리뷰 PASS | -| 4 | **Evidence** | 통합·E2E 검사 뒤, 모든 시나리오를 각 페르소나로 실제 인터페이스에서 돌립니다. 점수와 다음 경로는 스크립트가 정합니다. | 납품 | - -**Evidence 뒤 라우팅**은 에이전트 판단이 아니라 `sdlc.sh score`가 계산합니다. - -1. 계획 때문에 생긴 실패, 또는 같은 코드 실패의 반복 → **Plan**으로 -2. must 시나리오가 전부 통과하고 전체의 95% 이상 통과 → **납품** -3. 환경이 없어 시나리오를 못 돌렸고, 그 때문에 납품이 막힘 → **사람**에게 -4. 나머지 → **Build**로 - -되돌아가는 횟수는 경로마다 세 번까지이고, 넘으면 사람이 정합니다. 루프는 -`sdlc.sh approve plan --human`으로만 다시 시작합니다. 못 돌린 시나리오는 실패로 -칩니다. 시나리오를 지우는 것은 사람만 할 수 있습니다. PASS에는 반드시 로그가 -붙어야 합니다. +```mermaid +flowchart LR + I["1 Intent"] -->|사람 승인| P["2 Plan"] + P -. 빈틈 발견 .-> P + P -->|계획 승인| B["3 Build"] + B -. 리뷰 FAIL: 고치고 다시 리뷰 .-> B + B -->|리뷰 PASS| E["4 Evidence"] + E -. 계획이 틀렸거나 같은 실패 반복 .-> P + E -. 코드 실패 .-> B + E -->|must 전부 통과, 전체 95% 이상| D(["납품"]) + E -->|돌릴 환경 없음| H(["사람이 결정"]) +``` + +| 단계 | 하는 일 | 되돌아가는 때 | +|---|---|---| +| **1 Intent** | 요청한 것, 에이전트가 이해한 것, 그 이해에 숨은 위험을 적습니다. 사람이 확인합니다. | — | +| **2 Plan** | 여러 scout가 나란히 정본·데이터·로직·사용자 흐름을 조사해 `refs/`에 남깁니다. `PLAN.md` 한 장에 AS-IS → TO-BE, 부작용, QA가 돌릴 시나리오를 담습니다. | 누락 점검에서 빈틈이 나올 때 | +| **3 Build** | 가장 작은 완전한 변경을 만들어 커밋하고, 별도 리뷰어가 공격적으로 검토합니다. | 리뷰 FAIL: 고치고 다시 리뷰 | +| **4 Evidence** | 실제 검사 뒤, 모든 시나리오를 각 페르소나로 실제 인터페이스에서 돌립니다. 점수와 다음 경로는 에이전트가 아니라 `sdlc.sh score`가 정합니다. | 계획이 틀렸거나 같은 실패 반복 → Plan, 코드 실패 → Build | + +되돌아가는 횟수는 리뷰 FAIL, Plan 복귀, Build 복귀마다 세 번까지입니다. 넘으면 +루프가 멈추고 사람이 정하며, `sdlc.sh approve plan --human`으로만 다시 시작합니다. +못 돌린 시나리오는 실패로 칩니다. 시나리오를 지우는 것은 사람만 할 수 있고, +PASS에는 반드시 로그가 붙어야 합니다. ## 빠른 시작 diff --git a/README.md b/README.md index b5cb542..2d88bce 100644 --- a/README.md +++ b/README.md @@ -30,23 +30,30 @@ and needs no particular harness: it is Markdown plus one shell script. ## The loop -| # | Phase | What happens | Leaves when | -|---|---|---|---| -| 1 | **Intent** | What you asked, what the agent understood, and the risks in that understanding. You confirm it. | intent approved | -| 2 | **Plan** | Parallel scouts map source of truth, data, logic and user flow into `refs/`; one `PLAN.md` holds AS-IS → TO-BE, side effects and the scenarios QA will run. | plan approved | -| 3 | **Build** | The smallest complete change, then a separate adversarial reviewer. Three FAILs stop the loop. | review PASS | -| 4 | **Evidence** | Integration and E2E checks, then every scenario run as its persona through the real interface. A script scores it and routes it. | delivered | - -**Routing after Evidence** — computed by `sdlc.sh score`, not judged by the agent: - -1. a failure the plan caused, or the same code failure twice → back to **Plan** -2. every must scenario passes and ≥ 95% of all scenarios pass → **deliver** -3. scenarios could not run (no environment) and that is what blocks delivery → **the human** -4. otherwise → back to **Build** - -Each kind of return is capped at three; then the human decides, and only -`sdlc.sh approve plan --human` resumes the loop. A scenario that could not run -counts as failed, only you can remove a scenario, and every PASS needs its log. +```mermaid +flowchart LR + I["1 Intent"] -->|you approve| P["2 Plan"] + P -. gap found .-> P + P -->|plan approved| B["3 Build"] + B -. FAIL: fix, re-review .-> B + B -->|review PASS| E["4 Evidence"] + E -. plan was wrong, or same failure twice .-> P + E -. code failed .-> B + E -->|every must passes, 95%+ overall| D(["deliver"]) + E -->|no environment to run it| H(["you decide"]) +``` + +| Phase | What happens | Goes back when | +|---|---|---| +| **1 Intent** | What you asked, what the agent understood, and the risks in it. You confirm it. | — | +| **2 Plan** | Parallel scouts map source of truth, data, logic and user flow into `refs/`; one `PLAN.md` holds AS-IS → TO-BE, side effects and the scenarios QA will run. | the gap check finds holes | +| **3 Build** | The smallest complete change, committed, then a separate adversarial reviewer. | the review FAILs: fix it, review again | +| **4 Evidence** | Real checks, then every scenario as its persona through the real interface. `sdlc.sh score` scores and routes it; the agent does not judge. | the plan was wrong or the same failure came twice → Plan; code failed → Build | + +Every way back is capped at three — three review FAILs, three returns to Plan, +three to Build — then the loop stops for you, and only +`sdlc.sh approve plan --human` resumes it. A scenario that could not run counts +as failed, only you can remove a scenario, and every PASS needs its log. ## Quick start diff --git a/docs/index.html b/docs/index.html index 501b0fd..70595f2 100644 --- a/docs/index.html +++ b/docs/index.html @@ -131,7 +131,28 @@ .band-alt { background: linear-gradient(rgba(255, 251, 240, 0.016), rgba(255, 251, 240, 0.016)); } /* ---------- the loop ---------- */ - .flow { list-style: none; margin: 0 0 2.75rem; padding: 0; display: flex; flex-direction: column; gap: 0.55rem; } + .loopmap { display: grid; gap: 2rem; align-items: start; } + .loopmap > * { min-width: 0; } + @media (min-width: 900px) { .loopmap { grid-template-columns: minmax(0, 30rem) 1fr; gap: 3rem; } } + .loopsvg { display: block; width: 100%; max-width: 30rem; height: auto; margin-inline: auto; } + .loopsvg .box rect { fill: var(--bg-raised); stroke: var(--line-strong); stroke-width: 1.2; } + .loopsvg .box text { font: 600 16px var(--slab); fill: var(--text); text-anchor: middle; } + .loopsvg path { fill: none; stroke-width: 1.6; stroke-linecap: round; stroke-linejoin: round; } + .loopsvg .go path { stroke: var(--accent); marker-end: url(#ah-go); } + .loopsvg .back path { stroke: var(--danger); stroke-dasharray: 5 4; marker-end: url(#ah-back); } + .loopsvg .trunk { stroke: var(--line-strong); } + .loopsvg .stop { stroke: var(--text-2); marker-end: url(#ah-out); } + .loopsvg .mk-go { fill: var(--accent); } + .loopsvg .mk-back { fill: var(--danger); } + .loopsvg .mk-out { fill: var(--text-2); } + .loopsvg .dots circle { fill: var(--line-strong); } + .loopsvg .pill { fill: none; stroke: var(--text-2); stroke-width: 1.2; } + .loopsvg .pill.done { fill: var(--accent); stroke: var(--accent); } + .loopsvg .pill-t { font: 600 13px var(--sans); fill: var(--text); text-anchor: middle; } + .loopsvg .pill-t.done { fill: var(--accent-ink); } + .loopsvg .lbl text { font: 400 13.5px var(--sans); fill: var(--text-2); } + .loopsvg .lbl.end text { text-anchor: end; } + .flow { list-style: none; margin: 0; padding: 0; display: grid; gap: 0.75rem; } .flow .stage { background: var(--bg-raised); border: 1px solid var(--line); border-radius: 10px; padding: 1rem 1.15rem 1.1rem; } .flow h3 { margin: 0 0 0.3rem; font-size: 1.08rem; display: flex; align-items: baseline; gap: 0.6rem; flex-wrap: wrap; } .flow h3 .art { @@ -140,36 +161,8 @@ padding: 0.14rem 0.5rem; border-radius: 99px; letter-spacing: 0; } .flow .what { margin: 0; color: var(--text-2); font-size: 0.86rem; line-height: 1.55; } - .flow .edge { display: flex; flex-direction: column; align-items: center; gap: 0.3rem; padding-block: 0.15rem; } - .flow .edge .lbl { - font-family: var(--mono); font-size: 0.66rem; letter-spacing: 0.02em; text-align: center; - color: var(--text-2); border: 1px dashed var(--line-strong); border-radius: 99px; padding: 0.2rem 0.7rem; - } - .flow .edge.gate .lbl { color: var(--accent); border-color: rgba(234, 176, 77, 0.45); } - .flow .edge svg { color: var(--line-strong); } - .flow .edge.gate svg { color: var(--accent); } - .loopnote { margin: 1rem 0 0; max-width: 62ch; color: var(--text-2); font-size: 0.86rem; } + .loopnote { margin: 1.5rem 0 0; max-width: 62ch; color: var(--text-2); font-size: 0.86rem; } .loopnote b { color: var(--text); font-weight: 600; } - @media (min-width: 900px) { - .flow { - display: grid; gap: 1.1rem 0.5rem; align-items: stretch; - grid-template-columns: 1fr 5.2rem 1fr; - grid-template-areas: "s1 e12 s2" ". . e23" "s4 e34 s3"; - } - .s1 { grid-area: s1; } .s2 { grid-area: s2; } .s3 { grid-area: s3; } .s4 { grid-area: s4; } - .e12 { grid-area: e12; } .e23 { grid-area: e23; } .e34 { grid-area: e34; } - .flow .edge { justify-content: center; } - } - @media (max-width: 899.98px) { .flow .edge .d { display: none; } } - - /* ---------- routing table ---------- */ - .tablewrap { overflow-x: auto; } - table.how { width: 100%; border-collapse: collapse; font-size: 0.9rem; } - table.how caption { text-align: left; font-family: var(--slab); font-weight: 600; font-size: 1.12rem; padding-bottom: 0.8rem; } - table.how th, table.how td { text-align: left; padding: 0.75rem 1rem 0.75rem 0; border-top: 1px solid var(--line); vertical-align: top; } - table.how thead th { font-family: var(--mono); font-size: 0.7rem; font-weight: 500; text-transform: uppercase; letter-spacing: 0.08em; color: var(--text-2); } - table.how tbody th { font-weight: 600; white-space: nowrap; font-family: var(--mono); font-size: 0.84rem; } - table.how td { color: var(--text-2); } /* ---------- what you get (ledger) ---------- */ .ledger { margin: 0; border-bottom: 1px solid var(--line); } @@ -249,54 +242,77 @@

sdlc-kit

Four phases, with checkpoints between them

-

Each phase writes down what it found or did, and the next one starts only when its checkpoint opens. By default a person confirms the request. A plan with a risk flag also waits for a person, and you can choose to approve every plan yourself.

+

Each phase writes down what it did, and the next one starts only when its checkpoint opens. The red arrows show where work goes back when something fails.

-
    -
  1. -

    1 · Intent what you asked

    -

    The AI writes down what you asked, what it understood, and the risks in that understanding. It asks only the questions whose answers would change what gets built.

    -
    2. -
  2. - - checkpoint · a person confirms -
    3. -
  3. -

    2 · Plan one plan page

    -

    Several helper AIs explore at the same time: the rules that decide the behaviour, the data, the logic, and how users reach it today. Each writes notes. One plan page holds before and after, side effects, and the scenarios that will be tested. A separate AI checks it for gaps.

    -
    4. -
  4. - - risk flag · a person approves -
    5. -
  5. -

    3 · Build the smallest complete change

    -

    The AI makes the smallest change that fully does what the plan says. A separate AI then reviews it, assuming it is wrong. After three failed reviews the work stops for a person.

    -
    6. -
  6. - - review passes · goes on -
    7. -
  7. -

    4 · Evidence scored proof

    -

    The project's real checks run first. Then every scenario is played as its user, through the same screens and commands that user really works with. A script scores the result, so the AI cannot grade its own work.

    -
    8. -
+
+ + + + + + + + 1 · Intent + 2 · Plan + 3 · Build + 4 · Evidence + + + + + + + + + + + + + + Deliver + A person + + checkpoint · a person confirms + plan approved + risk flag · a person approves + review passes · goes on + plan wrong or incomplete, + or the same failure twice + all must-pass scenarios passed, + and at least 95% of all + no place to run scenarios, + and that blocks delivery + + + gaps found: + 1–2 rounds + review fails: + fix, review again + anything else: + the change failed + + -
- - - - - - - - - - - -
After Evidence, the score decides where the work goes
Goes toWhen
PlanThe plan was wrong or missed something, or the same failure happened twice.
DeliverEvery must-pass scenario passed, and at least 95% of all scenarios passed.
A personScenarios could not be run, because there was nowhere to run them, and that is what stops delivery.
BuildAnything else.
+
    +
  1. +

    1 · Intent what you asked

    +

    The AI writes down what you asked, what it understood, and the risks in that understanding. It asks only the questions whose answers would change what gets built.

    +
    2. +
  2. +

    2 · Plan one plan page

    +

    Helper AIs explore the rules, the data, the logic and how users reach it today. One plan page holds before and after, side effects and the scenarios to test. A separate AI checks it for gaps.

    +
    3. +
  3. +

    3 · Build the smallest complete change

    +

    The AI makes the smallest change that fully does what the plan says. A separate AI reviews it, assuming it is wrong. A failed review sends it back to be fixed and reviewed again; after three failures the work stops for a person.

    +
    4. +
  4. +

    4 · Evidence scored proof

    +

    The project's real checks run first, then every scenario is played as its user. A script scores the result, so the AI cannot grade its own work. Failures go back to Plan or Build, depending on the cause.

    +
    5. +
-

The rules are checked in this order. Each kind of return happens at most three times, then a person decides. A scenario that could not run counts as failed, and only a person can remove a scenario.

+

The score is checked from top to bottom. Each kind of return happens at most three times, then a person decides. A scenario that could not run counts as failed, and only a person can remove a scenario.

@@ -404,34 +420,38 @@

For the person who sets it up

"t6": '통과. 두 번째 검토입니다.', "t7": '8개 중 8개 통과. 납품합니다.', "loop-h": '네 단계와 그 사이의 확인 지점', - "loop-lede": '각 단계는 알아낸 것이나 한 일을 글로 남기고, 다음 단계는 확인 지점이 열려야 시작합니다. 기본 설정에서는 사람이 요청 내용을 확인합니다. 위험 표시가 붙은 계획도 사람을 기다리며, 원하면 모든 계획을 직접 승인할 수 있습니다.', + "loop-lede": '각 단계는 한 일을 글로 남기고, 다음 단계는 확인 지점이 열려야 시작합니다. 빨간 화살표는 무언가 실패했을 때 작업이 되돌아가는 곳입니다.', "s1-h": '1 · 의도', "s1-a": '요청한 것', "s1-p": 'AI가 요청한 내용, 자신이 이해한 내용, 그 이해에 숨은 위험을 글로 적습니다. 답에 따라 만들 것이 달라지는 질문만 묻습니다.', "e12": '확인 지점 · 사람이 확인', "s2-h": '2 · 계획', "s2-a": '계획 한 장', - "s2-p": '여러 보조 AI가 동시에 조사합니다. 동작을 정하는 규칙, 데이터, 처리 흐름, 사용자가 지금 그 기능에 닿는 경로를 살피고 각자 기록을 남깁니다. 계획 한 장에 바뀌기 전과 후, 부작용, 시험할 시나리오를 담고, 다른 AI가 빠진 곳을 찾습니다.', + "s2-p": '보조 AI들이 규칙, 데이터, 처리 흐름, 사용자가 지금 그 기능에 닿는 경로를 조사합니다. 계획 한 장에 바뀌기 전과 후, 부작용, 시험할 시나리오를 담고, 다른 AI가 빠진 곳을 찾습니다.', + "d-ok2": '계획 승인', "e23": '위험 표시 · 사람이 승인', "s3-h": '3 · 만들기', "s3-a": '가장 작은 완전한 변경', - "s3-p": '계획이 말하는 일을 빠짐없이 해내는 가장 작은 변경을 만듭니다. 이어서 다른 AI가 틀렸다고 가정하고 검토합니다. 검토에서 세 번 떨어지면 작업을 멈추고 사람에게 넘깁니다.', + "s3-p": '계획이 말하는 일을 빠짐없이 해내는 가장 작은 변경을 만듭니다. 이어서 다른 AI가 틀렸다고 가정하고 검토합니다. 검토에서 떨어지면 고친 뒤 다시 검토받고, 세 번 떨어지면 작업을 멈추고 사람에게 넘깁니다.', "e34": '검토 통과 · 다음으로', "s4-h": '4 · 검증', "s4-a": '점수가 매겨진 증거', - "s4-p": '먼저 프로젝트의 실제 점검을 돌립니다. 그다음 모든 시나리오를 그 사용자가 되어, 사용자가 실제로 쓰는 화면과 명령으로 해 봅니다. 결과는 스크립트가 채점하므로 AI가 스스로 채점할 수 없습니다.', - "rt-cap": '검증이 끝나면 점수가 다음 행선지를 정합니다', - "rt-h1": '다음 단계', - "rt-h2": '조건', - "rt1-to": '계획', - "rt1": '계획이 틀렸거나 무언가를 놓쳤을 때, 또는 같은 실패가 두 번 났을 때', - "rt2-to": '납품', - "rt2": '반드시 통과해야 할 시나리오가 모두 통과하고, 전체 시나리오의 95% 이상이 통과했을 때', - "rt3-to": '사람', - "rt3": '돌려 볼 환경이 없어 시나리오를 실행하지 못했고, 그 때문에 납품할 수 없을 때', - "rt4-to": '만들기', - "rt4": '그 밖의 모든 경우', - "loopnote": '조건은 위에서부터 차례로 따집니다. 같은 종류의 되돌아가기는 최대 세 번이며, 그 뒤에는 사람이 정합니다. 실행하지 못한 시나리오는 실패로 치고, 시나리오를 지우는 것은 사람만 할 수 있습니다.', + "s4-p": '먼저 프로젝트의 실제 점검을 돌리고, 모든 시나리오를 그 사용자가 되어 해 봅니다. 결과는 스크립트가 채점하므로 AI가 스스로 채점할 수 없습니다. 실패하면 원인에 따라 계획이나 만들기로 돌아갑니다.', + "d-gap1": '빈틈이 있으면', + "d-gap2": '1~2회 보완', + "d-fail1": '검토 불합격', + "d-fail2": '고쳐서 재검토', + "d-a1": '계획이 틀렸거나 빠졌을 때,', + "d-a2": '또는 같은 실패가 두 번 났을 때', + "d-b1": '필수 시나리오가 모두 통과하고', + "d-b2": '전체의 95% 이상이 통과', + "d-c1": '시나리오를 돌릴 환경이 없어', + "d-c2": '납품할 수 없을 때', + "d-d1": '그 밖의 경우:', + "d-d2": '만든 변경의 실패', + "d-deliver": '납품', + "d-person": '사람', + "loopnote": '점수는 위에서부터 차례로 따집니다. 같은 종류의 되돌아가기는 최대 세 번이며, 그 뒤에는 사람이 정합니다. 실행하지 못한 시나리오는 실패로 치고, 시나리오를 지우는 것은 사람만 할 수 있습니다.', "why-h": '달라지는 점', "why-lede": 'AI는 모든 단계에서 같은 규칙을 따릅니다. 그래서 다음이 달라집니다.', "g1-t": '중요한 것은 사람이 확인합니다', @@ -458,7 +478,8 @@

For the person who sets it up

var KO_ARIA = { "hero-aria": 'sdlc-kit 소개', "term-aria": '대화 예시: 사람이 요청을 확인하고, 다른 AI가 작업을 검토하고, 점수가 납품을 정합니다.', - "flow-aria": '네 단계와 그 사이의 확인 지점', + "loop-aria": '작업 순환도. 1 의도는 사람이 승인하면 2 계획으로 갑니다. 계획은 승인되면 3 만들기로 가며, 위험 표시가 있으면 사람이 승인합니다. 빈틈이 발견되면 계획을 1~2회 보완합니다. 만들기는 검토를 통과하면 4 검증으로 가고, 검토에서 떨어지면 고쳐서 다시 검토받습니다. 검증은 점수를 다음 순서로 따집니다. 계획이 틀렸거나 빠졌을 때, 또는 같은 실패가 두 번 났을 때는 계획으로 돌아갑니다. 필수 시나리오가 모두 통과하고 전체의 95% 이상이 통과하면 납품합니다. 시나리오를 돌릴 환경이 없어 납품할 수 없으면 사람에게 넘깁니다. 그 밖의 경우는 만들기로 돌아갑니다. 같은 종류의 되돌아가기는 최대 세 번이며, 그 뒤에는 사람이 정합니다.', + "flow-aria": '네 단계', "foot-aria": '바닥글' }; var enText = new WeakMap(); From d0bff1fc18a62183f9c274e764e56281dcac86e1 Mon Sep 17 00:00:00 2001 From: cskwork <76669236+cskwork@users.noreply.github.com> Date: Mon, 12 Oct 2026 13:39:52 +0900 Subject: [PATCH 2/2] feat: carry policies through the loop (v2.1.0) - PLAN.md AS-IS -> TO-BE gains a Policy column (where it is written, with version | code | unknown); behavior that must not change is a row whose TO-BE is "unchanged", with a scenario. - Intent risks name a policy the request would change and its owner. - Delivery: a changed policy is updated where it is written in the same delivery, or evidence.md's Delivery records the follow-up and owner on a "Policy:" line; the diff reviewer blocks a policy change with neither. - The source scout reads "policies and canonical docs". No script change. Prompts and templates: 4,026 words; heaviest phase 2,132. --- VERSION | 2 +- log/changelog-v2.1.0.md | 23 +++++++++++++++++++++++ phases/1-intent.md | 3 ++- phases/2-plan.md | 6 ++++-- phases/4-evidence.md | 4 +++- roles/reviewer.md | 2 ++ templates/PLAN.md | 6 +++--- templates/evidence.md | 1 + templates/intent.md | 2 +- 9 files changed, 40 insertions(+), 9 deletions(-) create mode 100644 log/changelog-v2.1.0.md diff --git a/VERSION b/VERSION index 227cea2..7ec1d6d 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -2.0.0 +2.1.0 diff --git a/log/changelog-v2.1.0.md b/log/changelog-v2.1.0.md new file mode 100644 index 0000000..783ccc9 --- /dev/null +++ b/log/changelog-v2.1.0.md @@ -0,0 +1,23 @@ +# v2.1.0 — policies through the loop, every way back on the page + +Policies now travel with the work from Intent to delivery, and readers can +see where work goes back. + +## Changes + +- **Policy column.** PLAN.md's AS-IS → TO-BE table names the policy behind + each behavior: where it is written, with its version, or `code` or + `unknown`. Behavior that must not change is a row whose TO-BE is + `unchanged`, with a scenario. +- **Policy owner in Intent.** Risks name a policy the request would change + and who owns it. +- **Policy at delivery.** A changed policy is updated where it is written in + the same delivery, or evidence.md's Delivery records the follow-up and its + owner on a `Policy:` line. The reviewer blocks a policy change that has + neither. +- **Loops shown.** The README (English and Korean) has a diagram of every way + back: the plan gap check, a build review FAIL, and Evidence returning to + Plan or Build. The site's loop section draws the same loop in place of the + routing table. + +No script change; existing records stay valid. diff --git a/phases/1-intent.md b/phases/1-intent.md index fb99fa8..730816a 100644 --- a/phases/1-intent.md +++ b/phases/1-intent.md @@ -13,7 +13,8 @@ risks in that understanding — confirmed before anyone explores deeply. - **Understood as** — the outcome, what is in and out of scope, and success criteria `O1..On`, each observable so a scenario can check it. - **Risks in this intent** — ambiguity, a claim the code or data already - contradicts (with the evidence), work that needs authority (rule 3). + contradicts (with the evidence), a policy the request would change and + who owns it, work that needs authority (rule 3). - **Blocking questions** — only those whose wrong answer changes what gets built or leaves the authorized scope. Ask them one at a time and record each answer in place as `— resolved: `. Other diff --git a/phases/2-plan.md b/phases/2-plan.md index 6a4afa0..fa56cf0 100644 --- a/phases/2-plan.md +++ b/phases/2-plan.md @@ -13,7 +13,7 @@ writing one file in `refs/`: | Scout | File | Answers | |---|---|---| -| source | `refs/source.md` | the request's text, the canonical rules and docs it touches, earlier attempts and reverts and why | +| source | `refs/source.md` | the request's text, the policies and canonical docs it touches, earlier attempts and reverts and why | | data | `refs/data.md` | data models and fields, who writes and reads each, the states existing records are in | | logic | `refs/logic.md` | entry points, call chains, every caller in every tier and repository the change crosses, shared code | | flow | `refs/flow.md` | how each persona reaches the behavior today, observed by running it, with the result | @@ -30,7 +30,9 @@ Fill `templates/PLAN.md`, 150 lines at most. It summarizes; refs hold the evidence. Link, do not copy. - **Understanding** — a few lines each on data, logic, source of truth and user flow, each with its ref. -- **AS-IS → TO-BE** — every behavior before and after; AS-IS as observed. +- **AS-IS → TO-BE** — every behavior before and after, with the policy that + sets it; AS-IS as observed. Behavior that must not change is a row whose + TO-BE is `unchanged`, with a scenario. - **Side effects** — every other reader or writer of the touched data, every caller that sends today's shapes (missing, empty, null, old values), records made before the change, shared code — each with how it stays diff --git a/phases/4-evidence.md b/phases/4-evidence.md index 350bdf8..1c9955b 100644 --- a/phases/4-evidence.md +++ b/phases/4-evidence.md @@ -40,7 +40,9 @@ Deliver the verified commit by the project's rules and intent.md's target: intent.md or, for a later or different target, in evidence.md's Delivery as `Authorized: yes — ""`. Do not change code after scoring. Fill evidence.md's Delivery: target, delivered commit per repository, the command -that checked it and its deciding output line. Then: +that checked it and its deciding output line. A changed policy is updated +where it is written in the same delivery, or its follow-up and owner go in +Delivery's `Policy:` line. Then: - move verified facts from the refs (and `refs/learnings.md`, if any) into `knowledge`: one place per fact, updating a page rather than adding a duplicate; diff --git a/roles/reviewer.md b/roles/reviewer.md index 726f964..20f5763 100644 --- a/roles/reviewer.md +++ b/roles/reviewer.md @@ -18,6 +18,8 @@ Blocking: - it does not do what PLAN.md says, or does more; - a side effect PLAN.md names is left unhandled; input that callers send today is newly refused without intent.md authorizing it; +- a policy changed with neither an update where it is written nor a + recorded follow-up; - a masked symptom: a catch that logs and continues, a default that hides a missing value; - security: injection, missing authorization, secrets in code, unsafe diff --git a/templates/PLAN.md b/templates/PLAN.md index bea7e81..e6314bf 100644 --- a/templates/PLAN.md +++ b/templates/PLAN.md @@ -10,9 +10,9 @@ - User flow: <…> (refs/flow.md) ## AS-IS → TO-BE -| Behavior | AS-IS (observed) | TO-BE | -|---|---|---| -| <…> | <…> | <…> | +| Behavior | Policy | AS-IS (observed) | TO-BE | +|---|---|---|---| +| <…> | | <…> | <… | unchanged> | ## Side effects - → () diff --git a/templates/evidence.md b/templates/evidence.md index bcdf28c..5b72843 100644 --- a/templates/evidence.md +++ b/templates/evidence.md @@ -23,3 +23,4 @@ - Checked with: - Output: - Authorized: +- Policy: | follow-up | unchanged> diff --git a/templates/intent.md b/templates/intent.md index 3136971..285ffd7 100644 --- a/templates/intent.md +++ b/templates/intent.md @@ -14,7 +14,7 @@ - O1: ## Risks in this intent -- +- ## Blocking questions - none