From 5ec509795c1c46815a8bb5ae00adf28ff9597fbd Mon Sep 17 00:00:00 2001
From: JeremyDev87 <soundbrokaz@kakao.com>
Date: Wed, 6 May 2026 23:25:04 +0900
Subject: [PATCH] =?UTF-8?q?docs(readme):=20audit=20=EC=8B=A0=ED=98=B8=20?=
 =?UTF-8?q?=EC=A0=95=EC=B1=85=EC=9D=84=20=EB=AC=B8=EC=84=9C=ED=99=94?=
 =?UTF-8?q?=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

README에 env secret heuristic, env config schema, tsconfig noise policy를 추가한다.

Closes #106
---
 README.en.md | 28 ++++++++++++++++++++++++++++
 README.md    | 28 ++++++++++++++++++++++++++++
 2 files changed, 56 insertions(+)

diff --git a/README.en.md b/README.en.md
index beb014c..aed1143 100644
--- a/README.en.md
+++ b/README.en.md
@@ -63,6 +63,34 @@ Current MVP auto-fixes:
 - Create `.env.example` from concrete `.env` files
 - Append missing keys to `.env.example`
 
+## Audit Signal Policy
+
+### Env contract
+
+Maximus treats contract files such as `.env.example` as shareable interfaces. The `env-example-secret` warning now considers both the key name and the value shape.
+
+- Keys such as `*_TOKEN`, `*_SECRET`, `*_PASSWORD`, `*_SERVICE_KEY`, `PRIVATE_KEY`, `*_API_KEY`, and `*_ACCESS_KEY` still warn when they contain non-placeholder values.
+- High-confidence secret value shapes still warn regardless of the key name, including `sk_live_`, `sk_test_`, `ghp_`, `github_pat_`, `xoxb-`, `xoxp-`, `xoxa-`, AWS `AKIA...`, Google `AIza...`, and private key blocks.
+- Public or config-like identifiers such as `NEXT_PUBLIC_*_CLIENT_ID`, URLs, repository names, labels, dates, percentages, and hours do not warn only because the value is long.
+- Blank values, `change-me`, `example`, `placeholder`, `your-*`, `localhost`, `127.0.0.1`, `true`, `false`, `0`, and `1` are treated as placeholders.
+
+Env keys that are missing locally but injected by CI or hosting can be declared in `maximus.config.json` or `.maximusrc.json`.
+
+```json
+{
+  "env": {
+    "ciInjectedKeys": ["GH_COLLECTOR_TOKEN"],
+    "optionalLocalKeys": ["NEXT_PUBLIC_OKTA_DOMAIN"]
+  }
+}
+```
+
+Both lists are exact keys excluded from `env-missing-concrete`. There is no glob or prefix matching contract, so write concrete key names instead of patterns such as `VERCEL_*`. Unknown config fields fail parsing instead of being ignored silently.
+
+### TypeScript config
+
+No-op excludes that only repeat TypeScript's default excluded directories, such as `exclude: ["node_modules"]`, are hidden from the default audit output. Non-default excludes that carry project intent, such as `generated/**/*.ts` or `dist/**/*.d.ts`, still produce the existing `Info` finding when they do not remove any included files. Warnings for `include` patterns that match no files are unchanged.
+
 ## Example Output
 
 ```text
diff --git a/README.md b/README.md
index f33a987..2d2dcef 100644
--- a/README.md
+++ b/README.md
@@ -63,6 +63,34 @@ npx @jeremyfellaz/maximus fix
 - `.env` 기반 `.env.example` 생성
 - `.env.example`에 누락된 키 추가
 
+## Audit Signal 정책
+
+### Env contract
+
+Maximus는 `.env.example` 같은 contract 파일을 공유 가능한 인터페이스로 취급합니다. `env-example-secret` 경고는 이제 key 이름과 value 형태를 함께 봅니다.
+
+- `*_TOKEN`, `*_SECRET`, `*_PASSWORD`, `*_SERVICE_KEY`, `PRIVATE_KEY`, `*_API_KEY`, `*_ACCESS_KEY` 계열 key에 placeholder가 아닌 값이 들어 있으면 계속 경고합니다.
+- `sk_live_`, `sk_test_`, `ghp_`, `github_pat_`, `xoxb-`, `xoxp-`, `xoxa-`, AWS `AKIA...`, Google `AIza...`, private key block처럼 secret 가능성이 높은 value 형태는 key 이름과 관계없이 경고합니다.
+- `NEXT_PUBLIC_*_CLIENT_ID`, URL, repo 이름, label, date, percent, hour처럼 public/config 식별자 성격이 강한 key는 값이 길다는 이유만으로 경고하지 않습니다.
+- 빈 값, `change-me`, `example`, `placeholder`, `your-*`, `localhost`, `127.0.0.1`, `true`, `false`, `0`, `1`은 placeholder로 취급합니다.
+
+로컬에는 없지만 CI나 hosting에서 주입되는 env key는 `maximus.config.json` 또는 `.maximusrc.json`에서 명시할 수 있습니다.
+
+```json
+{
+  "env": {
+    "ciInjectedKeys": ["GH_COLLECTOR_TOKEN"],
+    "optionalLocalKeys": ["NEXT_PUBLIC_OKTA_DOMAIN"]
+  }
+}
+```
+
+두 목록은 `env-missing-concrete`에서 제외할 exact key 목록입니다. Glob나 prefix matching 계약은 없으므로 `VERCEL_*` 같은 패턴 대신 실제 key 이름을 넣으세요. 잘못된 config field는 조용히 무시하지 않고 parse error로 처리됩니다.
+
+### TypeScript config
+
+`exclude: ["node_modules"]`처럼 TypeScript의 기본 제외 디렉터리를 반복하는 no-op exclude는 기본 audit 출력에서 숨깁니다. 반면 `generated/**/*.ts`, `dist/**/*.d.ts`처럼 팀 의도가 담긴 non-default exclude가 실제 included file을 제거하지 못하면 기존처럼 `Info` finding을 유지합니다. `include` pattern이 아무 파일도 매칭하지 않는 경우의 warning도 그대로 유지됩니다.
+
 ## 예시 출력
 
 ```text