القائمة
WHEN: A PRD has been locked by intake and needs Council negotiation. HARD-GATE: Every locked PRD goes through Council (4 surfaces + 5 contracts negotiated). No skipping.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | forge-council-gate |
| description | WHEN: A PRD has been locked by intake and needs Council negotiation. HARD-GATE: Every locked PRD goes through Council (4 surfaces + 5 contracts negotiated). No skipping. |
| type | rigid |
| version | 1.0.6 |
| preamble-tier | 3 |
| triggers | ["council gate","spec is ready for build","freeze spec gate"] |
| allowed-tools | ["Bash","Read","Write","AskUserQuestion"] |
This skill lists AskUserQuestion in allowed-tools — canonical for Claude Code and skill lint. Map to the host’s blocking interactive prompt per skills/using-forge/SKILL.md Blocking interactive prompts (Cursor AskQuestion; hosts without the tool: numbered options + stop). See using-forge Interactive human input.
Cross-cutting assistant dialogue: docs/forge-one-step-horizon.md — using-forge Multi-question elicitation items 4–8.
Rule: Every locked PRD must be negotiated by Council.
| Rationalization | The Truth |
|---|---|
| "This is a backend-only change, we don't need all 4 surfaces" | Backend changes affect caching, APIs, schemas, infra. All 4 surfaces always matter. |
| "We already have API contracts, council will just rubber-stamp them" | Council doesn't rubber-stamp. It negotiates: backend may need different schema, web may need different API shape. |
| "Single-surface reasoning is sufficient, council is overkill" | Single-surface reasoning is local optimization. Council finds conflicts (trade-offs) that single-surface misses. |
| "The contracts are straightforward, we can skip negotiation" | Straightforward to whom? Backend finds performance issues that web didn't see. Web finds usability issues backend didn't anticipate. |
| "Council takes too long, we're on a deadline" | A day in council prevents a month of integration rework. Council schedule is non-negotiable. |
| "The previous spec passed council, this is just a patch" | Every PRD gets fresh council. Patches can break prior assumptions. Re-negotiate or escalate. |
| "We can do council discussions async, no need to synchronize" | Async discussion misses real-time insight. Surfaces need to hear each other. Council is synchronous or it's not council. |
| "Just one surface can't attend council this sprint, we'll get them next time" | All 4 surfaces must be present. Missing surface = missing veto. No exceptions. |
| "The contracts are defined by the previous system, we can't change them" | Every contract is renegotiable. If the new PRD requires a different contract, negotiate it. Don't lock to old contracts. |
| "We already negotiated with stakeholders, council is redundant" | Stakeholder agreement != technical consensus. Council surfaces conflicts in tech that stakeholder agreement misses. |
NO IMPLEMENTATION STARTS BEFORE COUNCIL COMPLETES. A SHARED-DEV-SPEC WITH ANY UNRESOLVED TBD OR MISSING CONTRACT IS NOT A LOCKED SPEC — IT IS A DRAFT.
If you notice any of these, STOP and do not proceed:
~/forge/brain/prds/ before invoking council.~/forge/brain/ before any surface proceeds to tech planning.[ADJACENCY-SCAN], missing cohort artifacts, or SPEC_INFERENCE-only segmentation per docs/adjacency-and-cohorts.md. STOP. Complete State 2.6 + council checks before spec-freeze.terminology.md (product/domain) has unresolved open doubts when those terms appear in success criteria or contract-facing copy — STOP. Resolve per docs/terminology-review.md or intake-interrogate; do not lock shared-dev-spec on ambiguous customer-facing names. (Forge process terms: forge-glossary.)[TERMINOLOGY] in conductor.log (standalone /council): Do not append from this skill — only council-multi-repo-negotiate Step 5.4 (end of council) writes the line, so a council run does not leave two [TERMINOLOGY] lines with conflicting open_doubts. The hook prompt-submit-gates.cjs uses the last [TERMINOLOGY] line in the file only.
Before preparing council materials, check whether a codebase scan exists and is fresh. Council surface agents need the module map to reason about where to place new code, which hubs will be affected, and what the existing architecture patterns are.
SCAN_FILE=~/forge/brain/products/<slug>/codebase/SCAN.json
if [ -f "$SCAN_FILE" ]; then
SCAN_DATE=$(cat "$SCAN_FILE" | grep '"scanned_at"' | grep -o '"[0-9T:Z-]*"' | tr -d '"')
SCAN_AGE=$(( ( $(date -u +%s) - $(date -d "$SCAN_DATE" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%SZ" "$SCAN_DATE" +%s 2>/dev/null) ) / 86400 ))
echo "Codebase scan: $SCAN_DATE ($SCAN_AGE days ago)"
else
echo "Codebase scan: NOT FOUND"
fi
SCAN.json may use a nested shape: per-role data lives under repos.<role> with top-level aggregates (scanned_at, source_files, …) for backward compatibility. The grep snippet above still finds scanned_at on typical files; when reading the file in full, prefer repos.<role> for role-specific freshness.
Decision:
| Situation | Action |
|---|---|
| Scan not found AND this is a greenfield product (first PRD) | No scan needed. Proceed to council. |
| Scan not found AND this is an existing codebase | Warn surface agents: ⚠️ No codebase scan. Surface agents will reason without architecture context — tech plans may conflict with existing structure. Recommend: run /scan <slug> before council. Do NOT block council. |
| Scan is <7 days old | Surface scan context to agents. Proceed to council. |
| Scan is 7-30 days old | Warn: ⚠️ Scan is N days old — refresh recommended (/scan <slug>). Do NOT block council if user acknowledges. |
| Scan is >30 days old | Prompt user: "Codebase scan is N days old. Running council on stale architecture data risks tech plans that don't fit the codebase. Refresh now? (yes / proceed anyway)" |
Never block council — the scan gate is advisory. Flag staleness, provide the data you have, proceed.
When SCAN.json exists: Run python3 tools/verify_scan_outputs.py ~/forge/brain/products/<slug>/codebase (up to 3 attempts, 1s apart). If it still fails, warn loudly: consolidated markdown/JSON did not land — re-run /scan before relying on modules/*.md for council file paths. Proceeding without refresh is allowed only if the human acknowledges explicit risk in writing (e.g. context-loaded.md).
spec-freeze): Ensure the task folder will receive ~/forge/brain/prds/<task-id>/parity/ with external-plan.md OR completed checklist.md (copy docs/parity-checklist-template.md) OR waiver.md (parity_waiver: true + owner + reason). Council + contracts must not be treated as “done” if the only artifact is a thin shared-dev-spec that never absorbed the org’s detailed plan — see spec-freeze Step 0.ALWAYS invoke /council-multi-repo-negotiate — do not run individual surface reasonings.
The skill will:
Input: Surface proposals (from skill output)
For each conflict:
Consensus paths:
Escalation triggers (invoke dreamer):
shared-dev-spec.md frontmatter. Contracts with status: negotiated are already closed — do not re-open them. Start from the first open contract.When a contract is in disputed state and a dreamer escalation is pending:
contract_api_status: disputed
dispute_escalation_id: DREAM-<timestamp>-<slug>
dispute_reason: <one-line description of the disagreement>
negotiated while a dispute is pending.open contracts that are not party to the dispute.negotiated (if resolved) or open (if sent back for re-negotiation), remove dispute_escalation_id, and log [P2-DISPUTE-RESOLVED] task_id=<id> contract=<name> decision=DREAM-<id> to conductor.log.spec-freeze while any contract is in disputed state, even if all others are negotiated.Before locking spec, verify:
design_intake_anchor present in prd-locked.md per intake-interrogate Q9 (proves design source-of-truth was asked)/council-multi-repo-negotiate skill invokedshared-dev-spec.md YAML frontmatter after each contract closes:
contract_api_status: negotiated # or: open | disputed
contract_events_status: negotiated
contract_cache_status: negotiated
contract_db_status: negotiated
contract_search_status: negotiated
open = not yet discussed; disputed = dreamer escalation pending; negotiated = locked.Situation: Two or more surfaces have irreconcilable positions. Backend insists on schema X, web insists on schema Y, neither will move.
Example: Backend: "Single monolithic table for performance"; Web: "Normalized tables for flexibility" — both have valid technical reasons.
Do NOT: Pick one arbitrarily. Deadlock is a signal that the decision matters and needs authority to resolve.
Action:
Situation: Required stakeholder or surface representative is unavailable during council session.
Example: Infra engineer called to incident; web stakeholder dropped off call; new requirement surfaces from product who wasn't initially consulted.
Do NOT: Proceed with incomplete council. Missing surface = missing constraints, vetos, requirements.
Action:
Situation: Council runs but key conflicts surface late. Surfaces need time to research alternatives or consult external teams. One session is insufficient.
Example: "This API contract requires infrastructure we haven't built yet; we need 2 days to scope the work" — valid concern, but not resolvable in 1-hour council.
Do NOT: Force consensus under time pressure. Premature lock creates technical debt later.
Action:
Output: SPEC LOCKED (ready for per-project tech planning) or BLOCKED (deadlock without dreamer input, incomplete attendance, unresolvable conflict awaiting follow-up research)
Symptom: The backend surface proposes a new REST API contract (e.g., POST /auth/mfa/enable) but a prior brain decision D007 defines POST /auth/2fa/setup for the same intent. The new contract would create a naming collision or semantic overlap.
Do NOT: Allow the new contract to land without resolving the conflict with the prior decision.
Action:
brain-read — read D007 in full, including its rationalebrain-forget to retire D007 and document the supersession reasonSymptom: Council locked the spec with shared-dev-spec.md. Two days later, the mobile surface discovers the agreed event bus contract requires a native library not available on iOS.
Do NOT: Let the surface silently deviate from the spec during implementation. And do NOT let it quietly drop the feature.
Action:
council_amendment request to the dreamer: "iOS cannot implement X because Y"Before claiming council complete:
shared-dev-spec.md frontmatter. Contracts with status: negotiated are already closed — do not re-open them. Start from the first open contract.shared-dev-spec.md YAML frontmatter after each contract closes:
contract_api_status: negotiated # or: open | disputed
contract_events_status: negotiated
contract_cache_status: negotiated
contract_db_status: negotiated
contract_search_status: negotiated
open = not yet discussed; disputed = dreamer escalation pending; negotiated = locked.Example shared-dev-spec.md frontmatter with per-contract status:
---
task_id: my-feature-task
schema_version: 1
contract_api_status: negotiated # REST endpoints agreed
contract_cache_status: open # TTL policy still disputed
contract_event_status: negotiated # Topic names + schema locked
contract_schema_status: negotiated # DB migration approved
contract_search_status: open # Index mapping TBD
spec_frozen: false # set to true only when ALL contracts = negotiated
---
On session resumption: skip any contract where status: negotiated. Re-enter negotiation only for open or disputed contracts.
status: negotiated in shared-dev-spec.md frontmatter.[P2-SPEC-FROZEN] logged to conductor.log after last contract negotiated.shared-dev-spec.md committed to brain with task_id: anchor.open or disputed state.negotiated were re-negotiated.council-multi-repo-negotiate: Called by forge-council-gate to run contract negotiation per repo pair; gate validates negotiation is complete.spec-freeze: Triggered by forge-council-gate when all 5 contracts reach status: negotiated; logs [P2-SPEC-FROZEN].contract-api-rest: First contract validated by the gate; REST API contract between repos.contract-event-bus: Second contract validated by the gate; event/message contracts.contract-cache: Third contract validated by the gate; cache key and TTL contracts.contract-schema-db: Fourth contract validated by the gate; database schema contracts.contract-search: Fifth contract validated by the gate; search index contracts.conductor-orchestrate: Sequences [P2-SPEC-FROZEN] in the pipeline; forge-council-gate produces the output conductor consumes.docs/conductor-log-format.md: [P2-SPEC-FROZEN] and [P2-SPEC-AMENDED] marker formats logged after council completes.WHEN: You need to detect performance regressions before merge — TTFB, response time, bundle size. Run as part of forge-eval-gate or standalone before raising a PR.
WHEN: A decision is being superseded, deprecated, or has aged out. Archive it without deletion — marks as warm→cold→archived with full audit trail.
WHEN: You are writing a new decision, superseding an old one, or querying relationships across decisions. Create semantic edges between decisions and link concepts across products/projects/time.
WHEN: You are about to make a decision and need to check if prior art or past learnings exist. Recall decisions, patterns, and gotchas from the brain before proceeding.
WHEN: You need to trace the full provenance of a specific decision — who made it, when, why, and what alternatives were considered. Shows why, when, by whom, evidence, alternatives, outcome.
WHEN: You need to record a decision, lock a spec, log an eval run, or document learnings in the brain.