From 8ad1fe03fcf5582edad6b73b8a0b83e8e7fab9cd Mon Sep 17 00:00:00 2001 From: Jeongwook Park Date: Fri, 3 Jul 2026 15:51:49 +0900 Subject: [PATCH 1/3] =?UTF-8?q?docs(references):=20wiki-growth-triage?= =?UTF-8?q?=EC=97=90=20=EB=A9=B1=EB=93=B1=20=EC=93=B0=EA=B8=B0=C2=B7?= =?UTF-8?q?=EC=A7=80=EC=8B=9D=20=EA=B0=90=EC=82=AC=20=EC=A0=88=EC=B0=A8=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 재관찰된 지식의 upsert 멱등성(의미 기준 동일성, 같은 출처 무변경, 승격/폐기 이력 재적립 금지, 사후 중복은 병합)과 지식 표면 전수 감사 9종 검사(보고→승인→일괄수정 2단계)를 wiki-growth-triage에 추가한다. 추가분이 retro/setwiki 예산을 초과해 4키를 ceiling 내에서 재조정한다. Co-Authored-By: Claude Fable 5 Ultraworked-With: claude-fable-5 User-Request: PR 관찰에서 검증된 지식 거버넌스 패턴을 ddalggak에 흡수 (멱등 CRUD·감사) --- .../ddalggak/references/wiki-growth-triage.md | 25 +++++++++++++++++++ core/token-budgets.yaml | 8 +++--- ddalggak/references/wiki-growth-triage.md | 25 +++++++++++++++++++ 3 files changed, 54 insertions(+), 4 deletions(-) diff --git a/.codex/skills/ddalggak/references/wiki-growth-triage.md b/.codex/skills/ddalggak/references/wiki-growth-triage.md index eefc5cf..2cb1a57 100644 --- a/.codex/skills/ddalggak/references/wiki-growth-triage.md +++ b/.codex/skills/ddalggak/references/wiki-growth-triage.md @@ -46,6 +46,31 @@ Before promoting wiki-derived knowledge into ddalggak, verify: - The change does not create hidden runtime machinery, scheduler mutation, or durable state storage unless explicitly requested and separately scoped. - The change includes validation evidence appropriate to the touched surface: `npm run verify:codex-skill`, `npm test`, package dry-run, `git diff --check`, or a specific not-applicable reason. +## Idempotent knowledge writes + +Re-observing an already-recorded lesson is the normal case, not an error. Durable-surface writes (wiki proposals, references, templates, regression-library entries) must stay idempotent against it: + +- Identity is semantic, not path- or title-based: before writing, read the neighboring entries and compare meaning. +- Re-observation is an upsert: add the new evidence source to the existing entry instead of creating a sibling entry. If the same source is already recorded, make no change. +- Do not re-add knowledge that was already promoted or deprecated; if it recurs, cite the prior decision and propose raising its promotion strength instead. +- Repair duplicates that slipped past judgment by merging, not blocking: consolidate evidence into the better-distilled entry and deprecate the other with the merge reason recorded. The goal is bounded duplication with cheap recovery, not zero duplication. + +Pattern provenance: distilled from field observation of an OKF-style repo-local agent knowledge-bundle workflow (Open Knowledge Format v0.1 governance). + +## Knowledge audit mode + +When asked to audit or clean a durable knowledge surface, run report → approval → batch fix. Never fix silently while auditing. Report at minimum: + +1. Orphan entries that no other document links to (indexes excluded). +2. Broken internal links; external URLs are out of scope. +3. Mentioned-but-unlinked entries: another entry's subject named in prose without a link. +4. Missing or undefined required metadata, such as admission header fields. +5. Index ↔ file mismatches, checked in both directions. +6. Contradictions between entries on the same topic — report for human decision; never auto-merge content conflicts. +7. Stale entries past a declared freshness threshold, when the surface declares one. +8. Tag or vocabulary drift from the established set. +9. Duplicate suspects, routed to the merge rule in Idempotent knowledge writes. + ## Worked examples | Input knowledge | Classification | Why | diff --git a/core/token-budgets.yaml b/core/token-budgets.yaml index 52ede62..190996c 100644 --- a/core/token-budgets.yaml +++ b/core/token-budgets.yaml @@ -27,14 +27,14 @@ subcommand_token_budgets: issue: 10000 clean: 9500 ship: 10000 - retro: 14000 + retro: 14500 prompt: 12500 tune: 11000 forge: 11000 spark: 11000 check: 9500 getwiki: 11500 - setwiki: 13000 + setwiki: 13500 ulw-loop: 14000 ulw-plan: 13000 ulw-research: 11000 @@ -49,14 +49,14 @@ subcommand_token_budgets: issue: 10500 clean: 10000 ship: 10500 - retro: 12500 + retro: 13500 prompt: 12500 tune: 12000 forge: 12000 spark: 12000 check: 10000 getwiki: 12000 - setwiki: 13500 + setwiki: 14000 ulw-loop: 15000 ulw-plan: 14000 ulw-research: 12000 diff --git a/ddalggak/references/wiki-growth-triage.md b/ddalggak/references/wiki-growth-triage.md index eefc5cf..2cb1a57 100644 --- a/ddalggak/references/wiki-growth-triage.md +++ b/ddalggak/references/wiki-growth-triage.md @@ -46,6 +46,31 @@ Before promoting wiki-derived knowledge into ddalggak, verify: - The change does not create hidden runtime machinery, scheduler mutation, or durable state storage unless explicitly requested and separately scoped. - The change includes validation evidence appropriate to the touched surface: `npm run verify:codex-skill`, `npm test`, package dry-run, `git diff --check`, or a specific not-applicable reason. +## Idempotent knowledge writes + +Re-observing an already-recorded lesson is the normal case, not an error. Durable-surface writes (wiki proposals, references, templates, regression-library entries) must stay idempotent against it: + +- Identity is semantic, not path- or title-based: before writing, read the neighboring entries and compare meaning. +- Re-observation is an upsert: add the new evidence source to the existing entry instead of creating a sibling entry. If the same source is already recorded, make no change. +- Do not re-add knowledge that was already promoted or deprecated; if it recurs, cite the prior decision and propose raising its promotion strength instead. +- Repair duplicates that slipped past judgment by merging, not blocking: consolidate evidence into the better-distilled entry and deprecate the other with the merge reason recorded. The goal is bounded duplication with cheap recovery, not zero duplication. + +Pattern provenance: distilled from field observation of an OKF-style repo-local agent knowledge-bundle workflow (Open Knowledge Format v0.1 governance). + +## Knowledge audit mode + +When asked to audit or clean a durable knowledge surface, run report → approval → batch fix. Never fix silently while auditing. Report at minimum: + +1. Orphan entries that no other document links to (indexes excluded). +2. Broken internal links; external URLs are out of scope. +3. Mentioned-but-unlinked entries: another entry's subject named in prose without a link. +4. Missing or undefined required metadata, such as admission header fields. +5. Index ↔ file mismatches, checked in both directions. +6. Contradictions between entries on the same topic — report for human decision; never auto-merge content conflicts. +7. Stale entries past a declared freshness threshold, when the surface declares one. +8. Tag or vocabulary drift from the established set. +9. Duplicate suspects, routed to the merge rule in Idempotent knowledge writes. + ## Worked examples | Input knowledge | Classification | Why | From 06c4ab0584355aa8b4668835412afb64d92c8b8d Mon Sep 17 00:00:00 2001 From: Jeongwook Park Date: Fri, 3 Jul 2026 15:56:08 +0900 Subject: [PATCH 2/3] =?UTF-8?q?docs(references):=20=EC=A7=80=EC=8B=9D=20?= =?UTF-8?q?=EC=8B=A0=EC=84=A0=EB=8F=84=20=EA=B3=84=EC=95=BD=20reference=20?= =?UTF-8?q?=EC=8B=A0=EC=84=A4=20(on-demand=20=EB=A1=9C=EB=93=9C)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit durable 문서의 신선도 규칙(last-verified 의미, 종류별 stale 임계, 외부 증류물 upstream identity, co-change 검사)을 신규 reference로 추가한다. retro/setwiki 예산 재소모를 피해 required_references 배선 대신 wiki-growth-triage 감사 pointer 경유 on-demand 로드로 두고, parity ledger(must-match)와 예산 exemption(cap 800)에 등록한다. 기존 문서 소급 stamping은 비범위 — 별도 기계적 rollout의 몫이다. Co-Authored-By: Claude Fable 5 Ultraworked-With: claude-fable-5 User-Request: 신선도 계약은 규칙만 흡수 (소급 stamping 제외) --- .../knowledge-freshness-contract.md | 36 +++++++++++++++++++ .../ddalggak/references/wiki-growth-triage.md | 2 +- core/projections.yaml | 2 ++ core/token-budgets.yaml | 3 ++ .../knowledge-freshness-contract.md | 36 +++++++++++++++++++ ddalggak/references/wiki-growth-triage.md | 2 +- 6 files changed, 79 insertions(+), 2 deletions(-) create mode 100644 .codex/skills/ddalggak/references/knowledge-freshness-contract.md create mode 100644 ddalggak/references/knowledge-freshness-contract.md diff --git a/.codex/skills/ddalggak/references/knowledge-freshness-contract.md b/.codex/skills/ddalggak/references/knowledge-freshness-contract.md new file mode 100644 index 0000000..34cd741 --- /dev/null +++ b/.codex/skills/ddalggak/references/knowledge-freshness-contract.md @@ -0,0 +1,36 @@ +# Knowledge Freshness Contract +Use when: creating or editing a durable knowledge document (reference, template, wiki proposal), or judging whether an existing one is still current before citing it. +Required by: knowledge audit mode in `wiki-growth-triage.md`; freshness judgment before citing a durable document as current. +Side effects: none +Do not use when: the document is transient session output (a plan, research report, or review comment) that is not meant to stay durable. + +Durable documents rot silently. This contract makes staleness observable instead of discovered-in-failure. + +## Last-verified, not created + +A freshness timestamp records when the document's claims were last verified against live state, not when the text was written. Editing prose without re-verifying claims does not refresh it. + +## Staleness thresholds by document kind + +Reference defaults; a surface may declare stricter ones. Past-threshold is not auto-deletion — it is an audit finding that demands re-verification, update, or deprecation. + +| Kind | Threshold | Rationale | +|---|---|---| +| Operational scope/config statements | 30 days | Tracks fast-moving work state. | +| Lessons from recent incidents | 60 days | Should be promoted or retired, not hoarded. | +| Rules and gates | 90 days | Stable, but must track workflow evolution. | +| External-source distillations | 180 days | Bounded by upstream drift, tracked explicitly below. | + +## Upstream identity for distillations + +A document distilled from an external source records the upstream identity it was distilled from (commit SHA, release version, or dated URL) so upstream drift is detectable by comparison rather than by memory. + +## Co-change check + +When changing a workflow surface, command, or file that durable documents describe, grep the durable surfaces for the changed names. Statements the change makes stale get an update in the same change or an explicit follow-up proposal. Silent rot is the failure mode this contract exists to prevent. + +## Application scope + +Applies to durable documents created or modified after this contract landed. Retroactive stamping of the existing corpus is a separate mechanical rollout, sized and approved on its own. + +Pattern provenance: distilled from field observation of an OKF-style repo-local agent knowledge-bundle workflow (Open Knowledge Format v0.1 governance). diff --git a/.codex/skills/ddalggak/references/wiki-growth-triage.md b/.codex/skills/ddalggak/references/wiki-growth-triage.md index 2cb1a57..0ce6255 100644 --- a/.codex/skills/ddalggak/references/wiki-growth-triage.md +++ b/.codex/skills/ddalggak/references/wiki-growth-triage.md @@ -67,7 +67,7 @@ When asked to audit or clean a durable knowledge surface, run report → approva 4. Missing or undefined required metadata, such as admission header fields. 5. Index ↔ file mismatches, checked in both directions. 6. Contradictions between entries on the same topic — report for human decision; never auto-merge content conflicts. -7. Stale entries past a declared freshness threshold, when the surface declares one. +7. Stale entries past a declared freshness threshold, when the surface declares one (thresholds and last-verified semantics: `references/knowledge-freshness-contract.md`). 8. Tag or vocabulary drift from the established set. 9. Duplicate suspects, routed to the merge rule in Idempotent knowledge writes. diff --git a/core/projections.yaml b/core/projections.yaml index ee3960f..9df89d8 100644 --- a/core/projections.yaml +++ b/core/projections.yaml @@ -63,6 +63,8 @@ parity_ledger: class: must-match - path: references/issue-ready-plan.md class: may-localize + - path: references/knowledge-freshness-contract.md + class: must-match - path: references/local-diff-check.md class: may-localize - path: references/merge-cleanup.md diff --git a/core/token-budgets.yaml b/core/token-budgets.yaml index 190996c..6eb260c 100644 --- a/core/token-budgets.yaml +++ b/core/token-budgets.yaml @@ -87,6 +87,9 @@ reference_budget_exemptions: - reference: vercel-agent-skills-gates.md max_tokens: 2300 reason: conditional gate reachable only via quality-lens-router; not in any base required_references + - reference: knowledge-freshness-contract.md + max_tokens: 800 + reason: freshness contract loaded on demand via wiki-growth-triage knowledge audit pointer; not in any base required_references - reference: pr-status-evidence-bundle.md max_tokens: 1400 reason: claude-runtime pr-status evidence bundle loaded on demand outside base required_references diff --git a/ddalggak/references/knowledge-freshness-contract.md b/ddalggak/references/knowledge-freshness-contract.md new file mode 100644 index 0000000..34cd741 --- /dev/null +++ b/ddalggak/references/knowledge-freshness-contract.md @@ -0,0 +1,36 @@ +# Knowledge Freshness Contract +Use when: creating or editing a durable knowledge document (reference, template, wiki proposal), or judging whether an existing one is still current before citing it. +Required by: knowledge audit mode in `wiki-growth-triage.md`; freshness judgment before citing a durable document as current. +Side effects: none +Do not use when: the document is transient session output (a plan, research report, or review comment) that is not meant to stay durable. + +Durable documents rot silently. This contract makes staleness observable instead of discovered-in-failure. + +## Last-verified, not created + +A freshness timestamp records when the document's claims were last verified against live state, not when the text was written. Editing prose without re-verifying claims does not refresh it. + +## Staleness thresholds by document kind + +Reference defaults; a surface may declare stricter ones. Past-threshold is not auto-deletion — it is an audit finding that demands re-verification, update, or deprecation. + +| Kind | Threshold | Rationale | +|---|---|---| +| Operational scope/config statements | 30 days | Tracks fast-moving work state. | +| Lessons from recent incidents | 60 days | Should be promoted or retired, not hoarded. | +| Rules and gates | 90 days | Stable, but must track workflow evolution. | +| External-source distillations | 180 days | Bounded by upstream drift, tracked explicitly below. | + +## Upstream identity for distillations + +A document distilled from an external source records the upstream identity it was distilled from (commit SHA, release version, or dated URL) so upstream drift is detectable by comparison rather than by memory. + +## Co-change check + +When changing a workflow surface, command, or file that durable documents describe, grep the durable surfaces for the changed names. Statements the change makes stale get an update in the same change or an explicit follow-up proposal. Silent rot is the failure mode this contract exists to prevent. + +## Application scope + +Applies to durable documents created or modified after this contract landed. Retroactive stamping of the existing corpus is a separate mechanical rollout, sized and approved on its own. + +Pattern provenance: distilled from field observation of an OKF-style repo-local agent knowledge-bundle workflow (Open Knowledge Format v0.1 governance). diff --git a/ddalggak/references/wiki-growth-triage.md b/ddalggak/references/wiki-growth-triage.md index 2cb1a57..0ce6255 100644 --- a/ddalggak/references/wiki-growth-triage.md +++ b/ddalggak/references/wiki-growth-triage.md @@ -67,7 +67,7 @@ When asked to audit or clean a durable knowledge surface, run report → approva 4. Missing or undefined required metadata, such as admission header fields. 5. Index ↔ file mismatches, checked in both directions. 6. Contradictions between entries on the same topic — report for human decision; never auto-merge content conflicts. -7. Stale entries past a declared freshness threshold, when the surface declares one. +7. Stale entries past a declared freshness threshold, when the surface declares one (thresholds and last-verified semantics: `references/knowledge-freshness-contract.md`). 8. Tag or vocabulary drift from the established set. 9. Duplicate suspects, routed to the merge rule in Idempotent knowledge writes. From 1575cc1eaaab693cb7bd45b98a3cb284eb540555 Mon Sep 17 00:00:00 2001 From: Jeongwook Park Date: Fri, 3 Jul 2026 17:33:46 +0900 Subject: [PATCH 3/3] =?UTF-8?q?docs(references):=20=EC=8B=A0=EC=84=A0?= =?UTF-8?q?=EB=8F=84=20=EB=A7=88=EC=BB=A4=20=ED=91=9C=EA=B8=B0=20=ED=8F=AC?= =?UTF-8?q?=EB=A7=B7=20=EC=A0=95=EC=9D=98=20(=EB=A6=AC=EB=B7=B0=20Medium?= =?UTF-8?q?=20=EB=B0=98=EC=98=81)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 리뷰 지적대로 last-verified 의미론만 있고 표기 포맷이 없어 감사 항목이 기계 실행 불가했다. admission header 직하의 `Last-verified: YYYY-MM-DD ()` 라인과 `Freshness-threshold: d` 선언 형식을 계약에 명시한다. Co-Authored-By: Claude Fable 5 Ultraworked-With: claude-fable-5 User-Request: 리뷰 suggestion 적용하고 머지 진행 --- .../skills/ddalggak/references/knowledge-freshness-contract.md | 2 +- ddalggak/references/knowledge-freshness-contract.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.codex/skills/ddalggak/references/knowledge-freshness-contract.md b/.codex/skills/ddalggak/references/knowledge-freshness-contract.md index 34cd741..a4de195 100644 --- a/.codex/skills/ddalggak/references/knowledge-freshness-contract.md +++ b/.codex/skills/ddalggak/references/knowledge-freshness-contract.md @@ -8,7 +8,7 @@ Durable documents rot silently. This contract makes staleness observable instead ## Last-verified, not created -A freshness timestamp records when the document's claims were last verified against live state, not when the text was written. Editing prose without re-verifying claims does not refresh it. +A freshness timestamp records when the document's claims were last verified against live state, not when the text was written. Record it as a `Last-verified: YYYY-MM-DD ()` line directly under the admission header; a surface declares thresholds or stricter overrides the same way (e.g. `Freshness-threshold: 90d`). Editing prose without re-verifying claims does not refresh it. ## Staleness thresholds by document kind diff --git a/ddalggak/references/knowledge-freshness-contract.md b/ddalggak/references/knowledge-freshness-contract.md index 34cd741..a4de195 100644 --- a/ddalggak/references/knowledge-freshness-contract.md +++ b/ddalggak/references/knowledge-freshness-contract.md @@ -8,7 +8,7 @@ Durable documents rot silently. This contract makes staleness observable instead ## Last-verified, not created -A freshness timestamp records when the document's claims were last verified against live state, not when the text was written. Editing prose without re-verifying claims does not refresh it. +A freshness timestamp records when the document's claims were last verified against live state, not when the text was written. Record it as a `Last-verified: YYYY-MM-DD ()` line directly under the admission header; a surface declares thresholds or stricter overrides the same way (e.g. `Freshness-threshold: 90d`). Editing prose without re-verifying claims does not refresh it. ## Staleness thresholds by document kind