@polymorphism-tech/morph-spec 8.6.0 → 8.8.0

package/framework/hooks/shared/claim-registry.js

@@ -0,0 +1,175 @@
+/**
+ * claim-registry.js — advisory feature ownership across parallel sessions.
+ *
+ * Two Claude Code sessions worked the SAME feature at the same time without
+ * seeing each other: one finished it and removed the worktree out from under
+ * the other's running sub-agent. A complete recap.md was discarded, a sub-agent
+ * wasted, and a decision taken on state that was already obsolete. There was no
+ * lock, no claim, no heartbeat — not even a warning.
+ *
+ * DELIBERATELY ADVISORY. This is not a lock: nothing here ever blocks a
+ * command. The framework is fail-open by principle, and a strong lock left
+ * behind by a crashed session would strand a feature for no gain. Being
+ * VISIBLE is the whole fix.
+ *
+ * Location: `<git-common-dir>/morph-spec/claims.json`, beside the fleet's
+ * env-registry, for the same three reasons — it can never dirty the `git
+ * status` the finish gates read, it survives `git clean -fdx`, and the COMMON
+ * dir is the one place every linked worktree of the repo shares. That last one
+ * is decisive here: in the observed incident one session sat inside the
+ * worktree and the other in the primary root, so a claim written to the
+ * branch-local `feature.json` would have been invisible to exactly the session
+ * that needed to read it.
+ *
+ * Writes are tmp+rename (torn file impossible); a corrupt registry reads as
+ * empty — the cost is a lost warning, never a crash.
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * A claim with no heartbeat for this long is considered dead. The heartbeat
+ * fires on tool activity, so this is really "how long a session may sit idle
+ * before its claim stops warning others".
+ */
+export const CLAIM_TTL_MS = 30 * 60 * 1000;
+
+/** Minimum gap between heartbeat WRITES. The heartbeat runs on every tool call. */
+export const HEARTBEAT_THROTTLE_MS = 60 * 1000;
+
+/** Claim file path for a repo's common git dir. */
+export function claimsPath(gitCommonDir) {
+  return join(gitCommonDir, 'morph-spec', 'claims.json');
+}
+
+function readRegistry(gitCommonDir) {
+  try {
+    const raw = readFileSync(claimsPath(gitCommonDir), 'utf8').replace(/^/, '');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.claims === 'object' && parsed.claims !== null) return parsed;
+  } catch { /* fail-open: absent or corrupt registry restarts empty */ }
+  return { version: 1, claims: {} };
+}
+
+function writeRegistry(gitCommonDir, registry) {
+  const path = claimsPath(gitCommonDir);
+  mkdirSync(join(gitCommonDir, 'morph-spec'), { recursive: true });
+  const tmp = `${path}.tmp.${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify(registry, null, 2)}\n`, 'utf8');
+  renameSync(tmp, path);
+}
+
+/** Is this claim still within its TTL? A missing/unparseable heartbeat is dead. */
+export function isLive(claim, now = Date.now()) {
+  const beat = Date.parse(claim?.heartbeatAt ?? '');
+  return Number.isFinite(beat) && now - beat < CLAIM_TTL_MS;
+}
+
+/**
+ * Claim a feature for this session, or refresh an existing claim of ours.
+ *
+ * A claim held by ANOTHER session is TAKEN OVER, not refused — advisory by
+ * design, and the caller has already been warned via `foreignClaim`. The
+ * takeover is recorded in `previousSessionId` so it is never silent.
+ *
+ * @param {string} feature
+ * @param {{ gitCommonDir: string, sessionId: string, pid?: number, path?: string }} opts
+ * @returns {object} the stored claim
+ */
+export function acquireClaim(feature, { gitCommonDir, sessionId, pid = process.pid, path = null }) {
+  const registry = readRegistry(gitCommonDir);
+  const previous = registry.claims[feature];
+  const now = new Date().toISOString();
+  const claim = {
+    feature,
+    sessionId,
+    pid,
+    path: path ? String(path).replace(/\\/g, '/') : null,
+    claimedAt: previous?.sessionId === sessionId ? (previous.claimedAt || now) : now,
+    heartbeatAt: now,
+    ...(previous && previous.sessionId !== sessionId ? { previousSessionId: previous.sessionId } : {}),
+  };
+  registry.claims[feature] = claim;
+  writeRegistry(gitCommonDir, registry);
+  return claim;
+}
+
+/**
+ * Refresh our own claim's heartbeat. Throttled — this runs on every tool call,
+ * and a write per call would be pure I/O waste.
+ *
+ * Never touches a claim owned by another session: a heartbeat is proof of life,
+ * and forging someone else's would defeat the TTL.
+ *
+ * @param {string} feature
+ * @param {{ gitCommonDir: string, sessionId: string }} opts
+ * @returns {boolean} true when a write actually happened
+ */
+export function heartbeatClaim(feature, { gitCommonDir, sessionId }) {
+  const registry = readRegistry(gitCommonDir);
+  const claim = registry.claims[feature];
+  if (!claim || claim.sessionId !== sessionId) return false;
+
+  const beat = Date.parse(claim.heartbeatAt ?? '');
+  if (Number.isFinite(beat) && Date.now() - beat < HEARTBEAT_THROTTLE_MS) return false;
+
+  claim.heartbeatAt = new Date().toISOString();
+  writeRegistry(gitCommonDir, registry);
+  return true;
+}
+
+/**
+ * The LIVE claim on this feature held by a session that is not us — the thing
+ * worth warning about. Returns null when the feature is unclaimed, claimed by
+ * us, or claimed by a session whose heartbeat went stale.
+ *
+ * @param {string} feature
+ * @param {{ gitCommonDir: string, sessionId?: string }} opts
+ * @returns {object|null}
+ */
+export function foreignClaim(feature, { gitCommonDir, sessionId }) {
+  const claim = readRegistry(gitCommonDir).claims[feature];
+  if (!claim) return null;
+  if (sessionId && claim.sessionId === sessionId) return null;
+  return isLive(claim) ? claim : null;
+}
+
+/**
+ * Drop a feature's claim. Called by the manual `morph-spec claim <f> --release`
+ * (recovering from a session that died without releasing) and by `finish`.
+ *
+ * @param {string} feature
+ * @param {{ gitCommonDir: string }} opts
+ * @returns {boolean} false when there was nothing to release
+ */
+export function releaseClaim(feature, { gitCommonDir }) {
+  const registry = readRegistry(gitCommonDir);
+  if (!registry.claims[feature]) return false;
+  delete registry.claims[feature];
+  writeRegistry(gitCommonDir, registry);
+  return true;
+}
+
+/**
+ * Every claim on record, live and stale, newest heartbeat first. `live` is
+ * computed, never stored — a stored flag would go wrong the moment nobody
+ * rewrites the file.
+ *
+ * @param {string} gitCommonDir
+ * @returns {object[]}
+ */
+export function listClaims(gitCommonDir) {
+  const now = Date.now();
+  return Object.values(readRegistry(gitCommonDir).claims)
+    .map((c) => ({ ...c, live: isLive(c, now) }))
+    .sort((a, b) => String(b.heartbeatAt).localeCompare(String(a.heartbeatAt)));
+}
+
+/** Human-readable age of a claim's last heartbeat ("3 min", "2 h", "—"). */
+export function claimAge(claim, now = Date.now()) {
+  const beat = Date.parse(claim?.heartbeatAt ?? '');
+  if (!Number.isFinite(beat)) return '—';
+  const min = Math.max(0, Math.round((now - beat) / 60000));
+  return min < 60 ? `${min} min` : `${Math.round(min / 60)} h`;
+}

