Harness Phase Upgrades Grill Log

Initial Situation

Harness already has repo-local phase wrappers, scaffold packs, wiki routing, default skills, and validation gates. A recent comparison against Superpowers and Compound Engineering Plugin identified two narrow upgrades worth grilling before implementation:

• Superpowers-style TDD hard law.
• Compound-style typed learning loop and refresh model.

The current direction is to steal schemas, gates, and artifact lifecycles, not the full operating models. Harness should preserve its advantage: repo-local scaffold context, phase wrappers, skill packs, routed wiki authority, and CLI-driven receiving/updating.

Branch: TDD Hard Law

Q1

Question: Should Harness's TDD hard law apply to every production-code edit, or only to behavior-changing work?

Accepted answer:

• Apply the hard law to actual code changes that can change behavior: features, bugfixes, refactors with behavior risk, and other behavior-changing production-code edits.
• Allow explicit escapes for docs-only, formatting-only, generated-code-only, config-only, scaffold/bookkeeping-only, or truly non-testable tasks through reason_not_testable.
• The hard law is not only stricter skill prose. Harness should make RED/GREEN auditable through phase artifacts.
• Superpowers achieves strictness through context injection, mandatory skill routing, TDD-shaped plans, execution discipline, and completion verification.
• Harness should implement the equivalent through tdd, create-plan, implement-spec, review-phase, default quality packs, and durable wiki/spec artifacts.
• Axiom: for behavior-changing implementation work, a task is incomplete until it has RED evidence and GREEN evidence, or an explicit accepted reason_not_testable.
• Axiom: if behavior-changing production code was written before RED evidence, restart that implementation slice from the failing test or record why the slice is genuinely non-testable.

Q2

Question: Should the TDD hard law be enforced only by skill and phase instructions, or should Harness also add a machine-checkable validation pass over PLAN.md and IMPLEMENTATION-NOTES.md?

Accepted answer:

• Start with phase-level hard enforcement, not a CLI parser or markdown validator.
• tdd should carry the hard law language.
• create-plan should require explicit RED/GREEN evidence fields in each behavior-changing task.
• implement-spec should block task completion unless the task has RED evidence and GREEN evidence, or an explicit reason_not_testable.
• review-phase should fail behavior-changing tasks that lack proof instead of treating missing evidence as advisory feedback.
• Park machine-checkable CLI/schema validation until the evidence shape stabilizes through real implementation runs.
• Axiom: hard enforcement can begin as a phase contract before it becomes a parser-backed CLI validation gate.

Q3

Question: Where should RED/GREEN proof live?

Accepted answer:

• Split intent from evidence.
• PLAN.md task metadata stores the intended TDD contract:
  • tdd_target
  • red_command
  • expected_red_failure
  • green_command
  • reason_not_testable when needed
• PLAN.md task log stores the short actual evidence:
  • red_evidence
  • green_evidence
  • touched files
  • deviations
• IMPLEMENTATION-NOTES.md stores non-obvious narrative only:
  • why a test shape changed
  • why a task was non-testable
  • why code-before-RED had to be restarted or accepted
  • surprising validation details
• Axiom: PLAN.md is the auditable execution board for task completion proof.
• Axiom: IMPLEMENTATION-NOTES.md preserves judgment, surprises, and deviations, not a duplicate task database.

Q4

Question: When implement-spec discovers behavior-changing production code was written before RED evidence, what should happen?

Accepted answer:

• Automatically recover through the TDD loop instead of only blocking the task.
• Write a RED test that proves the actual intended public result, not an implementation detail or a weak snapshot of the current code.
• Patch the production code until that intended-result test passes.
• Record the recovery in PLAN.md task evidence:
  • what intended result the RED test proves
  • the RED command and failure
  • the GREEN command and pass
  • any production code reconciled after the missing-RED discovery
• If the existing production code already makes the new test pass, the agent must not fake RED. It must either isolate the pre-fix state, revert the task slice enough to observe RED, or record why a true RED step cannot be reconstructed and treat that as an explicit deviation.
• reason_not_testable cannot be used just because the agent forgot to write RED first.
• review-phase treats unexplained code-before-RED or fake RED evidence as a blocking finding.
• Axiom: code-before-RED recovery should produce a real intended-behavior test and a passing implementation, not just a written apology.

Q5

Question: Should the final TDD task schema use tdd_target, red_command, expected_red_failure, green_command, reason_not_testable, red_evidence, and green_evidence, plus a compact status field?

Accepted answer:

• Yes.
• The final task schema should use:
  • tdd_status
  • tdd_target
  • red_command
  • expected_red_failure
  • green_command
  • reason_not_testable
  • red_evidence
  • green_evidence
• tdd_status values are:
  • required
  • not_testable
  • recovered
  • not_applicable
