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..a4de195 --- /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. 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 + +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 eefc5cf..0ce6255 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 (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. + ## Worked examples | Input knowledge | Classification | Why | 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 52ede62..6eb260c 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 @@ -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..a4de195 --- /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. 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 + +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 eefc5cf..0ce6255 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 (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. + ## Worked examples | Input knowledge | Classification | Why |