tegwick
c1b60f322e
All checks were successful
Build and publish policy-nexus image / build-and-push (push) Successful in 1m10s
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a058f3-8ba0-7692-a042-9a870fc3d663
279 lines
30 KiB
HTML
279 lines
30 KiB
HTML
<!doctype html>
|
|
<html lang="en"><meta charset="utf-8">
|
|
<meta name="policy-source-revision" content="f9435cd605cc5b3cb0f2e957ce6287d9f3129aac">
|
|
<meta name="policy-source-digest" content="61889b2f18a82a08b66ef90d758efe5c028a4f52aced1721a23e69c6f24a8224">
|
|
<title>Project Repository Flavor (prj-) v0.1</title>
|
|
<style>
|
|
:root{
|
|
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
|
|
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
|
|
--rule:#D3D7DC; --rule-strong:#B6BCC3;
|
|
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
|
|
--clay:#8A3A2C; --clay-soft:#F2DFDA;
|
|
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
|
|
--chip-fg:#F6F7F8;
|
|
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
|
|
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
|
|
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
|
|
--measure:66ch;
|
|
}
|
|
@media (prefers-color-scheme:dark){
|
|
:root:not([data-theme="light"]){
|
|
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
|
|
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
|
|
--rule:#2A3138; --rule-strong:#3B444D;
|
|
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
|
|
--clay:#D08A76; --clay-soft:#3A211B;
|
|
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
|
|
--chip-fg:#12161A;
|
|
}
|
|
}
|
|
:root[data-theme="dark"]{
|
|
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
|
|
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
|
|
--rule:#2A3138; --rule-strong:#3B444D;
|
|
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
|
|
--clay:#D08A76; --clay-soft:#3A211B;
|
|
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
|
|
--chip-fg:#12161A;
|
|
}
|
|
|
|
*{box-sizing:border-box}
|
|
body{
|
|
margin:0; background:var(--paper); color:var(--ink);
|
|
font-family:var(--font-body); font-size:17px; line-height:1.62;
|
|
-webkit-font-smoothing:antialiased;
|
|
}
|
|
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
|
|
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
|
|
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
|
|
|
|
/* ---------- rail ---------- */
|
|
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
|
|
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
|
|
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
|
|
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
|
|
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
|
|
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
|
|
|
|
/* ---------- header ---------- */
|
|
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
|
|
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
|
|
.eyebrow .stat{color:var(--clay)}
|
|
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
|
|
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
|
|
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
|
|
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
|
|
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
|
|
|
|
/* ---------- typography ---------- */
|
|
section{margin-bottom:60px;scroll-margin-top:24px}
|
|
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
|
|
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
|
|
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
|
|
p{margin:0 0 15px;max-width:var(--measure)}
|
|
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
|
|
li{margin-bottom:7px}
|
|
strong{font-weight:600}
|
|
em{font-style:italic}
|
|
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
|
|
a{color:var(--brass)}
|
|
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
|
|
|
|
/* ---------- devices ---------- */
|
|
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
|
|
.callout p:last-child{margin-bottom:0}
|
|
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
|
|
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
|
|
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
|
|
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
|
|
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
|
|
.hard p:last-child{margin-bottom:0}
|
|
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
|
|
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
|
|
|
|
/* ---------- tables ---------- */
|
|
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
|
|
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
|
|
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
|
|
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
|
|
td:first-child{color:var(--ink);font-weight:600}
|
|
tbody tr:last-child td{border-bottom:none}
|
|
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
|
|
|
|
/* ---------- ladders ---------- */
|
|
.breakout{margin:34px 0 40px}
|
|
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
|
|
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
|
|
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
|
|
.ladders{display:grid;gap:26px}
|
|
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
|
|
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
|
|
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
|
|
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
|
|
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
|
|
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
|
|
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
|
|
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
|
|
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
|
|
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
|
|
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
|
|
.rung.na{opacity:.42}
|
|
|
|
/* ---------- matrix ---------- */
|
|
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
|
|
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
|
|
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
|
|
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
|
|
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
|
|
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
|
|
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
|
|
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
|
|
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
|
|
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
|
|
.rlab{min-height:60px}
|
|
.clab{padding-top:7px;min-height:22px}
|
|
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
|
|
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
|
|
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
|
|
.mnote .k{display:flex;align-items:center;gap:7px}
|
|
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
|
|
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
|
|
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
|
|
@media (max-width:640px){
|
|
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
|
|
.mcell{min-height:52px;padding:4px}
|
|
.pin{font-size:8px;padding:1px 3px}
|
|
.rlab{min-height:52px}
|
|
}
|
|
|
|
/* ---------- methodology ---------- */
|
|
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
|
|
.verb{background:var(--surface);padding:18px 18px 20px}
|
|
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
|
|
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
|
|
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
|
|
|
|
/* ---------- questions ---------- */
|
|
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
|
|
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
|
|
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
|
|
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
|
|
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
|
|
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
|
|
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
|
|
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
|
|
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
|
|
|
|
/* ---------- misc ---------- */
|
|
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
|
|
.numbers .v{color:var(--ink);font-weight:600}
|
|
.numbers .k{color:var(--ink-3)}
|
|
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
|
|
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
|
|
.alt:last-of-type{border-bottom:none}
|
|
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
|
|
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
|
|
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
|
|
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
|
|
.tm td,.tm th{text-align:center}
|
|
.tm td:first-child,.tm th:first-child{text-align:left}
|
|
.yes{color:var(--l4);font-weight:700}
|
|
.no{color:var(--clay);font-weight:700}
|
|
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
|
|
.kind.adv{border-color:var(--clay);color:var(--clay)}
|
|
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
|
|
.route{background:var(--surface);padding:16px 18px}
|
|
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
|
|
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
|
|
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
|
|
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
|
|
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
|
|
|
|
</style>
|
|
<div class="wrap"><header><div class="eyebrow"><span>canon-project-repository-flavor</span> <span class="stat">accepted · accepted-1</span> <span>the-custodian</span> <span>reviewed 2026-08-31</span><span>generated from canonical source — do not edit</span></div><h1>Project Repository Flavor (prj-) v0.1</h1><p class="sub">Source: <code>the-custodian · canon/standards/project-repository-flavor_v0.1.md · f9435cd605cc5b3cb0f2e957ce6287d9f3129aac</code></p><p class="sub">Review due: 2027-02-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#purpose"><span class="n">·</span>Purpose</a></li><li><a href="#when-to-use-a-project-repository"><span class="n">·</span>When to use a project repository</a></li><li><a href="#naming"><span class="n">·</span>Naming</a></li><li><a href="#authority-boundary"><span class="n">·</span>Authority boundary</a></li><li><a href="#required-files"><span class="n">·</span>Required files</a></li><li><a href="#lifecycle"><span class="n">·</span>Lifecycle</a></li><li><a href="#residuals-before-completion"><span class="n">·</span>Residuals before completion</a></li><li><a href="#completion-record"><span class="n">·</span>Completion record</a></li><li><a href="#archive-procedure"><span class="n">·</span>Archive procedure</a></li><li><a href="#workplan-and-agent-conventions"><span class="n">·</span>Workplan and agent conventions</a></li><li><a href="#minimal-layout-example"><span class="n">·</span>Minimal layout example</a></li><li><a href="#reference-instance"><span class="n">·</span>Reference instance</a></li><li><a href="#conformance-checklist"><span class="n">·</span>Conformance checklist</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="purpose"><h2>Purpose</h2>
|
|
<p>Define the durable <strong>project repository</strong> flavor used for complex cross-repository efforts: naming, required files, authority boundary, lifecycle, residual handoff, and archive procedure.</p>
|
|
<p>This standard implements and completes <strong>ADR-005</strong> (<em>Cross-Repo Workplans Live in Dedicated Project Repos</em>). It does <strong>not</strong> replace the Repo Classification Standard: project repositories still use <code>category: project</code> in <code>.repo-classification.yaml</code>.</p>
|
|
</section>
|
|
<section id="when-to-use-a-project-repository"><h2>When to use a project repository</h2>
|
|
<p>Create a project repository when <strong>all</strong> of the following hold:</p>
|
|
<ol><li>The work coordinates change across <strong>two or more</strong> functional repositories.</li><li>Binding the coordination workplan to any single product/tooling repo would misrepresent ownership or pollute that repo's history.</li><li>The effort has a <strong>bounded outcome</strong> with explicit success and retirement conditions (not an open-ended product roadmap).</li></ol>
|
|
<p>Do <strong>not</strong> create a project repository for:</p>
|
|
<ul><li>single-repo workplans;</li><li>small cross-cutting fixes that fit one lead repo's workplan plus dependency links;</li><li>durable products, libraries, or services (those use <code>INTENT.md</code> and ordinary product/tooling/research categories);</li><li>long-lived domain charters (those remain under <code>the-custodian/canon/projects/</code>).</li></ul>
|
|
</section>
|
|
<section id="naming"><h2>Naming</h2>
|
|
<div class="scroll"><table><thead><tr><th>Element</th><th>Convention</th></tr></thead><tbody><tr><td>Git / local directory</td><td><code>prj-<kebab-slug></code></td></tr><tr><td>Hub <code>repo</code> slug</td><td>same as directory name</td></tr><tr><td>Workplan prefix</td><td>short uppercase prefix derived from the project, ending in <code>-WP-</code> (example: <code>SHR-WP-</code> for State Hub Retirement)</td></tr><tr><td>Classification</td><td><code>category: project</code></td></tr></tbody></table></div>
|
|
<p><strong>Canonical prefix is <code>prj-</code>.</strong> ADR-005's illustrative <code>proj-</code> form is superseded for new repositories. Do not invent parallel prefixes (<code>project-</code>, <code>xrepo-</code>, …).</p>
|
|
<p>Slug rules:</p>
|
|
<ul><li>lowercase kebab-case;</li><li>outcome-oriented (<code>prj-state-hub-retirement</code>), not a random ticket id;</li><li>stable for the life of the project (rename only with an explicit migration note in <code>history/</code>).</li></ul>
|
|
</section>
|
|
<section id="authority-boundary"><h2>Authority boundary</h2>
|
|
<div class="scroll"><table><thead><tr><th>Concern</th><th>Owner</th></tr></thead><tbody><tr><td>Project goal, success gates, retirement conditions</td><td>project repo (<code>GOAL.md</code>)</td></tr><tr><td>Architecture decisions, sequencing, dependency map, migration ledger, risks, consolidated evidence</td><td>project repo</td></tr><tr><td>Cross-repo workplans that coordinate the effort</td><td>project repo (<code>workplans/</code>)</td></tr><tr><td>Production implementation, tests, deployables</td><td><strong>participating functional repositories</strong></td></tr><tr><td>Per-repo implementation workplans and local evidence</td><td>each functional repository</td></tr><tr><td>Durable post-project standards and ADRs</td><td>permanent homes (<code>the-custodian</code> canon, or the owning product/tooling repo)</td></tr></tbody></table></div>
|
|
<p><strong>Hard rules:</strong></p>
|
|
<ol><li>Project repositories <strong>MUST NOT</strong> host production implementation code for the systems being changed.</li><li>Project workplans <strong>link</strong> child workplans by stable ID; they <strong>MUST NOT</strong> copy or replace child task lists.</li><li>The hub remains a read/index layer; work records originate as files (ADR-001).</li><li>Results of the project live primarily in the modified functional repositories and promoted canon. The project repo is coordination + provenance.</li></ol>
|
|
</section>
|
|
<section id="required-files"><h2>Required files</h2>
|
|
<p>At registration / first meaningful commit:</p>
|
|
<div class="scroll"><table><thead><tr><th>Path</th><th>Required</th><th>Role</th></tr></thead><tbody><tr><td><code>GOAL.md</code></td><td><strong>yes</strong></td><td>Outcome, invariants, success gates, project retirement conditions. <strong>Replaces <code>INTENT.md</code> for this flavor.</strong></td></tr><tr><td><code>SCOPE.md</code></td><td><strong>yes</strong></td><td>Project authority, participating repos, in/out of scope, work-record rule.</td></tr><tr><td><code>README.md</code></td><td><strong>yes</strong></td><td>Short entry point linking <code>GOAL.md</code>, <code>SCOPE.md</code>, genesis/history, active workplans.</td></tr><tr><td><code>AGENTS.md</code></td><td><strong>yes</strong></td><td>Agent session protocol for this project (orient → work → close; hub integration).</td></tr><tr><td><code>.repo-classification.yaml</code></td><td><strong>yes</strong></td><td><code>category: project</code> plus domain / capability tags for the <em>effort</em>.</td></tr><tr><td><code>workplans/</code></td><td><strong>yes</strong></td><td>At least one foundation workplan; prefix unique to the project.</td></tr><tr><td><code>history/</code></td><td>recommended</td><td>Genesis and significant milestones (why the project exists).</td></tr><tr><td><code>WORK-RECORDS.md</code></td><td>generated</td><td>Hub index; do not hand-edit.</td></tr><tr><td><code>.custodian-brief.md</code></td><td>generated</td><td>Offline orientation brief.</td></tr></tbody></table></div>
|
|
<h3><code>GOAL.md</code> (not <code>INTENT.md</code>)</h3>
|
|
<p>Durable product and tooling repositories explain <strong>why they exist</strong> with <code>INTENT.md</code>. Project repositories are temporary and outcome-bounded; they use <strong><code>GOAL.md</code></strong> instead.</p>
|
|
<p><code>GOAL.md</code> MUST include:</p>
|
|
<ol><li><strong>Outcome</strong> — what success looks like in one short section.</li><li><strong>Invariants</strong> — rules that must hold during the project.</li><li><strong>Success gates</strong> — checkable conditions for “goal achieved”.</li><li><strong>Project retirement</strong> — conditions under which <em>this repository</em> may be archived (usually: gates met + residuals handed off + durable decisions promoted).</li></ol>
|
|
<p>Recommended frontmatter:</p>
|
|
<pre>---
|
|
repo: prj-<slug>
|
|
repo_flavor: project
|
|
project_status: draft | active | completed | archived
|
|
started: "YYYY-MM-DD"
|
|
reviewed: "YYYY-MM-DD"
|
|
---</pre>
|
|
<p><strong>Anti-pattern:</strong> shipping both <code>INTENT.md</code> and <code>GOAL.md</code> in a <code>prj-</code> repo. If a durable intent emerges, promote it into a permanent repository's <code>INTENT.md</code> (or canon) and keep the project goal as the temporary outcome document.</p>
|
|
<h3>Relation to durable <code>INTENT.md</code></h3>
|
|
<div class="scroll"><table><thead><tr><th>Repository kind</th><th>Purpose document</th></tr></thead><tbody><tr><td>product / tooling / research / business / experimental</td><td><code>INTENT.md</code></td></tr><tr><td><strong>project (<code>prj-</code>)</strong></td><td><strong><code>GOAL.md</code> only</strong></td></tr></tbody></table></div>
|
|
<p>Tooling that scaffolds repositories (e.g. <code>statehub register</code>) MUST treat <code>GOAL.md</code> + <code>repo_flavor: project</code> as sufficient purpose documentation for <code>prj-</code> repos and MUST NOT require inventing an <code>INTENT.md</code> that pretends the project is a permanent product.</p>
|
|
</section>
|
|
<section id="lifecycle"><h2>Lifecycle</h2>
|
|
<pre>draft → active → completed → archived</pre>
|
|
<div class="scroll"><table><thead><tr><th>Status</th><th>Meaning</th><th>Repo / hub signals</th></tr></thead><tbody><tr><td><code>draft</code></td><td>Convention and foundation still forming; may not yet be registered</td><td><code>project_status: draft</code>; workplans often <code>proposed</code> / <code>ready</code></td></tr><tr><td><code>active</code></td><td>Coordination and child implementation in progress</td><td><code>project_status: active</code>; at least one workplan <code>active</code> or <code>ready</code></td></tr><tr><td><code>completed</code></td><td>All success gates have accepted evidence; residuals have live owners outside this repo</td><td><code>project_status: completed</code>; project workplans <code>finished</code> or cancelled with rationale</td></tr><tr><td><code>archived</code></td><td>Repository is read-only provenance</td><td>forge archive flag; hub repo/workplan <code>archived</code>; no normal writes</td></tr></tbody></table></div>
|
|
<p>Promotion rules:</p>
|
|
<ul><li><code>draft → active</code> when <code>GOAL.md</code> / <code>SCOPE.md</code> are reviewable and the foundation workplan is <code>ready</code> or <code>active</code>.</li><li><code>active → completed</code> only when <strong>every</strong> <code>GOAL.md</code> success gate has accepted evidence <strong>and</strong> residuals are live work records elsewhere (see below).</li><li><code>completed → archived</code> after the completion record is written, durable decisions are promoted, and a final consistency/link check passes.</li></ul>
|
|
</section>
|
|
<section id="residuals-before-completion"><h2>Residuals before completion</h2>
|
|
<p>Actionable leftovers MUST NOT live only in finished workplan prose or <code>SCOPE.md</code>. Before any project workplan is set to <code>finished</code>, and again before <code>project_status: completed</code>, each residual becomes a <strong>live work record</strong> outside the closing narrative:</p>
|
|
<ul><li>intake with <code>origin: residual</code> + <code>origin_ref: <WP-id></code>, or</li><li>a next workplan / decision / engagement / register-entry in a permanent repo.</li></ul>
|
|
<p>Canon: <code>work-record-types_v0.1.md</code> § Residuals. Fleet residual listing is a State Hub concern, not a project-local queue file.</p>
|
|
</section>
|
|
<section id="completion-record"><h2>Completion record</h2>
|
|
<p>Before archival, the project repository MUST contain a completion record (recommended path: <code>history/YYYY-MM-DD-completion.md</code>) that lists:</p>
|
|
<ol><li>deployed or merged revisions that realize the outcome;</li><li>every participating repository touched, with links to merged PRs/commits or child workplan IDs;</li><li>promoted durable artefacts (canon paths, ADRs, standards);</li><li>migration and retirement evidence pointers (counts, cutover windows, backups);</li><li>residual work-record IDs and their owning repos;</li><li>rollback expiry or remaining operational obligations, if any.</li></ol>
|
|
<p>Without this record, do not archive.</p>
|
|
</section>
|
|
<section id="archive-procedure"><h2>Archive procedure</h2>
|
|
<ol><li>Verify all success gates and retirement conditions in <code>GOAL.md</code>.</li><li>Confirm residuals are live and owned outside this repository.</li><li>Promote remaining durable decisions/standards to permanent homes; leave pointers from the project repo.</li><li>Finish or cancel project workplans; move finished files to <code>workplans/archived/YYMMDD-<id>-<slug>.md</code> per workplan convention.</li><li>Write the completion record.</li><li>Set <code>project_status: archived</code> in <code>GOAL.md</code> frontmatter.</li><li>Run <code>statehub fix-consistency</code> (or equivalent) so the hub reflects finished workplans and the archived status.</li><li>Archive the repository in the forge (read-only); do <strong>not</strong> delete it.</li><li>Optionally mark the hub registration archived / read-only.</li></ol>
|
|
<p><strong>Archive means read-only provenance, never deletion.</strong> Historical evidence and coordination narrative remain queryable.</p>
|
|
</section>
|
|
<section id="workplan-and-agent-conventions"><h2>Workplan and agent conventions</h2>
|
|
<ul><li>Workplan files: <code>workplans/<PREFIX>-WP-NNNN-<slug>.md</code> with fleet status vocabulary (<code>proposed</code> … <code>archived</code>).</li><li>Session start order for agents: <code>GOAL.md</code> → <code>SCOPE.md</code> → genesis/history → active workplans (see project <code>AGENTS.md</code>).</li><li>Progress and task status follow ordinary State Hub / fix-consistency rules.</li><li>Ad-hoc low-risk fixes may use <code>workplans/ADHOC-YYYY-MM-DD.md</code> with canonical id <code>{PREFIX}-WP-ADHOC-YYYY-MM-DD</code>; anything multi-step belongs in a normal workplan.</li></ul>
|
|
</section>
|
|
<section id="minimal-layout-example"><h2>Minimal layout example</h2>
|
|
<pre>prj-example-cutover/
|
|
GOAL.md
|
|
SCOPE.md
|
|
README.md
|
|
AGENTS.md
|
|
.repo-classification.yaml
|
|
history/
|
|
2026-08-09-genesis.md
|
|
workplans/
|
|
EX-WP-0001-foundation.md</pre>
|
|
</section>
|
|
<section id="reference-instance"><h2>Reference instance</h2>
|
|
<p>The first repository under this standard is <code>prj-state-hub-retirement</code> (State Hub retirement / hub-core consolidation). Use it as the structural reference when scaffolding later <code>prj-</code> repos; do not copy its domain-specific content.</p>
|
|
</section>
|
|
<section id="conformance-checklist"><h2>Conformance checklist</h2>
|
|
<p>A repository conforms to the <code>prj-</code> flavor when:</p>
|
|
<ul><li>[ ] Named <code>prj-<slug></code> and classified <code>category: project</code>.</li><li>[ ] Has <code>GOAL.md</code> with outcome, invariants, success gates, and retirement.</li><li>[ ] Has no durable-product <code>INTENT.md</code> (or documents an explicit temporary exception during migration of a mis-scaffolded repo).</li><li>[ ] Has <code>SCOPE.md</code>, <code>README.md</code>, <code>AGENTS.md</code>, and <code>.repo-classification.yaml</code>.</li><li>[ ] Hosts coordination workplans only; implementation lives in child repos.</li><li>[ ] Links child workplans by ID rather than duplicating their tasks.</li><li>[ ] Defines archive/completion discipline consistent with this standard.</li><li>[ ] On completion, writes a completion record and archives read-only.</li></ul>
|
|
</section>
|
|
<section id="related"><h2>Related</h2>
|
|
<ul><li>ADR-001 — Workplans and Work Items Are Repository Artefacts</li><li>ADR-005 — Cross-Repo Workplans Live in Dedicated Project Repos</li><li><code>repo-classification-standard_v1.0.md</code> — <code>category: project</code></li><li><code>work-record-types_v0.1.md</code> — residuals and work-record kinds</li><li><code>workplan-terminology-fleet_v0.1.md</code> — workplan vocabulary</li></ul>
|
|
</section><footer><span>canon-project-repository-flavor · accepted-1 · accepted</span><span>the-custodian · canon/standards/project-repository-flavor_v0.1.md · f9435cd605cc5b3cb0f2e957ce6287d9f3129aac</span></footer></main></div></div></html>
|