• tdd_status gives implement-spec and review-phase a compact state before reading the full evidence.
• Use recovered when code-before-RED recovery produced an intended-result test and patch-to-pass evidence.
• Use not_applicable only for tasks outside the hard-law scope, such as docs-only, formatting-only, scaffold/bookkeeping-only, or generated-code-only work.
• The TDD hard-law branch is closed for implementation planning.

Branch: Removed Scope

• Strategy and ideation are out of this initiative.
• Product pulse is out of this initiative.

Branch: Knowledge Loop

Q6

Question: Should Harness create a separate Compound-style docs/solutions/ tree, or keep learning artifacts inside the existing routed wiki/project docs model?

Accepted answer:

• Keep learning artifacts inside the existing docs-ingest-phase and routed wiki/project docs model.
• Do not create a separate docs/solutions/ tree.
• Add a learning-artifact substep inside docs-ingest-phase.
• Store canonical learning in routed wiki/project pages.
• Keep memory notes as compact gotchas and routing aids, not canonical knowledge.
• Add duplicate detection before writing.
• Add refresh outcomes later:
  • keep
  • update
  • consolidate
  • replace
  • delete
  • mark_stale
• Axiom: learning artifacts should compound inside the existing Harness docs authority, not create a parallel knowledge surface.

Q7

Question: Should compounding rely only on future-use hooks from each learning artifact, or should phase skills also be instructed to consume prior learnings during discovery, planning, debugging, and review?

Accepted answer:

• Require both a consumer instruction and a future-use hook.
• Phase skills should explicitly scan relevant prior learnings when they enter discovery, planning, debugging, or review:
  • requirements-phase and requirements-grill when requirements depend on known project/domain behavior
  • create-spec during orientation
  • create-plan before task synthesis
  • debugging-phase before or during hypothesis construction
  • review-phase while gathering evidence and local guidance
• Every learning artifact must expose at least one future-use hook:
  • link from a relevant routed flow, concept, or runbook
  • link from spec or implementation notes
  • compact memory note for a hard-to-discover gotcha
  • update a phase skill reference when the learning changes agent behavior
  • add a prevention/test note to a validation or review checklist
• Root AGENTS.md should carry only the compact invariant: when routed learning artifacts exist, consult relevant learnings during discovery, planning, debugging, and review.
• Detailed mechanics belong in shared phase skills and docs-ingest references, not root prompt bloat.
• Axiom: a learning is not closed until future phases know to look for it and at least one artifact points back to it.

Q8

Question: Should Harness use two learning artifact tracks, bug and knowledge, like Compound?

Accepted answer:

• Yes, with Harness-native field names and wiki/source metadata.
• Use learning_type: bug | knowledge.
• Shared fields:
  • date
  • domain
  • module
  • component
  • severity
  • source
  • referenced_files
  • future_use_hooks
• Bug-only fields:
  • symptoms
  • root_cause
  • resolution_type
  • prevention
• Knowledge-only fields:
  • applies_when
  • guidance
  • why_it_matters
• Compound's schema shape is useful, but Harness should map it into routed wiki authority, domain metadata, source links, and the future-use hook contract.

Q9

Question: Should learning refresh be a separate phase/skill later, or integrated into docs-ingest-phase now?

Accepted answer:

• Integrate learning refresh directly into docs-ingest-phase.
• docs-ingest-phase is the compounding engine: it captures new learning, deduplicates it, updates old learning, consolidates overlap, replaces stale guidance, and marks ambiguous knowledge stale.
• Do not create a separate $knowledge-refresh-phase for this initiative.
• Every learning ingest must check existing routed learning artifacts before writing a new page.
• Existing learning artifact outcomes:
  • keep when current learning is still accurate and the new work adds nothing durable
  • update when the same learning needs fresher facts, references, examples, or prevention notes
  • consolidate when overlapping learnings should become one canonical page
  • replace when old guidance is misleading and a clear successor exists
  • delete only when the artifact is clearly obsolete, unreferenced, and no longer useful
  • mark_stale when evidence is ambiguous or a human decision is needed
• docs-ingest-phase may run scoped refresh only around the current ingest's domain/module/component/referenced files, not a broad repo-wide sweep by default.
• Axiom: compounding happens inside docs-ingest-phase by maintaining the learning set as part of every relevant ingest.

Q10

Question: Should docs-ingest-phase write memory notes for every learning artifact?

Accepted answer:

• No.
• Memory notes are only for hard-to-discover gotchas or routing aids that future agents are likely to miss during normal repo/wiki search.
• Canonical knowledge lives in the routed learning artifact.
• Future-use hooks provide navigation and discovery.
• Memory notes provide compact gotcha/routing support only.
• Do not write a memory note when the routed page and future-use hooks are enough.
• Axiom: memory must not become a hidden second learning tree.
• The knowledge-loop branch is closed for implementation planning.