package/framework/hooks/shared/state-reader.js

@@ -181,6 +181,63 @@ export function getFeature(featureName, projectPath) {
  */
 export const PHASE_INDEX = { proposal: 0, uiux: 1, plan: 2, implement: 3, review: 4 };
 
+/**
+ * The canonical artifact of each phase, descending. Exported so a caller that
+ * holds the file list from somewhere OTHER than the local filesystem (a git
+ * tree, say) can answer the same question without re-encoding the map.
+ */
+export const PHASE_ARTIFACTS = [
+  ['4-review',    'review',    'review-report.md'],
+  ['3-implement', 'implement', 'recap.md'],
+  ['2-plan',      'plan',      'spec.md'],
+  ['1-design',    'uiux',      'design-system.md'],
+  ['0-proposal',  'proposal',  'proposal.md'],
+];
+
+const gatesOf = (feature) => feature?.approvals || feature?.approvalGates;
+
+/**
+ * Gate-implied phase from an ALREADY-LOADED feature object — no disk access.
+ *
+ * Split out of `gateImpliedPhase` so callers holding a feature.json that did
+ * not come from the working tree (e.g. `git show morph/{f}:…`) can reuse the
+ * rule instead of copying it. The path-based wrapper below is unchanged.
+ *
+ * @param {Object|null} feature
+ * @returns {string} phase name
+ */
+export function gateImpliedPhaseFrom(feature) {
+  const gates = gatesOf(feature);
+  const ok = (g) => gates?.[g]?.approved === true;
+  if (ok('review')) return 'review';
+  if (ok('plan')) return 'implement';
+  if (ok('uiux')) return 'plan';
+  return 'proposal';
+}
+
+/**
+ * Phase from an already-loaded feature plus an artifact predicate — no disk
+ * access of its own, so the artifact universe can be a git tree.
+ *
+ * @param {Object|null} feature
+ * @param {(relPath: string) => boolean} hasArtifact - receives POSIX-style
+ *   paths relative to the feature dir, e.g. `2-plan/spec.md`
+ * @returns {string} phase name
+ */
+export function derivePhaseFrom(feature, hasArtifact) {
+  let artifactPhase = 'proposal';
+  for (const [folder, phase, canonical] of PHASE_ARTIFACTS) {
+    if (hasArtifact(`${folder}/${canonical}`)) { artifactPhase = phase; break; }
+  }
+
+  // Gate-aware: an approved gate advances the phase even before the next
+  // phase's first canonical artifact exists. This breaks the chicken-and-egg
+  // where that first artifact could never be written because the phase never
+  // advanced to permit it. Take whichever of (artifact, gate-implied) is later.
+  const implied = gateImpliedPhaseFrom(feature);
+  return PHASE_INDEX[implied] > PHASE_INDEX[artifactPhase] ? implied : artifactPhase;
+}
+
 /**
  * The phase implied purely by approved gates, independent of which artifacts
  * exist on disk. An approved gate authorizes the NEXT phase, so:
@@ -192,32 +249,15 @@ export const PHASE_INDEX = { proposal: 0, uiux: 1, plan: 2, implement: 3, review
  * @returns {string} phase name
  */
 export function gateImpliedPhase(featureName, projectPath) {
-  if (isGateApproved(featureName, 'review', projectPath)) return 'review';
-  if (isGateApproved(featureName, 'plan', projectPath)) return 'implement';
-  if (isGateApproved(featureName, 'uiux', projectPath)) return 'plan';
-  return 'proposal';
+  return gateImpliedPhaseFrom(getFeature(featureName, projectPath));
 }
 
 export function derivePhaseForFeature(featureName, projectPath) {
   const basePath = join(projectPath || process.cwd(), '.morph/features', featureName);
-  const phaseMap = [
-    ['4-review',    'review',    'review-report.md'],
-    ['3-implement', 'implement', 'recap.md'],
-    ['2-plan',      'plan',      'spec.md'],
-    ['1-design',    'uiux',      'design-system.md'],
-    ['0-proposal',  'proposal',  'proposal.md'],
-  ];
-  let artifactPhase = 'proposal';
-  for (const [folder, phase, canonical] of phaseMap) {
-    if (existsSync(join(basePath, folder, canonical))) { artifactPhase = phase; break; }
-  }
-
-  // Gate-aware: an approved gate advances the phase even before the next
-  // phase's first canonical artifact exists. This breaks the chicken-and-egg
-  // where that first artifact could never be written because the phase never
-  // advanced to permit it. Take whichever of (artifact, gate-implied) is later.
-  const implied = gateImpliedPhase(featureName, projectPath);
-  return PHASE_INDEX[implied] > PHASE_INDEX[artifactPhase] ? implied : artifactPhase;
+  return derivePhaseFrom(
+    getFeature(featureName, projectPath),
+    (rel) => existsSync(join(basePath, rel)),
+  );
 }
 
 /**
@@ -253,10 +293,9 @@ export function isGateApproved(featureName, gate, projectPath) {
  * @param {string} [projectPath]
  * @returns {string[]} List of gate names that are not yet approved
  */
-export function getPendingGates(featureName, projectPath) {
-  const feature = getFeature(featureName, projectPath);
+export function pendingGatesFrom(feature) {
   // Support both field names: 'approvals' (v5 state) and 'approvalGates' (legacy)
-  const gates = feature?.approvals || feature?.approvalGates;
+  const gates = gatesOf(feature);
   if (!gates) return [];
 
   return Object.entries(gates)
@@ -264,6 +303,10 @@ export function getPendingGates(featureName, projectPath) {
     .map(([name]) => name);
 }
 
+export function getPendingGates(featureName, projectPath) {
+  return pendingGatesFrom(getFeature(featureName, projectPath));
+}
+
 /**
  * Get feature outputs status.
  * @param {string} featureName

package/framework/rules/morph-task-tracking.md

@@ -33,11 +33,18 @@ TaskUpdate(taskId, subject="Round 3 — score 82/100")
 
 ## Persisting Progress to `tasks.json`
 
+> **Dois sistemas, dois vocabulários.** Tudo acima desta linha é sobre as *session
+> tasks* nativas do Claude Code (`TaskCreate`/`TaskUpdate`), cujo status terminal é
+> `completed`. Tudo abaixo é sobre o `tasks.json` do morph-spec, governado por
+> `.morph/framework/schemas/tasks.schema.json`, cujo status terminal é `done` —
+> **`completed` não existe nesse enum** e o hook `protect-spec-files` rejeita a
+> gravação. Não misture os dois.
+
 Native session tasks (`TaskCreate`/`TaskUpdate`) track your live work. To persist
 task progress for the feature, write `.morph/features/{feature}/2-plan/tasks.json`,
 touching ONLY the mutable fields:
 
-- `status` — `pending` → `in_progress` → `completed`
+- `status` — `pending` → `in_progress` → `done` (também: `skipped`, `blocked`)
 - `outputs` — the files the task produced
 - `notes` — free-text record (deviations, context, resolved blockers)
 
@@ -53,17 +60,16 @@ output.
 ## Deviation Tracking
 
 When completing a task differently than originally planned, record the reason in the
-task's `notes` field. Use the `notes` array to capture deviations, added context, or
-resolved blockers — for example:
+task's `notes` field. `notes` is **uma única string** (o schema declara
+`"notes": { "type": "string" }`) — para registrar mais de um desvio, separe-os com
+`;` ou `\n` dentro da mesma string. Um array é **rejeitado** pelo validador, com a
+mensagem `'notes' must be a string`.
 
 ```json
 {
   "id": "T3",
-  "status": "completed",
+  "status": "done",
   "outputs": ["Features/User/Update/Handler.cs"],
-  "notes": [
-    "deviation: split validation into a separate validator for testability",
-    "blocker-resolved: EF migration conflict fixed by regenerating the snapshot"
-  ]
+  "notes": "deviation: split validation into a separate validator for testability; blocker-resolved: EF migration conflict fixed by regenerating the snapshot"
 }
 ```

package/framework/rules/morph-workflow.md

@@ -72,6 +72,39 @@ All outputs go in `.morph/features/{feature}/`:
 
 ---
 
+## Formato obrigatório do `3-implement/recap.md`
+
+> Esta exigência é **cobrada por hook** (`validate-completion`, no Stop). Ela está aqui, na regra
+> sempre-ativa, e não só na skill `morph-implement`: descobrir o formato quando o hook dispara
+> significa reescrever o recap depois de a fase já estar dada por encerrada.
+
+**Para CADA task com `status: "done"` em `tasks.json`**, o recap precisa de um bloco próprio:
+
+1. um heading `## T{N}` (o hook casa `^## T\d+` — uma linha de tabela `| T1 | … | done |` conta
+   como menção, **não** como bloco);
+2. uma linha `**Standard:** {standard-id}` **dentro de 12 linhas** do heading. Sem standard que
+   cubra o caso, registre a decisão em `decisions.md` e cite
+   `**Standard:** ad-hoc (see decisions.md ADR-{N})`.
+
+```markdown
+## T{N} — {title}
+
+**Standard:** {standard-id} (`.morph/framework/standards/{path}.md`)
+**Persona:** {mecanismo real usado}
+**Files:**
+- `{path}`
+
+{2-3 frases sobre o que foi feito}
+
+**Issues encontrados:** {breve descrição ou "nenhum"}
+```
+
+O `validate-completion` também acusa **drift**: uma task que aparece como concluída no recap mas
+ainda está `pending`/`in_progress` no `tasks.json`. Template completo e regras de exceção em
+`morph-implement` §6.
+
+---
+
 ## Checkpoints
 
 Run a checkpoint every 3 completed tasks:
@@ -158,7 +191,7 @@ During implementation, these skills MUST be invoked at the specified triggers:
 | Trigger | Skill | When |
 |---------|-------|------|
 | Before each task | `superpowers:test-driven-development` | Invoke BEFORE writing any code for a task |
-| Before marking a task complete | `morph-verification-before-completion` | Invoke BEFORE setting a task's `status` to `completed` in `tasks.json` |
+| Before marking a task complete | `morph-verification-before-completion` | Invoke BEFORE setting a task's `status` to `done` in `tasks.json` |
 | On bug/unexpected | `superpowers:systematic-debugging` | Invoke IF a bug or unexpected behavior is encountered |
 | After all tasks | `morph-post-implementation` | Invoke AFTER all tasks completed |
 | Before PR | `morph-checklist` | Invoke BEFORE creating pull request |

package/framework/schemas/feature.schema.json

@@ -222,7 +222,8 @@
       "properties": {
         "approved": { "type": "boolean" },
         "timestamp": { "type": ["string", "null"], "description": "ISO timestamp of the approval/revocation, null while never evaluated." },
-        "approvedBy": { "type": ["string", "null"], "description": "\"auto\" (approve/advance --mode auto), \"manual\" (human in the loop), \"policy:{workType}\" (gate stamped at birth by `morph-spec create` per the work type's skippedGates — see src/core/work-types.js; the gate-guard hook only special-cases \"auto\", so policy-stamped gates stay silent to it), a --approver name, or null while never evaluated." }
+        "approvedBy": { "type": ["string", "null"], "description": "\"auto\" (approve/advance --mode auto), \"manual\" (human in the loop), \"policy:{workType}\" (gate stamped at birth by `morph-spec create` per the work type's skippedGates — see src/core/work-types.js; the gate-guard hook only special-cases \"auto\", so policy-stamped gates stay silent to it), a --approver name, or null while never evaluated." },
+        "selfAssessed": { "type": "boolean", "description": "Gate `review` SOMENTE. `true` quando o Gate 3 foi aprovado sem `4-review/evaluator-report.md`, via `morph-spec approve <f> review --self-assessed`. O score composto deveria vir do avaliador independente; esta flag registra a degradação em vez de deixá-la silenciosa, e aparece no `morph-spec list`." }
       },
       "additionalProperties": true
     }

package/framework/skills/core/create-umbraco-lp/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a criação de uma landing page nova ponta-a-ponta a partir do
 version: core
 when-to-invoke: ao iniciar um novo projeto de LP com o template Umbraco genérico
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.8.0"
 ---
 
 # create-umbraco-lp

package/framework/skills/core/migrate-lp-to-umbraco/SKILL.md

@@ -4,7 +4,7 @@ description: Migra uma landing page existente (React/Vite, Next.js estático ou
 version: core
 when-to-invoke: ao receber instrução "use /migrate-lp-to-umbraco {projeto}" do usuário, ou quando o usuário descrever necessidade de migrar uma LP para Umbraco
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.8.0"
 ---
 
 # migrate-lp-to-umbraco

package/framework/skills/core/morph-apply/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a execução autônoma de tasks de uma feature morph-spec
 version: core
 when-to-invoke: após Gate 2 aprovado, ao receber instrução "use /morph-apply" ou "implementar feature"
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.8.0"
 ---
 
 # morph-apply

package/framework/skills/core/morph-brainstorming/SKILL.md

@@ -4,7 +4,7 @@ description: Entende o negócio, os usuários e a arquitetura antes de qualquer
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.8.0"
 ---
 
 # morph-brainstorming

package/framework/skills/core/morph-eval/SKILL.md

@@ -4,7 +4,7 @@ description: Avalia a qualidade de uma tarefa ou fase com rubricas graduadas 0-1
 version: core
 when-to-invoke: ao completar uma tarefa ou ao finalizar uma fase de implementação
 user-invokable: false
-cliVersion: "8.6.0"
+cliVersion: "8.8.0"
 ---
 
 # morph-eval

package/framework/skills/core/morph-hotfix/SKILL.md

@@ -4,7 +4,7 @@ description: ADW cirúrgico de hotfix — resolve uma queda/bug crítico de prod
 version: core
 when-to-invoke: ao receber "/morph-hotfix {feature}", quando a morph-proposal classifica o pedido como workType hotfix (Passo 0), ou o usuário diz "produção caiu / hotfix / urgente"
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.8.0"
 ---
 
 # morph-hotfix

package/framework/skills/core/morph-implement/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a execução de cada tarefa de implementação com standard e
 version: core
 when-to-invoke: ao iniciar cada task de implementação listada em tasks.json
 user-invokable: false
-cliVersion: "8.6.0"
+cliVersion: "8.8.0"
 ---
 
 # morph-implement

package/framework/skills/core/morph-plan/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a produção dos artefatos de planejamento de uma feature (use
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.8.0"
 ---
 
 # morph-plan

package/framework/skills/core/morph-proposal/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.8.0"
 ---
 
 # morph-proposal

package/framework/skills/core/morph-review/SKILL.md

@@ -4,7 +4,7 @@ description: Conduz a fase de revisão e produz o review-report.md para o Gate 3
 version: core
 when-to-invoke: ao iniciar a fase review, após todas as tasks de tasks.json estarem com status `done`
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.8.0"
 ---
 
 # morph-review
@@ -74,6 +74,12 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
    - **Leia primeiro** `.morph/features/{feature}/4-review/evaluator-report.md` — é o valor de retorno autoritativo, não a mensagem de texto do dispatch (que é cortesia, útil só quando chega inteira). Os scores por dimensão e o composto do review-report vêm **desse arquivo**, não da sua auto-avaliação. Se o arquivo vier ausente, oco, ou sem os scores por dimensão, registre a falha de protocolo na seção de método do review-report e re-despache.
 
 5. Produza `review-report.md` em `.morph/features/{feature}/4-review/` com:
+   - **`**Reviewed-SHA:** {git rev-parse HEAD}`** — o commit que você revisou, **obrigatório**.
+     Um review revisa uma ÁRVORE, e a árvore anda: sem esse carimbo, um relatório escrito antes
+     da última task fica no repo afirmando números e cobertura que já não valem. O
+     `morph-spec approve {feature} review` compara o carimbo com o HEAD e **recusa** se divergirem
+     (aconteceu de verdade: relatório de `b30ac6e` sobrevivendo à T3, que inverteu o default de
+     uma regra de negócio, e ainda dizendo `976/976` quando eram 982).
    - Scores por dimensão (arquitetura, contratos, qualidade, cobertura)
    - Score composto final
    - Lista de itens bloqueantes (se houver) — com descrição e critério de resolução

package/framework/skills/core/morph-stack-scan/SKILL.md

@@ -4,7 +4,7 @@ description: Varre o codebase existente, detecta stack atual, compara com o stac
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.8.0"
 ---
 
 # morph-stack-scan

package/framework/skills/core/morph-standards/SKILL.md

@@ -4,7 +4,7 @@ description: Localiza e carrega um standard específico do STANDARDS.json sob de
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.8.0"
 ---
 
 # morph-standards

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "8.6.0",
+  "version": "8.8.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",

package/src/commands/project/claim.js

@@ -0,0 +1,91 @@
+/**
+ * `morph-spec claim [feature] [--release] [--list]` — the manual half of
+ * advisory feature ownership (B1).
+ *
+ * Claims are acquired and heartbeaten AUTOMATICALLY (SessionStart hook +
+ * telemetry hook), so the operator never has to remember anything. This command
+ * exists for the case automation cannot cover: a session that died without
+ * releasing, leaving a claim that keeps warning everyone until its TTL expires.
+ *
+ * Read-only by default (`--list`); the only mutation is `--release`.
+ * Always exits 0 except on a genuine misuse — the claim system is advisory and
+ * must never become a source of hard failures.
+ */
+
+import chalk from 'chalk';
+import { execSync } from 'child_process';
+import { resolve } from 'path';
+import { isGitRepo, resolvePrimaryRoot } from './worktree.js';
+import { listClaims, releaseClaim, claimAge } from '../../../framework/hooks/shared/claim-registry.js';
+
+/** Resolve the repo's shared git common dir — where claims live. */
+function gitCommonDirOf(cwd) {
+  const root = resolvePrimaryRoot(cwd);
+  const common = execSync('git rev-parse --git-common-dir', { cwd: root, stdio: 'pipe' }).toString().trim();
+  return common ? resolve(root, common) : null;
+}
+
+/**
+ * @param {string|undefined} feature
+ * @param {{ release?: boolean, list?: boolean, json?: boolean, cwd?: string }} [options]
+ */
+export function claimCommand(feature, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  if (!isGitRepo(cwd)) {
+    console.log(chalk.gray('Fora de um repositório git — não há registro de claims.'));
+    process.exit(0);
+  }
+
+  let gitCommonDir = null;
+  try {
+    gitCommonDir = gitCommonDirOf(cwd);
+  } catch { gitCommonDir = null; }
+  if (!gitCommonDir) {
+    console.log(chalk.gray('Não foi possível resolver o git common dir — nenhum claim a mostrar.'));
+    process.exit(0);
+  }
+
+  if (options.release) {
+    if (!feature) {
+      console.error(chalk.red('\n❌ --release exige o nome da feature: morph-spec claim <feature> --release\n'));
+      process.exit(1);
+    }
+    const released = releaseClaim(feature, { gitCommonDir });
+    if (options.json) {
+      console.log(JSON.stringify({ feature, released }));
+      process.exit(0);
+    }
+    console.log(released
+      ? chalk.green(`\n✅ Claim de "${feature}" liberado.\n`)
+      : chalk.yellow(`\n⚠️  Nenhum claim registrado para "${feature}" — nada a liberar.\n`));
+    process.exit(0);
+  }
+
+  // Default and --list are the same read: the whole board, or one feature.
+  const all = listClaims(gitCommonDir);
+  const rows = feature ? all.filter((c) => c.feature === feature) : all;
+
+  if (options.json) {
+    console.log(JSON.stringify(rows));
+    process.exit(0);
+  }
+
+  if (!rows.length) {
+    console.log(chalk.gray(feature
+      ? `Nenhum claim para "${feature}".`
+      : 'Nenhuma feature reclamada — nenhuma sessão registrada.'));
+    process.exit(0);
+  }
+
+  const col = (s, w) => String(s ?? '-').padEnd(w);
+  console.log(chalk.white.bold(col('FEATURE', 24) + col('ESTADO', 10) + col('VISTO HÁ', 12) + col('PID', 9) + 'ONDE'));
+  for (const c of rows) {
+    const state = c.live ? chalk.yellow('viva') : chalk.gray('morta');
+    console.log(
+      col(c.feature, 24) + state + ' '.repeat(Math.max(1, 10 - (c.live ? 4 : 5)))
+      + col(claimAge(c), 12) + col(c.pid, 9) + (c.path || '-'),
+    );
+  }
+  console.log(chalk.gray('\nClaims são AVISOS, nunca bloqueios. Claim órfão: `morph-spec claim <f> --release`'));
+  process.exit(0);
+}